conductor-engine 0.11.0

Minimal orchestration runtime extracted from the Home AI Control Plane.

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

Phase	Status	Focus
Phase 1: Core Runtime	Complete	Single-process task execution, core capabilities, guardrails, local storage, and baseline CLI support.
Phase 2: Workflow Layer	Complete	Planner, worker, validator, and orchestrator contracts over the existing supervisor path.
Phase 3: Production Hardening	Complete	Observability, policies, pluggable stores, approvals, and parallel workflow execution.
Phase 4: TUI	Planned	Terminal-first operations and live visibility into a running Conductor instance.
Phase 5: Autonomous Operation	Planned	Self-enforcing policy, recovery, auditability, and unattended execution paths.
Phase 6: Guild Layer	Planned	Cross-project failure learning and role-scoped knowledge sharing.
Phase 7: Remote Deployment and Protected Operation	Planned	Remote-first API, protected multi-tenant operation, and hardened deployment targets.

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.

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.

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.