What it does for you
forum takes a plain request and sends it to the right lane, plans the work as a dependency graph that runs in parallel waves, and runs it on whichever model you point it at: a local command, any OpenAI-compatible server or the Anthropic API. Every step goes into a causal ledger. You can verify that ledger, trace any result back to the request that caused it, and catch a stored body that was changed.
- Routing without a model
forum routepicks a lane from a 28-route roster with a lexical scorer, or says it needs a classifier. - Parallel wavesTasks with their dependencies become waves of parallel work, capped by a policy.
- Bounded runsA run budget caps model calls and wall clock, and a context budget trims what goes into each prompt.
- A ledger you can replayEach entry links to the one before and to the entry that caused it. A deep verify re-checks every stored body.
Source: README.md at abafb38 (release 1.17.0)
Watch
Video walkthrough: coming with the next release.
How it works, one step at a time
Scroll, or use the step buttons. The panel follows forum's bundled demo, examples/demo.py, which CI runs on every push. It uses a stub executor in place of a model, so the routing, planning and ledger are real and the task outputs are placeholders. Every value is output from forum at commit abafb38.
- 01
Route four requests
The lexical router scores each request against the roster's lanes, with no model call. Schema and auth work goes to
backend, a React component tofrontend, a guide todocs."Summon a unicorn" matches nothing. It scores 0.00 and the router escalates: it needs an LLM classifier, and it says so and makes no guess.
Source: examples/demo.py; src/forum/routing.py
- 02
One request, scored in full
forum routeprints the whole decision: the chosen lane, its confidence, whether it needs escalation, the router that decided and every candidate's score. Herebackendwins at 0.6 andci-cdis next at 0.2.Source: src/forum/routing.py; README.md, "Install and quickstart"
- 03
Plan the work into waves
Four tasks with dependencies: T1 designs the schema, T2 builds the auth endpoint after T1, and T3 (login page) and T4 (API docs) both wait on T2.
The planner sorts the graph into waves of tasks whose dependencies are done. The policy caps each wave at two tasks, so T3 and T4 share the last wave.
Source: examples/demo.py; src/forum/plan.py, src/forum/policy.py
- 04
Run each wave, and record every step
Each task runs in its lane, and every step is appended to the ledger: the request, the routes, the plan, each assignment and each result. Every entry names its causal parent, so a result points to its task, the task to the plan, and the plan to the request.
The demo's stub executor returns
done:plus the task. A real run puts a model here.Source: src/forum/ledger.py,
appendandcausal_chain - 05
Verify the ledger
verify()re-derives every entry's hash from its sequence number, time, actor, kind, causal parent, payload hash and the previous entry's hash. All 14 entries link.verify(deep=True)also re-hashes every stored payload body against the hash its entry recorded. The Merkle checkpoint summarises the whole ledger in one hash.Source: src/forum/ledger.py,
verifyandverify_payloads - 06
Change one stored body
The demo replaces the stored body of entry 2 with
{"task": "TAMPERED"}. The chain still links, because entries hold the body's hash and none of them changed. The deep verify re-hashes the body, finds it no longer matches, and fails.That is why the two checks are separate: one proves the order of events, the other proves the content.
Source: examples/demo.py; src/forum/ledger.py,
verify_payloads
Walkthrough
Install it, run it once, then use the main feature. Each command below is real, and so is its output.
Install
Install from PyPI. Python 3.11 or newer; routing needs no model.
$ pip install forum-engineFirst run: route a request
Forum scores a request against its team profiles and names the one that should take it.
$ forum route "build the auth endpoint and the database schema" "decided": "backend", "confidence": 0.6,Run it on a model
Submit the request with any command that runs a model. Forum plans it into waves, runs them, and records every step in a ledger.
$ forum submit "ship a login API" --cmd "ollama run llama3"Verify the ledger
Check the recorded ledger afterwards.
$ forum ledger verify
Output from forum at abafb38. forum-engine 1.17.0 is the current PyPI release. forum submit needs a model you can reach.
What it does not do
- The lexical router decides from words. A request that matches no lane is escalated, and a request worded unusually can land in the wrong lane.
- A run result is distinct from an external effect. A ledger that verifies says the record is intact. Whether the work was right needs its own check.
- The chain check alone cannot see a changed payload body. Use the deep verify for content.
- Approval gates and resume run through the Python API. The CLI, the daemon and the MCP server list and resolve gates but do not yet open a gated run.
forum serveneeds a bearer token by default. Turning it off is meant for loopback only.
Source: README.md at abafb38, "Current status" and "Inspect and serve"; src/forum/ledger.py
Check what stuck
Answer each one in your head before you open it.
What does the router do with "summon a unicorn"?
It scores 0.00 against every lane and escalates, saying it needs an LLM classifier.
Why do T3 and T4 run in the same wave?
Both wait only on T2, and the policy allows two tasks per wave.
After a stored body is changed, why does verify() still return True?
The chain links entries through hashes the entries hold. The body is stored separately, so only the deep verify, which re-hashes bodies, sees the change.
How do you trace a result back to its request?
Follow the causal parents: result to task to plan to request.