Examples
All snippets below are from the repository's examples/ directory. Clone the repo to run them:
git clone https://github.com/JordanNewell/tractum
cd tractum
Minimal swarm + signed receipt
examples/quickstart.py — the smallest useful program. A 3-agent swarm (DBA, Indie Hacker, Security Engineer) picks a database for a side project; the result is rebuilt from its dict form, packed into a receipt via ConsensusReceipt.from_result, and signed with Ed25519Backend. Uses TRACTUM_SIGNING_KEY when set, otherwise a fresh ephemeral key.
pip install tractum
export ANTHROPIC_API_KEY=sk-ant-...
python examples/quickstart.py
Disagreement surfaced, then resolved
examples/consensus_demo.py — three specialists (StrongConsistency, Operations, Pragmatist) disagree on a multi-region backend architecture. The demo runs WeightedVote first to surface the disagreement, then re-runs Debate so agents see each other's reasoning and converge, and signs the final result. Shows to_json_receipt output.
python examples/consensus_demo.py
Hierarchical decomposition
examples/coordinator_demo.py — a Coordinator breaks a complex task into a real JSON plan, routes each sub-task to a specialist (Researcher, Analyst, Writer) by role match, runs independent sub-tasks in parallel, and synthesizes the result. Requires ANTHROPIC_API_KEY.
python examples/coordinator_demo.py
MCP end-to-end, keyless
examples/mcp_demo.py — the launch story in one script: a 3-agent swarm reaches a decision, the receipt is produced exactly the way tractum-mcp produces it, then verified — aggregate signature, quorum k-of-n, every agent statement — through the server's own verify_consensus tool. Runs keyless (offline stub agents, no API key) when the mcp extra is not installed; with tractum[mcp] the verification goes through the real MCP tool call.
python examples/mcp_demo.py # keyless, offline stubs
ANTHROPIC_API_KEY=sk-ant-... python examples/mcp_demo.py # live agents
Nostr round-trip (Buzz interop)
examples/buzz_consensus_demo.py — three advisors (Operator, Investor, CFO) reach a weighted-vote decision; the signed receipt is wrapped as a Nostr kind-30078 event via to_nostr_event, published to a relay, and a subscriber reads it back and verifies the consensus signature in one line. Offline mode needs no API key. Requires pip install tractum[nostr] websockets and a local relay:
nak serve --port 10547 # terminal 1
python examples/buzz_consensus_demo.py # terminal 2 (offline mode)
The relay URL defaults to ws://localhost:10547, overridable with TRACTUM_DEMO_RELAY.
Wire publish
examples/buzz_wire_publish.py — one-shot publisher: generates a fresh Nostr keypair, runs a real Debate consensus on a Buzz-relevant question with three agents (ProtocolArchitect, AgentFrameworkLead, AcquiHireBuyer), signs the receipt, publishes to a list of public relays, and prints a https://nostr.mom/e/{event_id} viewer URL. Requires ANTHROPIC_API_KEY.
The repository also ships examples/buzz_wire_event_v030.json — the actual kind-30078 event (event id 3974ebfe688f1639a8534b46bbbfeddf354d18efcd190352da877756d1bac60b) produced by that script at v0.3.0, suitable for nak verify against the relays it was published to.
Transparency log
examples/transparency_demo.py — three swarms reach (simulated) consensus; each receipt is appended to a TransparencyLog; the log root is published as a Nostr anchor event; then a receipt is verified against the published root with only the receipt + inclusion proof + root — no trust in the log operator. Runs fully offline (no API key); the Nostr anchor leg uses tractum[nostr].
python examples/transparency_demo.py
Framework adapters
Each demo shows the prebuilt path and the embed-in-your-graph path:
examples/langgraph_adapter_demo.py— consensus as aStateGraphnode (build_consensus_graphstandalone, ormake_consensus_nodeadded to your own graph after an upstream research node). RequireslanggraphandANTHROPIC_API_KEY.examples/maf_adapter_demo.py— consensus as a Microsoft Agent Framework executor (build_consensus_workflowstandalone, ormake_consensus_executorwired after an upstream research executor). Requirestractum[maf].examples/crewai_adapter_demo.py— consensus callable from a CrewAI crew:reach_consensus(swarm)as a@toolthe agent invokes, plus the prebuiltConsensusFlow. Requirestractum[crewai].
Killer benchmark
examples/killer_demo.py — the same hard question answered three ways: a single Claude call, a CrewAI crew, and a Tractum swarm. Captures latency, token counts, and a blind LLM-judge score (correctness, nuance, completeness, disagreement-surfaced); writes examples/killer_demo_results.md. Requires pip install -e ".[nostr,dev,benchmark]" (litellm optional for token tracking). Reproducible from cold via the Docker appliance — see Self-hosting.