Forum

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

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

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 singleforumcommand. Every run writes a replayable causal ledger you can re-check.

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

- 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--cmdfor--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 inspectexplains 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. Seedocs/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.RunBudgetcaps a run by model calls and wall clock.ContextBudgetadmits, trims, or omits request context, per-task context, upstream injection, and synthesis inputs under approximate-token caps.forum context preflightestimates the pressure before you spend a model call.
- 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 routepicks a route from a 28-route default roster without a model, and attaches aforum.route-frame/v1frame: 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 mcpexposes 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 --briefprojects the latest run into a readable brief with state, risk, and deterministic next actions.forum ledger capsulecompacts a run into a reusable context brief for the next one.
- Zero dependencies.Pure standard library at runtime. Python 3.11+.

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

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

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

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

forum --helplists the full surface:status,doctor,demo,humanize,route,submit,serve,mcp,context,runtime,ledger,gate,campaign,bench, andbench-deep-verify. From a source checkout the same CLI is available aspython -m forum. SeeRUNNING.mdfor real-model setups andUSAGE.mdfor the full command reference.

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

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 atexamples/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.

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, andverify()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 atFileStorageand 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-verifybuilds deterministic ledgers and times chain-onlyverify(), payload-onlyverify_payloads(), and fullverify(deep=True)separately. It varies entry count, payload body bytes, storage mode (memory,file-sync,file-batched), and redaction ratio, then emits aforum.deep-verify-benchmark/v1JSON receipt:

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

…