symposium-protocol 1.11.3

Reference implementation of the Symposium protocol — structured, sequential, adversarial multi-agent deliberation.

Symposium

A panel of AI experts that actually argue — structured, sequential, and replayable to the byte.

---

Symposium runs a small panel of AI personas through a structured debate — each takes a turn, a neutral coordinator steers, and you get back one synthesized answer. Every session is saved as a tamper-evident artifact you can replay byte-for-byte.

It's not another free-form "group chat" framework. Symposium enforces exactly one conversation shape — fixed panel, one turn per agent per round, a coordinator that recommends but never decides when to stop. You trade flexibility for something most multi-agent stacks can't give you: reproducibility.

        critic ── logician
       /                  \
  engineer    (coordinator)   visionary
       \                  /
        researcher ───────
   → one debate, one synthesized answer, one replayable artifact

Why Symposium

• 🔑 No API key needed. By default it drives your local claude / codex CLI login — nothing metered, nothing to configure.
• 🧠 A real panel. Five complementary personas (logician, visionary, researcher, critic, engineer) plus a separate coordinator. Add your own on the fly.
• 🔁 Byte-identical replay. Every run is a SHA-256-sealed artifact; re-render it or re-execute it and prove it didn't change.
• 📺 Watch it live. symposium watch opens a browser viewer — personas on a circle, a glow on the speaker, arrows for every direct question.
• 🧩 Built for Claude Code. Ships an MCP server: kick off a deliberation and stream the debate straight into your client.
• 📜 A spec, not just code. The protocol is language-independent; this Python package is one reference implementation.

Install

pip install symposium-protocol            # import symposium
pip install "symposium-protocol[mcp]"     # + the Claude Code / Desktop MCP server

Python 3.11+.

Quick start

In Claude Code (the easy path — no key). Register the server, then just ask:

claude mcp add symposium -- symposium-mcp

deliberate(problem="Should we migrate the monolith to microservices?")

The panel debates over your local claude / codex login and streams each turn back live. That's it.

From the terminal (no key, no network). Run the deterministic demo, then replay it:

symposium run \
  --config examples/configs/walking-skeleton.yaml \
  --script examples/scripts/walking-skeleton.json \
  --output runs/ examples/problem.md

symposium replay runs/demo-walking-skeleton-001     # byte-identity check
symposium watch  runs/demo-walking-skeleton-001     # ↑ watch it in the browser

Use it in Claude Code

The MCP server exposes the runtime as tools. The default provider="cli-auto" routes each persona to a local CLI — the creative visionary to codex, the rest to claude — and falls back to whichever you have installed. No API key.

// default: stream the debate live, no key
deliberate(problem="…")

// dynamic experts: generate a domain specialist mid-debate when the panel gets stuck
deliberate_adaptive(problem="…", experts=["GDPR compliance", "Postgres internals"])

// force one CLI, or opt into the metered HTTP API instead
deliberate(problem="…", provider="claude-cli")   // or "codex-cli"
deliberate(problem="…", provider="anthropic")     // reads ANTHROPIC_API_KEY

// deterministic, offline (tests & demos)
deliberate(problem="demo", provider="fake", fake_script_path="examples/scripts/walking-skeleton.json")

Tool	Does
deliberate	Run a debate, stream every turn live. The default.
deliberate_adaptive	Same, but generates new expert personas on demand (early-start + mid-run).
*_muted variants	Same result, no live streaming — just the final answer.
get_run_status	Poll a still-running debate for new turns.
get_run_summary	Outcome + metrics + replay check for a finished run.
list_personas / generate_persona	Inspect the built-in panel / design a new expert.
get_version	What's actually running (handy after a reinstall).

Billing. Logged in with a Pro/Max or ChatGPT subscription? CLI turns spend subscription quota and rate limits, not metered API dollars. The real ceiling under cli-auto is max_wallclock_seconds (default 1h) and your plan's rate limit — the token/cost caps are telemetry, not a hard budget. Only the anthropic / openai HTTP adapters bill per token.

API keys: what's used, what isn't

Provider	API key
cli-auto (default), claude-cli, codex-cli	None — reuses your local CLI login
fake	None — offline & deterministic
anthropic	ANTHROPIC_API_KEY (optional ANTHROPIC_BASE_URL)
openai	OPENAI_API_KEY (optional OPENAI_BASE_URL)

ANTHROPIC_API_KEY / OPENAI_API_KEY are read only when you explicitly pick the metered anthropic / openai HTTP adapter. Every default path ignores them — and the CLI adapters actively scrub cross-vendor credentials before each spawn.

CLI commands

symposium run                 # run a session against any provider
symposium watch               # live browser viewer (follows the newest run)
symposium replay              # re-render a stored transcript; verify the digest
symposium execution-replay    # re-run under the 10 pinning conditions; prove reproducibility
symposium validate            # check an artifact against the v1.0.0 JSON Schemas
symposium metrics             # tokens, cost, latency, branch depth — computed offline

To run real models from the CLI without a key, set provider: claude-cli (or codex-cli) on each agent in your config and drop the vendor key — the adapters are registered out of the box.

Use it as a library

from symposium.providers import default_registry
from symposium.scheduler import run_session

providers = default_registry().build_session_providers(config)
artifact = run_session(config, providers, runs_root="runs/")

print(artifact.outcome.kind)          # "synthesis" or "termination"
print(artifact.transcript_digest)     # 64-hex SHA-256 over the canonical transcript

How it's different

	Symposium
Topology	One fixed shape — no arbitrary handoffs or nested supervisors.
Routing	Schema-validated direct_request only; inline @mentions are never routing (injection-resistant).
Who decides to stop	Deterministic runtime code — never the LLM coordinator.
Replay	Unconditional transcript replay and conditional re-execution, both spelled out.
Failure modes	Closed, enumerated — not "whatever the framework happened to do".

The full rationale, and a comparison against AutoGen / CrewAI / LangGraph / OpenAI Agents SDK, lives in the specification.

Project layout

• docs/specification.md — the normative protocol (language-independent) + 16 JSON Schemas under docs/schemas/v1.0.0/.
• symposium/ — the reference Python runtime (scheduler, providers, replay, viewer, MCP server, CLI).
• examples/, tests/ — runnable configs and the conformance suite.

A conformant runtime in any language is just as valid as this one, as long as it matches the spec and validates against the schemas.

Contributing & status

The v1.0 spec is frozen (ratified 2026-05-26); the runtime ships as symposium-protocol on PyPI. Issues, errata, and PRs welcome — see CONTRIBUTING.md and ROADMAP.md.

pip install -e ".[test]" && pytest -q     # run the suite

License

Apache 2.0.