PRODUCT REQUIREMENTS DOCUMENT — v2.0

Chimera

One API call. A team of models. One superior answer.
A dynamic multi-model deliberation engine that fuses the best of every AI model into a single, structured output.

🏷️ v2.0 🐍 Python 3.11+ 📦 MIT License 🐳 Docker-ready ✅ CI/CD on GitHub Actions

🎯 Problem & Solution

The Problem

No single AI model is best at everything. DeepSeek V4 excels at coding but misses nuance in creative work. Claude Sonnet 4 is a brilliant writer but weaker at structured reasoning. Kimi K2.7 leads code benchmarks but struggles with broad analysis. Picking one model means accepting its blind spots.

Today's "model routing" tools pick one model per task. Multi-model "fusion" products give identical prompts to every model — wasting tokens on duplicate work. Neither captures the power of collaborative intelligence: different models tackling different aspects of a problem, then merging their insights.

The Solution

Chimera is a dynamic deliberation engine. A single "dispatcher" model analyzes your prompt, designs a custom processing pipeline (DAG), assigns domain-specific subtasks to the best models for each, and an aggregator merges their work using dispatcher-written instructions. The result: an answer that's stronger than any single model could produce — at a fraction of the cost of running every model on every query.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                        CLIENT                          │
│              POST /v1/chat/completions                       │
│              { "model": "auto", "messages": [...] }          │
└────────────────────────┬────────────────────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                   DISPATCHER (1 call)                    │
│  Analyzes task → Designs DAG → Picks models by category     │
│  → Writes per-worker custom prompts → Writes merge recipe   │
└──────┬──────────────┬──────────────┬────────────────────────┘
       ▼              ▼              ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Worker A      │ │ Worker B      │ │ Worker C      │
│ Code-focused │ │ Design-focus │ │ Analysis     │
│ (DeepSeek    │ │ (Claude      │ │ (GLM-5.2)    │
│  V4 Pro)     │ │  Sonnet 4)   │ │              │
└──────┬───────┘ └──────┬───────┘ └──────┬────────┘
       │                │                │
       └────────────────┼────────────────┘
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                   AGGREGATOR (1 call)                    │
│  Merges heterogeneous results using dispatcher's recipe     │
│  → Structured output (JSON Schema) → Final answer           │
└─────────────────────────────────────────────────────────────┘

Dispatcher → Workers (parallel) → Aggregator. One dispatcher designs the entire run.

Core Features

🧠

Category-Weighted Model Selection

Models scored on 32 hierarchical category paths (code, analysis, reasoning, design, audit). The dispatcher matches task domains to model strengths automatically — with per-request overrides.

🔀

Dynamic DAG Formations

Not a fixed pipeline. The dispatcher designs the optimal processing graph per query: simple (2 workers), debate (3+merge), audit (workers→merge→audit→refine), or fully custom.

📐

Structured Output Guarantee

End-to-end JSON Schema enforcement. Client passes response_format → dispatcher designs schema → aggregator enforces it via provider-native structured modes (json_schema, json_object).

🛡️

Failure Resilience

Worker failures degrade gracefully (not crash). Circuit breakers per provider. Token limit detection. Retry with exponential backoff. Budget exhaustion protection.

💰

Budget-First Defaults

Smart defaults use DeepSeek V4 Pro/Flash — high quality at 10-50× lower cost than premium models. Premium models (Claude, GPT) available via overrides when the task justifies it.

📊

Full Trace & Observability

Every deliberation returns a complete trace: model per stage, tokens in/out, cost, duration. structlog + optional Langfuse integration. Web UI with live DAG visualization.

🔌 Six Interfaces, One Engine

#InterfaceEntryUse Case
1CLIchimera "prompt"Terminal one-shots, quick queries
2REST APIPOST /v1/chat/completionsOpenAI-compatible drop-in for any app
3REST APIPOST /v1/deliberateFull control: DAG, overrides, trace
4Python SDKfrom chimera import EngineEmbedded in Python apps
5MCP Serverchimera-mcp (stdio)AI agent integration (Hermes, Claude, etc.)
6Web UI/web/ (SPA)Multi-turn chat with live DAG visualization

🌐 Supported Providers & Models

Via LiteLLM gateway with automatic provider routing. Direct API routes for DeepSeek and Z.AI (lower latency); OpenRouter for everything else.

ProviderModelsRoutingStrengths
DeepSeekV4 Pro, V4 FlashDirect APIBudget-optimized, strong coding & reasoning
AnthropicClaude Sonnet 4, Opus 4.7/4.8, Haiku 4.5OpenRouterCreative writing, nuanced analysis, design
Z.AIGLM-5.2Direct APIStrong reasoning, multilingual, coding
OpenAIGPT-5.5, GPT-5.1, GPT-5.1-miniOpenRouterBroad capability, structured outputs
MoonshotAIKimi K2.7 Code, K2.6OpenRouterTop-tier coding benchmarks
GoogleGemini 3.5 Flash, 3.1 Pro, 2.5 FlashOpenRouterMultimodal, large context windows
xAIGrok 4.20OpenRouterReal-time knowledge, reasoning
MiniMaxM3OpenRouterMultimodal, 1M context
MetaLlama 4 MaverickOpenRouterOpen-source, strong general performance

💼 Use Cases

🔧 Software Specification Generation

Formation: spec-writer (5-stage audit loop)

Structure → parallel domain-specific writing → merge → gap audit → refinement. Produces exhaustive technical specs with Mermaid diagrams, test scenarios, and error paths.

🎨 Creative & Design Work

Formation: design deliberation

Multiple models critique and improve design outputs (CSS, UI, branding) through iterative refinement. Beats solo model output on visual identity tasks.

📊 Technical Analysis & Research

Formation: auto / debate

Tech stack evaluations, architecture decisions, competitive analysis. Different models analyze different dimensions (performance, security, DX, ecosystem) → merged recommendation.

🤖 AI Agent Orchestration

Interface: MCP server

AI coding agents (Hermes, Claude Code) use Chimera as a "super-consult" tool. The agent delegates complex reasoning to Chimera's model panel, gets back a structured, multi-perspective answer.

📝 Content Generation Pipeline

Formation: custom DAG

Client-defined DAGs for content pipelines: research → draft → fact-check → polish → publish. Each stage uses the optimal model for that specific subtask.

🛠️ Technology Stack

Core

Python 3.11+, asyncio, Pydantic v2, structlog

API Gateway

LiteLLM — 100+ providers, OpenAI-compatible, automatic format negotiation

Server

FastAPI + Uvicorn — async, OpenAPI auto-docs, SSE streaming, CORS

MCP

FastMCP (stdio) — 3 tools: deliberate, formations, models

Model Catalog

models.dev auto-discovery — 145 providers, $/MTok pricing, 24h cache

Deployment

Docker with built-in config. Single command: docker compose up -d

💵 Cost Model

Chimera is MIT-licensed open source — you pay only for the underlying model API calls. No per-request markup, no platform fees.

FormationTypical CallsBudget (~$0.0002/1K tok)Premium (up to ~$0.015/1K tok)
Simple1 dispatch + 2 workers + 1 aggregator = 4 calls~$0.003~$0.08
Debate1 dispatch + 3 workers + 2 aggregators + 1 merge = 7 calls~$0.006~$0.18
Spec-Writer1 structure + 2 writers + 1 merge + 1 audit + 1 refine = 6 calls~$0.008~$0.25

Actual costs vary by prompt length and model selection. Budget formations use DeepSeek V4 Flash (~$0.00014/1K tokens). Premium formations can include Claude Sonnet 4 or GPT-5.5. The dispatcher picks models based on category-weighted scoring with configurable price sensitivity (0.0 = pure quality, 1.0 = pure bang-for-buck).

🚀 Deployment

Docker (One Command)

git clone https://github.com/totalwindupflightsystems/chimera.git
cd chimera
export DEEPSEEK_KEY=sk-...   # only required credential
docker compose up -d
# → REST API on :8765, Web UI on :8765/web/

pip

pip install chimera-deliberation[full]
cp chimera.yaml.example chimera.yaml   # add API keys
chimera serve                            # start server

12-Factor Config

Every setting is overridable via environment variables or CLI flags. No YAML editing required for common deployments:

CHIMERA_PORT=8080 CHIMERA_DISPATCHER=deepseek/deepseek-v4-pro chimera serve

Quality & Reliability

Testing

309+ unit tests, 54 integration tests (real API calls), 7-model compat suite. CI runs on every push to main.

Circuit Breakers

Per-provider state machine (CLOSED→OPEN→HALF_OPEN). Failing providers are isolated automatically; healthy ones keep working.

Rate Limiting

In-memory token bucket per API key. Configurable limits prevent runaway costs.

Authentication

API key auth (env or list mode). Optional per-endpoint. /v1/health/live always open for orchestration.

Concurrency

Async throughout (asyncio + FastAPI). Workers run in parallel. 50-request stress tests pass cleanly.

PyPI Publishing

Automated CI/CD pipeline. Tag a version → lint → test → integration test → publish to PyPI. Zero manual steps.

🗺️ Current Status & Roadmap

StatusItem
✅ Donev2 architecture — single dispatcher, category-weighted selection, budget-first defaults
✅ Done6 interfaces: CLI, REST, MCP, Python SDK, OpenAI-compatible, Web UI
✅ DoneStructured output pipeline (json_schema → json_object fallback)
✅ DoneFailure resilience: degradation, circuit breakers, retry, budget protection
✅ DoneCustom DAGs + per-stage model overrides
✅ DoneProvider auto-discovery (models.dev, 145 providers)
✅ DoneConfig-defined formations (spec-writer, etc.)
✅ DoneDocker one-command deploy with built-in config
✅ DoneCI/CD: lint → test → integration → PyPI publish
✅ DoneWeb UI: multi-turn chat, live DAG viz (Mermaid.js), token/cost dashboard
✅ DoneConfigurable timeout hierarchy (request header → admin ceiling → default)
🔄 Near-termPersistent session storage (SQLite/Postgres backend for Web UI sessions)
🔄 Near-termOpenRouter key auto-provisioning for multi-tenant deployments
📋 PlannedStreaming responses (SSE token-by-token from aggregator)
📋 PlannedModel benchmark auto-refresh pipeline (scores update from live eval results)
📋 PlannedMulti-tenant SaaS mode with per-tenant API key + budget isolation