Architecture — The Brain

Module Map

Module	Purpose
`delegate.py`	CLI entry point — parses `--provider`, `--type`, `--prompt`, `--context` flags; builds a `Task`; invokes the orchestrator; prints the result.
`brain/orchestrator.py`	Core dispatcher — runs a `Task` through the router and chosen adapter; retries on failure using the per-type fallback chain.
`brain/router.py`	Routing table plus per-`task_type` ordered fallback chains; maps each task type to a list of provider keys to try in sequence.
`brain/stats.py`	Appends every call's metadata to `stats/usage.json` (provider, model, tokens, latency, cost, success, error) regardless of outcome.
`brain/adapters/`	One file per provider — each exports `async def call(task: Task) -> Result`.
`mcp_server.py`	MCP server — exposes the `delegate` tool natively in Claude Code; same orchestrator, no bash required.
`session_start.py`	Session startup script — runs health check, prints provider status table, emits routing advisories.
`health_check.py`	Polls each provider with a lightweight test call; reports online/offline/degraded status.
`brain/model_state.py`	Reads/writes `stats/model_state.json` — pause, disable, or unpause individual provider models based on health probe outcomes.
`brain/health_rollup.py`	Aggregates raw `health_log.json` entries into per-provider uptime and latency summaries for display.
`report.py`	Formats and prints a usage summary; reads tier labels live from the adapter REGISTRY (no hardcoded list).
`push_stats.py`	Updates the GitHub README stats table and pushes to GitHub. Stats-only by default — health failures never block a stats commit.

Provider Adapters

One subdirectory per provider in brain/adapters/, each containing adapter.py. Auto-discovered by the REGISTRY at import time via load_adapters():

cerebras/, groq/, gemini/, mistral/, sambanova/
fireworks/, openai/, cohere/, cloudflare/
huggingface/, openrouter/, ollama/, pollinations/, anthropic/

Each adapter declares class-level metadata: PROVIDER_KEY, TIER, MODELS, DEFAULT_MODEL, QUALITY_SCORE, SPEED_TIER, DESCRIPTION, COST_PER_1K_TOKENS.

Adapter Contract

Every adapter extends BaseAdapter and implements a synchronous complete method:

def complete(task: Task) -> TaskResult

Result fields:

Field	Type	Description
`provider`	str	Provider key used
`model`	str	Model identifier
`content`	str	AI response text
`tokens_used`	int	Output token count
`latency_ms`	int	End-to-end response time
`cost_usd`	float	Estimated cost (0.0 for free tier)
`succeeded`	bool	Whether the call succeeded
`error`	str \| None	Error message if failed

Task Object

Field	Type	Description
`prompt`	str	The input prompt
`task_type`	TaskType enum	Routing category (classification, coding, reasoning, etc.)
`context`	str \| None	Optional text prepended to the prompt (document content, file contents)
`max_tokens`	int	Maximum output tokens (default 2048)
`preferred_model`	str	Provider key to try first

Fallback Chain Execution

Orchestrator invokes the adapter for preferred_model.
On failure, router looks up the fallback chain for task_type.
Orchestrator iterates the chain, trying each provider until one succeeds.
All attempts are logged to stats/usage.json — including failures.
If no provider succeeds, an error Result is returned.

Integration Modes

Mode	Entry Point	How Claude calls it
CLI	`delegate.py`	Bash tool: `python delegate.py --provider <name> --type <type> --prompt "..."`
MCP Server	`mcp_server.py`	Native `delegate` tool — appears in Claude's tool list alongside Bash, Read, Edit