Metadata-Version: 2.4
Name: forum-engine
Version: 1.14.0
Summary: Model-agnostic agent orchestration with a replayable, verifiable causal ledger.
Author: Zain Dana Harper
License-Expression: LicenseRef-FSL-1.1-MIT
Project-URL: Homepage, https://github.com/HarperZ9/forum
Project-URL: Repository, https://github.com/HarperZ9/forum
Keywords: agents,orchestration,ledger,accountability,multi-agent,audit,zero-dependency
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

<p align="center"><img src="docs/art/forum-header.svg" alt="forum: route a request, run it in waves, keep a record you can re-check." width="100%"></p>

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](https://img.shields.io/pypi/v/forum-engine?style=flat-square&labelColor=14041b&color=99f147)](https://pypi.org/project/forum-engine/)
[![license](https://img.shields.io/badge/license-Forum%20Fair--Source-8f8095?style=flat-square&labelColor=14041b)](LICENSE)
[![CI](https://github.com/HarperZ9/forum/actions/workflows/ci.yml/badge.svg)](https://github.com/HarperZ9/forum/actions/workflows/ci.yml)
[![downloads](https://img.shields.io/pypi/dm/forum-engine?label=downloads&style=flat-square&labelColor=14041b)](https://pypi.org/project/forum-engine/)
![python: 3.11+](https://img.shields.io/badge/python-3.11%2B-blue?style=flat-square&labelColor=14041b)
![deps: none](https://img.shields.io/badge/deps-none-success?style=flat-square&labelColor=14041b)

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](https://harperz9.github.io) | [gather](https://github.com/HarperZ9/gather) | [crucible](https://github.com/HarperZ9/crucible) | [index](https://github.com/HarperZ9/index) | [forum](https://github.com/HarperZ9/forum) | [telos](https://github.com/HarperZ9/telos) | [learn](https://github.com/HarperZ9/learn) | [emet](https://github.com/HarperZ9/emet) | [buildlang](https://github.com/HarperZ9/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](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

```bash
pip install forum-engine
```

Routing and the ledger commands need no model:

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

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

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

```bash
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:

```bash
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](RUNNING.md) for real-model setups and [USAGE.md](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](USAGE.md#codex-route-preflight-skill-asset) 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.

<p align="center"><img src="docs/art/run-lifecycle.svg" alt="Eight stages from a routed request to a hash-chained record: route, context, plan, dispatch, verdict, escalate, synthesize, ledger. A result that fails its verdict sends the task up a ladder of stronger models and is graded again. Re-checking the record reports the chain and the payloads separately, and a payload that was never stored is skipped rather than counted as held." width="100%"></p>

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.

<p align="center"><img src="docs/art/context-pressure.svg" alt="Seven things that can happen to one piece of context on its way to a task, and why each one lands that way. Text under its cap is kept whole, text over it is trimmed to the cap and measured again from what survived, and when two caps bind equally the reason names the total so a reader can tell the run is nearly out. Empty text is still recorded as a check. A character sitting on the cut is dropped rather than mangled, because the trim is measured in bytes. The marked row is the one where a piece is dropped whole, and even then the record keeps a row for it." width="100%"></p>

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:

```bash
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`](examples/forum-demo.html).

Every example in [`examples/`](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:

```bash
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.14.0` (observability, auth, route-preflight skill packaging, 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](CHANGELOG.md). The test suite currently collects 533 tests, including gated real-model tests, and CI runs on every push.

## Docs

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

Peer projects in Project Telos compose through clean seams: [index](https://github.com/HarperZ9/index) supplies organized context through the `ContextProvider` seam, and [crucible](https://github.com/HarperZ9/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](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:

```bash
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](CREDO.md).
The long form of this belief: [The Unbundling](https://github.com/HarperZ9/flywheel/blob/fix/release-model-identity/docs/essays/2026-07-13-the-unbundling.md).

---

**[Zentropy Labs](https://github.com/ZentropyLabs-ai)** · 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](https://harperz9.github.io).
