Conductor Engine

A minimal, installable orchestration runtime for task execution, capability loading, guardrails, storage abstractions, and future agent and policy layers.

AI Collaboration

This project is AI-enhanced. A significant portion of the code, tests, and documentation was written with AI assistance as part of an intentional human-AI collaborative workflow.

Roadmap Status

condor-tui already exists; Phase 4 is focused on aligning it to stable, versioned engine control-plane contracts.

Next: Phase 8 — TBD.

See the full roadmap for phase scope, rationale, and backlog details.

Quick Start

python3.14 -m venv .venv
source .venv/bin/activate
pip install -e .
cond run examples/echo.yaml
cond workflow run examples/workflow-echo.yaml

Use man cond for the stable CLI reference, cond help for runtime-aware command and capability help, and cond --help for standard flag usage.

HTTP API

The engine ships a full control-plane HTTP API built on FastAPI. Install the [api] extra and start the server:

pip install -e ".[api]"
cond serve                        # binds to 127.0.0.1:8080 by default
cond serve --host 0.0.0.0 --port 8080

Interactive docs are available at http://localhost:8080/docs once the server is running.

Endpoint groups

Multi-engine fleet

Register remote Conductor Engine instances as nodes and route tasks by tag constraints:

# Register a worker node
curl -X POST http://coordinator:8080/v1/engines \
  -H "Content-Type: application/json" \
  -d '{"name": "worker-gpu-01", "base_url": "http://10.0.0.5:8080", "tags": {"pool": "gpu", "region": "us-east-1"}}'

# Submit to best matching node
curl -X POST http://coordinator:8080/v1/engines/tasks/run \
  -H "Content-Type: application/json" \
  -d '{"name": "infer", "capability": "echo", "input": {}, "engine_tags": {"pool": "gpu"}}'

SSE event stream

curl -N http://localhost:8080/v1/events
curl -N "http://localhost:8080/v1/events?types=task_completed,task_failed"

Docker

A Dockerfile and .dockerignore are included at the repo root. The image uses python:3.14-slim on linux/arm64 (Apple Silicon) and linux/amd64.

# Build
docker build -t conductor-engine:latest .

# Run
docker run -p 8080:8080 conductor-engine:latest
# API docs: http://localhost:8080/docs

# Pass a custom store path or capabilities config
docker run -p 8080:8080 \
  -v "$PWD/.conductor:/data" \
  conductor-engine:latest \
  cond serve --host 0.0.0.0 --port 8080 --store /data/tasks.json

Architecture At A Glance

sequenceDiagram
    actor User
    participant CLI as cond workflow run
    participant ORCH as WorkflowOrchestrator
    participant PLAN as Planner
    participant WORK as Worker
    participant SUP as TaskSupervisor
    participant CAP as Capability
    participant STORE as TaskStore

    User->>CLI: workflow.yaml
    CLI->>ORCH: run(WorkflowGoal)
    ORCH->>PLAN: plan(goal, PlannerContext)
    PLAN-->>ORCH: PlanResponse(steps)

    loop for each PlanStep
        ORCH->>WORK: work(step_name, WorkerContext)
        WORK-->>ORCH: WorkerResponse(TaskSubmission)
        ORCH->>SUP: run_submission(submission)
        SUP->>CAP: validate_input -> execute
        CAP-->>SUP: CapabilityResult
        SUP->>STORE: save(TaskRecord)
        SUP-->>ORCH: TaskRecord
    end

    ORCH-->>CLI: WorkflowResult

What You Get

• Generic task contracts and a supervisor runtime that stays small and composable.
• Built-in echo, filesystem, http, and optional memory capabilities.
• A workflow layer with planner, worker, and validator interfaces over the same supervisor path.
• Local JSON task storage and an in-memory queue for straightforward local operation.
• A cond CLI with task execution, workflow execution, capability discovery, dynamic help, and native manpage support.
• A full FastAPI control-plane HTTP API (engine/api/) with SSE event streaming, versioned read models, control actions, and multi-engine cluster routing.
• A Dockerfile for containerised deployment on arm64 and amd64.

Docs And Examples

• Examples for runnable tasks and workflows.
• Phase 3 examples: workflow-parallel.yaml shows parallel fan-out with a barrier step, and capability-execution-controls.yaml shows per-capability execution controls for cond --config.
• Roadmap for phase planning and backlog tracking.
• Architecture diagrams for the full system view.
• CLI reference for command-focused documentation.
• PyPI project page for published releases.

Built With Conductor Engine

home-ai-control-plane is the motivating downstream system: a policy-governed, multi-agent AI control plane running on a Raspberry Pi 5 for personal digital workflows, home-lab services, and smart-home integrations.

See the use case write-up for how the engine maps to that system.

Development Notes

• Python support now targets 3.14+.
• The repo convention is a single root virtualenv: python3.14 -m venv .venv.
• Coverage and license badges can be added once coverage reporting and license metadata are published in-repo.