Skip to content
ContextUnity

ContextWorker

ContextWorker is the “Hands” of the ContextUnity ecosystem. It provides durable workflow infrastructure, schedule registration, and orchestration for registered tools and Router graphs — all built on Temporal.io.

Durable Workflows

Temporal.io workflows that survive restarts and failures, with automatic retries and state persistence.

Scheduled Jobs

Cron-based recurring tasks registered by project manifests or external modules.

gRPC Service

Trigger and monitor workflows from other services via ContextUnit protocol.

Tool & Graph Orchestration

Execute registered tools inside the Worker runtime and call compiled Router graphs durably.

Architecture

src/contextunity/worker/
├── __main__.py          # Entrypoint
├── cli.py               # CLI commands (Typer)
├── config.py            # WorkerConfig (Pydantic settings)
├── service.py           # gRPC WorkerService
├── server.py            # gRPC server setup
├── schedules.py         # Temporal schedule management
├── schemas.py           # Request/response schemas
├── interceptors.py      # gRPC interceptors
│
├── core/
│   ├── registry.py      # WorkerRegistry, ModuleConfig, plugin discovery
│   ├── worker.py        # Temporal client setup and worker creation
│   ├── worker_sdk.py    # Worker SDK helpers
│   └── brain_token.py   # Brain token utilities
│
├── engines/             # Pluggable execution backends
│   ├── base.py          # BaseEngine protocol
│   ├── temporal_engine.py  # Temporal workflow engine
│   └── huey_engine.py   # Huey task queue engine
│
└── jobs/
    ├── orchestrator.py  # Generic local-tool / Router-graph orchestration
    └── retention.py     # Retention helpers

Key Design Principle

Worker contains NO business logic. It provides infrastructure only.

Business logic lives in domain packages that register workflows and schedules explicitly.

Modules register themselves via the WorkerRegistry and are discovered at startup.