Kendra Orchestration Engine (KOE)

Durable, deterministic, multi-agent execution as an installable Python library.

First release, public. v0.1.0 is published on PyPI and as a GitHub Release (ADR 0021) — see Installation. See Project status.

What this is

KOE runs multi-agent workflows ("swarms"). That combination buys four things ad-hoc agent frameworks do not have:

• Durability — every superstep is checkpointed. A crash resumes from the last barrier instead of losing the run.
• Determinism — agents compute against a frozen state snapshot and emit deltas that merge through order-independent reducers. Concurrency cannot change the result.
• Real parallelism — 100+ agents execute in one superstep, each able to run on a different model.
• Auditability — bitemporal decision records answer "what did the agent know when it decided?"

It is not a prompt-chaining toolkit. It is an execution substrate for long-running, auditable, governed, multi-model agent workflows.

Why not a DAG

A directed acyclic graph cannot express reflection, retries, or multi-turn negotiation — the behaviours real multi-agent systems depend on. The superstep kernel treats cycles as first-class, so execution is a loop rather than a fixed path:

event → decision → branch → parallel agents → merge → feedback → repeat

How it's used

Four tiers, all from from korchestrator import .... Tiers 1–3 run entirely in-process with no service and no network.

# Tier 1 — one-liner. Zero infrastructure.
from korchestrator import Korch
print(Korch().run("Research durable agent execution and summarize the top 3").final_answer)

# Tier 2 — typed swarm builder, per-agent model isolation.
from korchestrator import Swarm, Agent
result = (
    Swarm(objective="Review this PR for security and performance")
    .add(Agent(id="security", role="security-reviewer", model="claude-3.5-sonnet"))
    .add(Agent(id="perf", role="performance-reviewer", model="gpt-4o-mini"))
    .add(Agent(id="lead", role="review-lead"))
    .edges([("security", "lead"), ("perf", "lead")])
    .run(max_supersteps=5)
)

# Tier 3 — the kernel directly, for embedding.
from korchestrator.core import PregelRunner

# Tier 4 — drive a hosted engine (optional, [remote] extra).
from korchestrator.remote import KorchestratorClient

Full surface: docs/specs/04-public-api.md.

Features

Everything below ships and is tested today — see Project status for what's still outstanding. 26 subpackages under src/korchestrator/, each with a single layer and a single responsibility (docs/specs/03-architecture.md):

Capability highlights that fall out of those modules:

• Local or durable execution — the same graph runs synchronously in-process or on a durable workflow engine with crash recovery, pause/resume, and replay, chosen by one config value.
• Per-agent model routing — mix models (and providers) in a single swarm; route explicitly, by algorithm, by semantic similarity, or by your own function.
• Tool use — first-party connectors, MCP servers, and custom connectors behind one bridge with schema validation, timeouts, and rate limiting.
• Governance & HITL — trust scoring and policy checks that can auto-pause a run for human approval (durable runtime only).
• PII/secret redaction — the Shield gate, applied on tool output and context-graph ingest.
• Bitemporal audit trail — the Context Graph answers "what did the agent know when it decided?"
• Streaming — subscribe to transport-agnostic execution events as a run progresses.
• Deterministic testing — MockLM is the default model gateway; nothing touches the network unless you configure a real one.

Installation

pip install "korchestrator[dspy]"
pip install "korchestrator[all]"

No GitHub credential needed — published on PyPI via Trusted Publishing (ADR 0021).

or from a local clone:

git clone git@github.com:Kendralabs/korch-sdk.git && cd korch-sdk
pip install -e '.[dspy]'      # cognitive layer (agents, compiled signatures) — most users need this
pip install -e '.[all]'       # everything

See docs/installation.md for the full extras table, and docs/releases.md for how releases are cut and tagged.

The base install has one runtime dependency. Everything heavy is an optional extra, lazy-imported so import korchestrator stays fast and the kernel stays embeddable. The default configuration runs offline against a deterministic mock model — no keys, no services, no infrastructure.

Windows note. pip install -e '.[dev]' installs console scripts (mkdocs, pytest, ruff, mypy, bandit, pre-commit, …) into your per-user Scripts directory (e.g. %APPDATA%\Python\Python3xx\Scripts). If a bare command isn't found right after install, either run it as python -m <tool> (e.g. python -m mkdocs serve) in the current shell, or add that Scripts directory to your user PATH and open a new terminal. See docs/troubleshooting.md.

Quick start — first run to a passing test suite

A complete, ordered sequence from a clone to a verified local setup. Every step runs offline; none of it needs API keys, Docker, or a deployed service.

# 1. Clone and install (dev extras: every extra + lint/type/test/docs tooling)
git clone <repository-url> && cd korch-sdk
pip install -e '.[dev]'

# 2. Verify the import — works on the base install, no extras, no network
python -c "import korchestrator; print(korchestrator.__version__)"

# 3. Run your first swarm, entirely offline against MockLM
python examples/01_one_liner.py
python examples/02_swarm.py          # typed builder, multiple agents, per-agent models

# 4. Explore the rest of the example set
python examples/03_custom_agent.py   # subclass Agent, override its reasoning step
python examples/04_custom_tool.py    # write and mount a custom tool connector
python examples/05_mcp_tool.py       # discover tools from an MCP server (needs [mcp])
python examples/06_custom_router.py  # write a custom per-agent model router
python examples/07_streaming.py      # consume execution events as a run progresses

# 5. Run the full quality gate the way CI does
ruff check src/korchestrator tests
ruff format --check src/korchestrator tests
mypy --strict src/korchestrator
pytest tests --cov=korchestrator --cov-report=term-missing

# 6. Build and preview the documentation site locally
mkdocs build --strict
mkdocs serve      # → http://127.0.0.1:8000

(Use python -m mkdocs, python -m pytest, etc. in place of the bare command if step 1's console scripts aren't on PATH yet — see the Windows note above.)

Testing a single module

Tests mirror src/korchestrator/<module> one-to-one under tests/unit/<module>/. Run just one module's suite while you're working on it:

pytest tests/unit/core -v          # kernel
pytest tests/unit/providers -v     # MockLM, gateways, identity/sandbox
pytest tests/unit/routing -v       # model routing strategies
pytest tests/unit/tools -v         # Agent Utility Bridge
pytest tests/unit/governance -v    # trust scoring, policy, HITL
pytest tests/unit/clients -v       # remote client contract

Other suites live in tests/integration/, tests/e2e/, tests/regression/, and tests/smoke/. The base-install kernel suite — what must pass with only pydantic installed, no extras — is:

pytest tests/unit/core tests/unit/models tests/smoke

Coverage floor: 90% global, 97% for core/, 99% for models/ — ratcheted up over time, never down. Full command reference: docs/specs/09-testing-and-quality.md.

Project status

v0.1.0 is released and public: the kernel, local and durable runtimes, agents and compiled signatures, model routing, tools/MCP/A2A, streaming, governance, the context graph, the remote client, the test and benchmark suite, and this documentation are all in place, and the release publishes to PyPI and GitHub Releases via Trusted Publishing (ADR 0021).

The project is still 0.x — see Versioning for what that means for compatibility. Current state, including known gaps, is tracked in .claude/memory/PROJECT_STATE.md; the ordered build plan behind it is in docs/specs/ for anyone contributing to the SDK itself.

Versioning. SemVer. While 0.x, a minor release may contain breaking changes — this is stated plainly in every changelog entry that carries one. From 1.0.0 the full compatibility policy applies without exception.

Documentation

The published docs site (docs/, built with MkDocs — mkdocs serve to preview locally):

The engineering record (not published to the docs site — internal, for anyone building the SDK itself):

Contributing

Read docs/specs/01-scope-and-principles.md first — it defines what belongs in this repository and what never will. Follow Quick start above to get installed and green, plus this one extra step:

chmod +x .claude/hooks/pre-commit-check.sh   # once, after cloning — enforces the gates below at commit time

Branches promote forward only: dev (integration) → staging (release candidate) → main (released, and the repository default). Branch off dev as <type>/p<phase>-<slug> and open the PR against dev — GitHub proposes main, which is wrong for feature work. Use Conventional Commits with a phase tag (feat(core): implement superstep kernel + reducers [P2]). Never commit directly to dev, staging, or main, and never bypass the hooks. Every change touching src/ updates .claude/memory/ENGINEERING_LOG.md before it is committed. The full model, including the hotfix exception, is in .claude/rules/branching-and-promotion.md.

Working with an AI coding agent? The repository is configured for it: .claude/CLAUDE.md is the always-on ruleset, .claude/rules/ holds the enforceable constraints, and /phase, /verify, /log, and /adr cover the standard workflow.

Releasing a version

Cut from staging, never from dev or directly on main. scripts/cut_release.py automates the mechanical steps:

# from staging: bump the version, date the CHANGELOG, open the release PR into main
python scripts/cut_release.py prepare --bump patch   # or --bump minor / --bump major / --version X.Y.Z

# after that PR is reviewed and merged: tag main and push it, which triggers .github/workflows/release.yml
python scripts/cut_release.py tag

release.yml builds the wheel and sdist, verifies the built artifact in a clean environment, and publishes a GitHub Release with the wheel, sdist, and SHA256SUMS attached — see Installation for how consumers then install it. Full runbook, including the merge-back step that keeps dev/staging/main in sync afterward: docs/releases.md.

Non-goals

This repository ships one product: the SDK. It will never contain a frontend, a backend, an HTTP server, or deployment manifests for a hosted service. "Deployment" here means publishing package artifacts, not running anything. A hosted engine, if one exists, is a downstream consumer of the published package — see ADR 0007.

License

Apache-2.0 — chosen for its explicit patent grant. See ADR 0003.