Chimera — Dynamic Multi-Model Deliberation Gateway

One API call. A team of models. One answer.

Chimera takes your prompt, dispatches it to a hand-picked team of LLMs (each with a custom subtask scoped to their strengths), and an aggregator merges their outputs using dispatcher-written instructions. One dispatcher model call designs the entire deliberation at once.

Quickstart

# Install (choose one)
pip install chimera-deliberation[full]        # full CLI + server in a venv
pipx install chimera-deliberation[full]       # same, isolated in its own env
pip install chimera-deliberation[server]      # API server only

# Configure
cp chimera.yaml.example chimera.yaml
# Add your API keys (at minimum: DEEPSEEK_API_KEY)

# Run
chimera "What is the capital of France?"      # CLI deliberation
chimera run "Compare React and Vue"           # explicit `run` subcommand (same as above)
chimera serve                                 # REST API + web UI (see Server & MCP)
chimera-mcp                                   # MCP tools for agents

Open http://localhost:8765/web/ for the web UI with live DAG visualization.

Python:

# If chimera.yaml is missing, create it before calling load_config():
chimera config init        # pip/pipx installs — template ships inside the wheel
# Repo checkouts can instead copy the checked-in template:
# cp chimera.yaml.example chimera.yaml
# Missing template? Reinstall to restore it:
# error: chimera.yaml.example not found — reinstall chimera-deliberation to restore the template.

load_config() finds the config in this order: explicit path argument, then the CHIMERA_CONFIG env var, then a walk-up from the current directory.

import asyncio

from chimera import Engine, LiteLLMGateway, load_config

config = load_config()
engine = Engine(config, LiteLLMGateway(config))
result = asyncio.run(engine.deliberate("Explain quantum computing."))
print(result.answer)  # merged output from multiple models

OpenAI-compatible:

curl -X POST http://localhost:8765/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "Hello"}]}'

Documentation

Detailed guides live in docs/:

Architecture

flowchart TB
    subgraph Client
        A[User Prompt]
    end

    subgraph Dispatcher["Dispatcher (1 call)"]
        B[Designs DAG<br/>Picks models by category<br/>Writes custom prompts<br/>Writes merge instructions]
    end

    subgraph Workers["Workers (parallel)"]
        C1[Worker A<br/>domain-scoped task]
        C2[Worker B<br/>domain-scoped task]
        C3[Worker C<br/>domain-scoped task]
    end

    subgraph Aggregation
        D[Aggregator<br/>merges with dispatcher instructions]
    end

    A --> B
    B --> C1
    B --> C2
    B --> C3
    C1 --> D
    C2 --> D
    C3 --> D
    D --> E[Final Answer]

Formation Types

flowchart LR
    subgraph Simple["Simple (2 workers)"]
        S1[W1] --> SA[Aggregator]
        S2[W2] --> SA
    end

    subgraph Debate["Debate (3 workers + merge)"]
        D1[W1] --> DA1[Agg 1]
        D2[W2] --> DA1
        D2 --> DA2[Agg 2]
        D3[W3] --> DA2
        DA1 --> DM[Merge]
        DA2 --> DM
    end

    subgraph Custom["Custom DAG (client-defined)"]
        C1[Researcher] --> C2[Critic]
        C2 --> C3[Polisher]
        C3 --> C4[Final]
    end

Flow: Request to Answer

sequenceDiagram
    participant Client
    participant Engine
    participant Dispatcher
    participant Workers
    participant Aggregator

    Client->>Engine: POST /v1/chat/completions
    Engine->>Dispatcher: Design formation
    Dispatcher->>Dispatcher: Pick models by category weights
    Dispatcher->>Dispatcher: Write per-worker prompts + merge instructions
    Dispatcher-->>Engine: DAG + prompts + instructions

    par Workers (parallel)
        Engine->>Workers: Worker A (custom prompt)
        Engine->>Workers: Worker B (custom prompt)
        Engine->>Workers: Worker C (custom prompt)
        Workers-->>Engine: responses
    end

    Engine->>Aggregator: Merge with dispatcher instructions
    Aggregator-->>Engine: Final answer

    Engine-->>Client: JSON response + trace

Server & MCP

chimera serve starts the REST API plus the web UI:

• http://localhost:8765/v1/chat/completions — OpenAI-compatible endpoint
• http://localhost:8765/docs — OpenAPI docs
• http://localhost:8765/web/ — web UI with live DAG visualization

Health probes (all return JSON):

• http://localhost:8765/health — alias of the liveness probe (always 200 when the process is alive)
• http://localhost:8765/v1/health — health check (healthy / degraded / unhealthy)
• http://localhost:8765/v1/health/ready — readiness probe (200 when ≥1 provider reachable, 503 otherwise)
• http://localhost:8765/v1/health/live — liveness probe (always 200 when alive)

chimera-mcp runs the MCP server over stdio so AI agents (Hermes, Claude Code, etc.) can call Chimera directly. Both read the same chimera.yaml configured in Quickstart.

Model Selection

The dispatcher picks models using category-weighted scoring:

Each model in the catalog has a score (0.0–1.0) per category. The dispatcher matches task domains to model strengths. You can override any model choice per request:

{
  "model": "auto",
  "messages": [{"role": "user", "content": "..."}],
  "dispatcher_model": "deepseek/deepseek-v4-flash",
  "aggregator_model": "z-ai/glm-5.2",
  "worker_model": "deepseek/deepseek-v4-pro",
  "allowed_models": ["deepseek/deepseek-v4-pro", "z-ai/glm-5.2"],
  "stage_models": {"worker_1": "openrouter/anthropic/claude-sonnet-4"}
}

• dispatcher_model — model for the planning/dispatch call itself.
• aggregator_model — forces every aggregator/merge/audit stage.
• worker_model — forces every worker stage.
• stage_models — per-stage overrides; these win over the global ones above.
• Config locks (defaults.lock_aggregator: true / defaults.lock_dispatcher: true) force the configured default for that role and discard the request override. A discarded override is never silent: it is recorded in the trace's dispatch_note (e.g. override discarded: aggregator_model='X' ignored (lock_aggregator=true)).

Custom DAGs

Send your own formation structure at request time. The example below is the complete request body for POST /v1/chat/completions with "model": "custom" — that endpoint is the custom-DAG contract (POST /v1/deliberate does not accept formation custom):

{
  "model": "custom",
  "allow_custom_dag": true,
  "dag": {
    "stages": [
      {"id": "researcher", "kind": "worker", "model": "openrouter/anthropic/claude-sonnet-4"},
      {"id": "critic", "kind": "aggregator", "model": "z-ai/glm-5.2", "depends_on": ["researcher"]},
      {"id": "polisher", "kind": "worker", "model": "deepseek/deepseek-v4-pro", "depends_on": ["critic"]},
      {"id": "final", "kind": "aggregator", "model": "openrouter/anthropic/claude-sonnet-4", "depends_on": ["polisher"]}
    ],
    "edges": [["researcher","critic"], ["critic","polisher"], ["polisher","final"]]
  },
  "messages": [{"role": "user", "content": "..."}]
}

The dispatcher writes custom prompts for each stage but uses YOUR structure exactly.

Interfaces

Response Trace

Every deliberation returns a full trace:

request_id: a71b3f2c...
formation: auto
source: auto        ← not "fallback" — dispatcher designed it
total_tokens: 12345
total_cost: $0.012
total_duration_ms: 15234

dispatch: V4 Flash (1,234ms, 800+420 tok)
workers:
  worker_rust: Claude Sonnet 4 (4,500ms, 300+1,200 tok)
  worker_go: Kimi K2.7 (8,200ms, 250+800 tok)
aggregator: V4 Flash (2,100ms, 3,000+500 tok)

Providers

Chimera uses LiteLLM under the hood. Supported providers: