Forum

Brand assets: .github/assets/banner.svg, docs/brand/forum-mark.svg, and docs/brand/forum-hero.png.

Agent fleets with routing, quality gates, prose contracts, and a replayable causal ledger.

PyPI license CI downloads

forum is a zero-dependency orchestration engine for fleets of agents: it routes a plain request to the right lane, plans a dependency graph into parallel waves, and runs it across model-agnostic executors (any command, any OpenAI-compatible server, the Anthropic API). Runs carry bounded budgets, witnessed model-tier escalation, expert delivery profiles that keep answers on contract, and checkpoints that let a crashed run resume where it stopped. An always-on daemon exposes the same engine over HTTP and MCP, driven by a single forum command. Every run writes a replayable causal ledger you can re-check.

Project Telos | gather | crucible | index | forum | telos | learn | emet | buildlang

Features

• One command, three model backends. forum submit "ship a login API" --cmd "ollama run llama3" plans the request, runs it across agents, and returns one synthesized answer. Swap --cmd for --chat-url (any OpenAI-compatible server) or --api (Anthropic). A local CLI needs no account.
• Tiered executors. Route task agents to cheap, capable, and frontier models by roster tier: --cheap-cmd, --capable-cmd, --frontier-cmd, or per-tier chat endpoints. Put the whole policy in a TOML file and load it with --runtime-config; forum runtime inspect explains the merged policy before anything runs.
• Crash-safe runs. Runs checkpoint at wave boundaries and resume from the durable ledger, reusing every task already witnessed as successful and re-running only the rest.
• Human-in-the-loop approvals. Pause a run at a wave boundary until you approve, edit, or reject it: forum gate list / approve / edit / reject. Gates can carry durable deadlines with a witnessed auto-decision on expiry, so an unattended run never stalls silently. See docs/GATE-DEADLINES.md.
• Campaigns. Declare a multi-project campaign as a JSON feature graph, then drive it to a fixed point: forum campaign declare / status / next / run / ingest-status. Cycles are caught up front; external project status can be ingested without execution.
• Bounded everything. RunBudget caps a run by model calls and wall clock. ContextBudget admits, trims, or omits request context, per-task context, upstream injection, and synthesis inputs under approximate-token caps. forum context preflight estimates the pressure before you spend a model call.
• Codex route-preflight skill. A standalone reviewed ZIP lets Codex hosts preview Forum route, context pressure, runtime readiness, and the prose contract before spending model calls. Future engine releases that include this source change also carry the same asset as package data. The helper is advisory only and never submits work.
• Delivery quality checks. A deterministic concision floor flags verbose answers; an opt-in reviser tightens them, accepted only if the shorter version still covers the request. Expert delivery profiles (operator, engineer, researcher, executive) check the final answer against a local prose contract, selected from the route by default.
• Deterministic routing with a human contract. forum route picks a route from a 28-route default roster without a model, and attaches a forum.route-frame/v1 frame: domain, intent, posture, delivery profile, runtime tier, and an embedded communication contract that synthesis follows.
• Witnessed escalation. Every result records the model that produced it; a failed task escalates up a ladder of stronger executors on an auditable verdict.
• Always-on surfaces. One daemon (stdlib asyncio, no framework) serves the engine over HTTP; forum mcp exposes the same tools over MCP (stdio), a thin adapter over the HTTP surface so the two cannot drift.
• Run rooms and capsules. forum ledger room --brief projects the latest run into a readable brief with state, risk, and deterministic next actions. forum ledger capsule compacts a run into a reusable context brief for the next one.
• Zero dependencies. Pure standard library at runtime. Python 3.11+.

Install and quickstart

pip install forum-engine

Routing and the ledger commands need no model:

forum route "build the auth endpoint and the database schema"

{
  "decided": "backend",
  "confidence": 0.6,
  "needs_escalation": false,
  ...
}

Answer a request with a local model (no account needed), then read the record:

forum submit "ship a login API" --cmd "ollama run llama3"
forum ledger show --limit 20
forum ledger verify
forum ledger room --brief

Run the daemon or the MCP server over the same engine:

forum serve --chat-url http://localhost:11434/v1/chat/completions --model llama3
forum mcp --cmd "ollama run llama3"

forum --help lists the full surface: status, doctor, demo, humanize, route, submit, serve, mcp, context, runtime, ledger, gate, campaign, bench, and bench-deep-verify. From a source checkout the same CLI is available as python -m forum. See RUNNING.md for real-model setups and USAGE.md for the full command reference.

Codex route-preflight skill asset

The standalone skill release path is a GitHub Release asset, not a forum-engine package release. The intended tag is forum-route-preflight-v0.1.0, with forum-route-preflight-skill-20260907-final.zip attached and the release marked --latest=false. That ZIP can be downloaded and extracted without cloning this repository or installing the engine source.

Engine package assets are separate. The next normal forum-engine release that includes this source change will carry the same reviewed files at forum/skills/forum-route-preflight/, plus forum/skills/forum-route-preflight.sha256 for the four reviewed file hashes. The standalone ZIP does not bump pyproject.toml, does not change src/forum/__init__.py, and does not publish to PyPI.

The skill was validated against the forum-engine==1.13.0 CLI/API shape. It previews route, context pressure, runtime readiness, and delivery-profile prose checks; it keeps decision.safe_to_submit: false, never calls forum submit, and never runs the configured model command. Failed subprocess diagnostics in its shareable receipt contain only exit code, byte counts, and SHA-256 digests of raw diagnostic bytes. Successful JSON is scrubbed for exact helper-supplied task text, paths, runtime commands, chat URLs, model names, API-key environment variable names, and the current values of those supplied API-key variables. It is not a universal secret detector for transformed or previously unknown values.

See USAGE.md for download, extraction, and checksum commands.

How a run works

forum submit turns one plain request into one answer, and leaves behind a record of everything that produced it. This is the path a request takes.

The edge that loops back is escalation, and what makes it auditable is where it starts. A task does not climb to a stronger model because a model reported low confidence. It climbs because a judge wrote a verdict into the ledger, that verdict said the result failed, and the retry is chained to it. Read the record later and the reason a frontier model was spent is right there as an entry, not an inference.

The band at the bottom is the part worth reading twice. forum ledger verify reports two booleans, not one: the chain recomputes, and the stored bodies still hash to their keys. They can disagree. A body that was redacted down to its fingerprint is skipped by the deep pass rather than failed, which is what makes hash-only storage usable, and it is also the reason a green deep check is not a claim that every payload was examined. It is a claim about the ones that are still there.

What a tight budget does to context

ContextBudget caps how much text one run may carry, per source and in total. When a cap binds, something has to give. What a task actually ends up seeing is the question this answers.

Every piece leaves a row behind, dropped ones included. forum context preflight runs the same arithmetic on the same inputs before a model call is spent.

A worked example: catch a tampered record

No install needed beyond a clone, and no model is called:

git clone https://github.com/HarperZ9/forum
cd forum
python examples/demo.py

The demo routes a few requests, plans a dependency graph into parallel waves, runs it, and then quietly corrupts one stored result:

4. Accountability: verify, tamper-detect, replay
  verify() (chain)      : True
  verify(deep=True)     : True
  causal chain of last  : request -> plan -> task -> result

   ...now tamper with a stored payload body (seq 2)
  verify() (chain only) : True   <- chain hashes still link
  verify(deep=True)     : False  <- body tamper caught

The chain of hashes still links, so a shallow check passes. But one record's contents no longer match what was promised, and the deep check says so. A visual replay of the same ledger lives at examples/forum-demo.html.

Every example in examples/ is a short, offline, dependency-free demonstration of one capability: escalation ladders, intent judging, delivery tightening, crash resume, context pressure, context capsules, campaigns, and more.

How the ledger works

Two old ideas do most of the work. A hash chain: every entry carries a fingerprint of the one before it, so edits, drops, and reorders stop the fingerprints lining up, and verify() tells you where. Content addressing: prompts and outputs are stored under a fingerprint of their own bytes, which keeps the chain small and lets you redact a sensitive body down to its fingerprint with the chain still checking out; verify(deep=True) re-hashes each body that is present.

Everything else falls out of those two. replay(until=...) rebuilds the exact state at any past point. causal_chain(seq) follows parent links to answer why something happened. checkpoint() folds the history into one Merkle root, built to avoid the second-preimage collision (CVE-2012-2459) that naive Merkle code runs into. By default the ledger lives in memory; point it at FileStorage and every entry is appended to a JSONL file and fsynced before the next, so the record survives a restart, tolerates a crash-torn final write, and still verifies exactly.

To measure the scaling cost honestly, forum bench-deep-verify builds deterministic ledgers and times chain-only verify(), payload-only verify_payloads(), and full verify(deep=True) separately. It varies entry count, payload body bytes, storage mode (memory, file-sync, file-batched), and redaction ratio, then emits a forum.deep-verify-benchmark/v1 JSON receipt:

forum bench-deep-verify --entries 1000,10000 --payload-bytes 256,4096 --storage memory --storage file-batched --json

HTTP and MCP surfaces

The daemon exposes route, plan, submit, humanize, prose contracts, gates, run rooms, capsules, runtime inspection, context preflight, and ledger verify/replay over HTTP (/route, /plan, /submit, /gates, /gate/approve, /room, /capsule, /runtime, /context/preflight, /prose/contract, /verify, and more). MCP mirrors the same tools: forum.submit, forum.route, forum.plan, forum.status, forum.doctor, forum.verify, forum.prose.humanize, forum.prose.contract, forum.ledger.summary, forum.ledger.capsule, forum.ledger.get, forum.run.room, forum.runtime.inspect, forum.context.preflight, and forum.gate.list / approve / edit / reject.

Status

The latest release is forum-engine 1.13.0 (context budgets and preflight, context capsules, expert delivery profiles, route frames and communication contracts, run rooms and readable briefs, runtime inspection, approvals with durable deadlines, proof and domain routes, and campaign orchestration), recorded in CHANGELOG.md. The test suite currently collects 533 tests, including gated real-model tests, and CI runs on every push.

Docs

• docs/INTRODUCTION.md: what forum is, core concepts, and a first-ten-minutes walkthrough.
• ARCHITECTURE.md: the layers, the ledger, and the surfaces.
• RUNNING.md: run it against a real model, over the API or a model CLI.
• USAGE.md: the full command reference.
• docs/GATE-DEADLINES.md: human-in-the-loop gates with durable deadlines.
• docs/ENTERPRISE-READINESS.md: context envelopes, action receipts, and host-neutral operation.
• SECURITY.md: the trust model, the no-shell guarantee, and sandboxing.

Peer projects in Project Telos compose through clean seams: index supplies organized context through the ContextProvider seam, and crucible can check answers through the VerifierProvider seam. Both default to no-ops, so forum stands alone.

Why it matters

Most orchestrators give you output and a log you are asked to trust. forum writes every routing decision, task, result, and verdict into a hash-chained, content-addressed ledger you can verify, replay, and challenge, so a run is something you can prove, not just believe.

License

Forum is fair-source: the code is open to read, run, and build on, with commercial use reserved so the project can fund its own development. Copyright stays with the author. See LICENSE for the exact terms.

For developers

Keep the public README, package metadata, and examples aligned with current behavior. Before opening a PR or pushing a release:

python -m pip install -e ".[dev]"
python -m pytest
python examples/demo.py

What this believes

This tool is one lane of a family that holds a single belief steady across every surface: knowledge open to anyone who can attain the means; acceptance decided by external checks, never reputation; every result re-runnable; honest nulls first-class; ownership earned by comprehension; learning woven into the work. The full text lives in CREDO.md. The long form of this belief: The Unbundling.

---

Zentropy Labs · order out of entropy. An independent lab building evidence-first tools that leave a re-checkable artifact behind. Built by Zain Dana Harper in Seattle. The full workbench is at Project Telos.