Skip to main content

​
Components

​
Data Flow

  1. CLI or Web UI calls run_debate(query, config) with optional panel, synthesizer, rounds overrides
  2. Orchestrator resolves defaults, initializes a DebateTranscript, and opens a ProviderRouter context
  3. Initial round — orchestrator fans out format_initial(query) to all panel models in parallel via complete_parallel()
  4. Reflection rounds — for each round, each model receives format_reflection(query, own_response, others_responses); all models run in parallel
  5. Synthesis — the designated synthesizer receives the full formatted transcript via format_synthesis()
  6. Scoring — if ground_truth is provided, the synthesizer scores its own output as judge
  7. Stats — token counts, per-model costs (from OpenRouter pricing API), and routing decisions are aggregated into metadata.stats
  8. Transcript — the completed DebateTranscript is serialized to JSON and saved to disk

​
Key Modules

ModuleResponsibility
orchestrator.pyDebate lifecycle, round management, parallel dispatch
providers/router.pyRouting decisions, provider selection, fan-out
providers/anthropic.pyDirect Anthropic API client
providers/openrouter.pyOpenRouter API client
config.pyConfiguration loading, alias resolution, key management
models.pyDebateTranscript, DebateRound, ModelResponse, ExperimentMetadata
types.pyVendor, RoutingDecision, RoutedRequest
transcript.pyJSON serialization, file storage, listing, loading
cli.pyClick command group, output formatting dispatch
web/app.pyStarlette application entry point
prompts.pyPrompt templates for initial, reflection, and synthesis rounds
scoring.pyGround-truth scoring via judge model
pricing.pyOpenRouter pricing cache, cost computation

​
Async Model

The orchestrator and provider layer are fully async. All model calls within a single round execute concurrently via asyncio.gather. The CLI runs the event loop with asyncio.run(). The web UI runs on uvicorn’s async event loop.