chimera-deliberation 0.1.0__tar.gz

chimera_deliberation-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * *"  # daily at 6am UTC
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    continue-on-error: true  # Non-blocking: advisory lint (matches pre-commit hook)
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Create venv and install ruff
+        run: |
+          python -m venv .venv
+          .venv/bin/pip install ruff>=0.6.0
+
+      - name: Run ruff
+        run: .venv/bin/ruff check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Create venv and install project
+        run: |
+          python -m venv .venv
+          .venv/bin/pip install --upgrade pip
+          .venv/bin/pip install -e ".[full]"
+
+      - name: Run tests
+        run: .venv/bin/python -m pytest tests/ -q
+
+      - name: Report test count
+        if: always()
+        run: |
+          .venv/bin/python -m pytest tests/ --collect-only -q 2>&1 | tail -5
+
+  publish:
+    needs: [lint, test]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build package
+        run: |
+          python -m venv .venv
+          .venv/bin/pip install build twine
+          .venv/bin/python -m build
+
+      - name: Publish to PyPI
+        run: .venv/bin/twine upload dist/*
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}

chimera_deliberation-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+chimera.yaml
+.env
+.pytest_cache/
+.ruff_cache/
+mutants/
+.coverage
+htmlcov/

chimera_deliberation-0.1.0/.gitreins/config.yaml

@@ -0,0 +1,39 @@
+# GitReins Configuration — Chimera
+
+guards:
+  secrets: true
+  lint: true
+  tests: true
+  test_command: "pytest -x --tb=short -q"
+
+pipeline:
+  stages:
+    - id: tier1
+      parallel: true
+      on: [pre-commit, pre-eval]
+      steps:
+        - id: secrets
+          type: script
+          run: "bash .git/hooks/pre-commit-secrets"
+          on_fail: block
+
+        - id: lint
+          type: script
+          run: "ruff check src/ tests/ --quiet"
+          on_fail: continue
+
+        - id: tests
+          type: script
+          run: "pytest -x --tb=short -q"
+          on_fail: continue
+
+    - id: tier2
+      type: ai_eval
+      on: [pre-eval]
+      condition: "true"
+      max_iterations: 20
+      tools: [read_file, run_command, search_pattern, read_diff, sandbox]
+
+evaluator:
+  max_iterations: 20
+  model: deepseek-chat

chimera_deliberation-0.1.0/.memory-bank/active-context.md

@@ -0,0 +1,37 @@
+# Active Context — Chimera
+
+## Current Phase
+**Phase 0: Architecture & Scaffolding** (June 17, 2026)
+
+## What We're Building
+Fresh implementation of Chimera v2 — dispatcher-first architecture with
+category-weighted domain routing, dynamic DAG formations, and dispatcher-written
+judge instructions.
+
+## Key Decisions
+- **No SpecLang** — clean Python project, no code generation pipeline
+- **OpenCode + GLM-5.2** as the build agent (Z.AI subscription, no OpenRouter fees)
+- **Memory bank pattern** from Axiom/Conscience projects
+- **Config-driven from day one** — no hardcoded model assignments
+- **Budget-first defaults** — DeepSeek V4 for dispatcher/worker/judge
+- **Request-level overrides** — API accepts allowed_models, disallowed_models,
+  dispatcher_model, judge_model, worker_model per request
+
+## Model Strategy
+- **Default**: DeepSeek V4 (cheap, good all-rounder) for all roles
+- **Premium options**: GLM-5.2, Claude Sonnet 4 — available via request overrides
+- **Per-request control**: Caller can force specific models, whitelist/blacklist
+- **Category weights**: Each model scored 0.0–1.0 per domain (code, analysis, design, audit, reasoning)
+- **Dispatcher uses weights** to auto-assign models when not overridden
+
+## Blockers
+None.
+
+## Next Steps
+1. ✅ Architecture spec written
+2. ✅ Memory bank initialized
+3. ✅ GLM-5.2 built full implementation (3,386 lines, 65 tests)
+4. ✅ Request-level overrides added to API + config
+5. 🔄 Live E2E deliberation test (budget-first defaults)
+6. Create GitLab repo and push
+7. MCP integration test with Hermes

chimera_deliberation-0.1.0/.memory-bank/product-context.md

@@ -0,0 +1,19 @@
+# Product Context — Chimera
+
+## User Experience
+1. User sends a prompt: "Design a scalable microservice architecture for an e-commerce platform"
+2. Chimera's dispatcher analyzes it — touches design, backend, analysis domains
+3. Dispatcher picks Gemini (strong at design) for architecture design, DeepSeek (strong at code) for service boundaries, Claude (strong at analysis) for trade-off analysis
+4. Each gets a custom prompt scoped to their subtask
+5. Judge merges: "Here's the architecture, here are the service boundaries, here are the trade-offs"
+
+## Stakeholders
+- **Bane (totalwindupflightsystems)** — primary user, drives design
+- **Hermes Agent** — dispatches Chimera stages via MCP
+- **Any AI coding agent** — drop-in OpenAI-compatible endpoint
+
+## Non-Goals (v1)
+- Streaming responses
+- Tool/function calling passthrough
+- Response caching
+- Multi-turn conversation state

chimera_deliberation-0.1.0/.memory-bank/progress.md

@@ -0,0 +1,19 @@
+# Progress — Chimera
+
+## 2026-06-17
+
+### Phase 0: Architecture & Scaffolding
+- [x] Architecture spec written (specs/architecture.md — 11KB)
+- [x] Memory bank initialized (.memory-bank/)
+- [x] Project scaffolding (pyproject.toml, .gitignore, README)
+- [x] Config example (chimera.yaml.example)
+- [ ] GLM-5.2 builds full implementation
+- [ ] All tests passing
+- [ ] Live deliberation smoke test
+- [ ] GitLab repo created and pushed
+
+## Validation Gate
+```bash
+cd ~/chimera-v2
+python -m pytest tests/ -x -q  && echo "PASS" || echo "FAIL"
+```

chimera_deliberation-0.1.0/.memory-bank/project-brief.md

@@ -0,0 +1,27 @@
+# Project Brief — Chimera
+
+## What
+A dynamic multi-model deliberation gateway. Takes a user prompt, designs a custom
+formation of models to solve it, and returns a merged answer.
+
+## Why
+OpenRouter Fusion runs a fixed panel of models with the same prompt. Chimera's
+dispatcher analyzes the task, picks the best models by category-weighted domain
+strength, writes custom prompts for each worker, and tells the judge how to merge.
+
+This makes weak models useful: a model bad at code but good at design gets
+design-only subtasks. Budget models handle simple pieces, premium models do
+complex work.
+
+## Core Principle
+**One model (Dispatcher) designs the entire deliberation in one shot.**
+It reads the user prompt + model catalog → designs formation DAG → writes all
+worker prompts + judge instructions simultaneously.
+
+## Success Criteria
+- OpenAI-compatible `/v1/chat/completions` endpoint (drop-in replacement)
+- Full deliberation completes with correct merged output
+- Category-weighted domain routing works (right model for right subtask)
+- Dispatcher-written judge instructions produce quality merges
+- Traceability: every stage logged (prompt, response, tokens, cost)
+- Config-driven: add models via YAML with category weights

chimera_deliberation-0.1.0/.memory-bank/system-patterns.md

@@ -0,0 +1,24 @@
+# System Patterns — Chimera
+
+## Dispatcher-First Architecture
+All intelligence lives in the dispatcher. Workers and judges are "dumb" executors
+following dispatcher-written instructions. The dispatcher reads the config (model
+catalog with category weights) and designs the entire formation.
+
+## Category-Weighted Domain Routing
+Models have weighted scores per category (code, analysis, design, audit).
+Like bandwidth provider weighting — this model in this category has this weight.
+The dispatcher uses these to assign tasks.
+
+## DAG Formations
+Not just linear. Dispatcher can design fan-out → process → fan-in → judge,
+multi-judge with merge, audit stages, whatever the task requires.
+
+## Provider Gateway
+Abstracts model providers behind a uniform interface. Supports OpenRouter,
+direct provider APIs (z-ai, anthropic, deepseek, openai). LiteLLM for protocol
+translation.
+
+## Observability
+Every stage logged: prompt, response, model, tokens, cost, latency.
+Optional Langfuse integration for production tracing.

chimera_deliberation-0.1.0/.memory-bank/tech-context.md

@@ -0,0 +1,29 @@
+# Tech Context — Chimera
+
+## Language
+Python 3.11+ with full type hints. Pydantic v2 for all data models.
+
+## Key Dependencies
+- **LiteLLM** — provider gateway (OpenRouter, direct APIs)
+- **FastAPI** — REST API server
+- **Click + Rich** — CLI
+- **MCP SDK** — Hermes integration
+- **Pydantic v2** — data validation
+- **structlog** — structured JSON logging
+- **httpx** — async HTTP client
+- **pytest + pytest-asyncio** — testing
+
+## Packaging
+pipx with extras: `chimera[cli]`, `chimera[server]`, `chimera[mcp]`, `chimera[full]`
+
+## Testing
+`python -m pytest tests/ -x -q` — must pass before any commit.
+
+## Config
+Single `chimera.yaml` — model catalog, provider settings, formation presets,
+observability config. API keys via env vars or config file (config file is
+in .gitignore).
+
+## Logging
+structlog → stderr (JSON). trace_enabled logs full prompts/responses.
+Langfuse optional for production.

chimera_deliberation-0.1.0/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: chimera-deliberation
+Version: 0.1.0
+Summary: Dynamic multi-model deliberation gateway
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: litellm>=1.50.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: structlog>=24.0
+Provides-Extra: cli
+Requires-Dist: click>=8.0; extra == 'cli'
+Requires-Dist: rich>=13.0; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: click>=8.0; extra == 'full'
+Requires-Dist: fastapi>=0.115.0; extra == 'full'
+Requires-Dist: mcp>=1.0.0; extra == 'full'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'full'
+Requires-Dist: pytest-cov>=5.0; extra == 'full'
+Requires-Dist: pytest>=8.0; extra == 'full'
+Requires-Dist: rich>=13.0; extra == 'full'
+Requires-Dist: ruff>=0.6.0; extra == 'full'
+Requires-Dist: uvicorn[standard]>=0.30.0; extra == 'full'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.115.0; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.30.0; extra == 'server'

chimera_deliberation-0.1.0/README.md

@@ -0,0 +1,212 @@
+# Chimera — Dynamic Multi-Model Deliberation Gateway
+
+[![CI](https://github.com/totalwindupflightsystems/chimera/actions/workflows/ci.yml/badge.svg)](https://github.com/totalwindupflightsystems/chimera/actions/workflows/ci.yml)
+
+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.
+
+## Architecture
+
+```mermaid
+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
+
+```mermaid
+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
+
+```mermaid
+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
+```
+
+## Quick Start
+
+```bash
+# Install
+pipx install chimera[full]
+
+# Configure
+cp chimera.yaml.example chimera.yaml
+# Edit chimera.yaml with your API keys
+
+# Run
+chimera deliberate "Compare React, Vue, and Svelte for a real-time dashboard"
+
+# Or as an API server
+chimera serve
+# → http://localhost:8000/v1/chat/completions (OpenAI-compatible)
+# → http://localhost:8000/docs (OpenAPI docs)
+
+# Or as MCP server for Hermes/AI agents
+chimera-mcp
+```
+
+## Model Selection
+
+The dispatcher picks models using **category-weighted scoring**:
+
+| Category | What it measures |
+|---|---|
+| `code` | Programming, debugging, software engineering |
+| `analysis` | Data analysis, research, evaluation |
+| `reasoning` | Logic, math, complex problem-solving |
+| `design` | Creative work, UX, content generation |
+| `audit` | Fact-checking, safety, correctness review |
+
+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:
+
+```json
+{
+  "model": "auto",
+  "messages": [{"role": "user", "content": "..."}],
+  "dispatcher_model": "deepseek/deepseek-v4-flash",
+  "allowed_models": ["deepseek/deepseek-v4-pro", "z-ai/glm-5.2"],
+  "stage_models": {"worker_1": "openrouter/anthropic/claude-sonnet-4"}
+}
+```
+
+## Custom DAGs
+
+Send your own formation structure at request time:
+
+```json
+{
+  "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
+
+| Interface | Endpoint | Use |
+|---|---|---|
+| **REST API** | `POST /v1/chat/completions` | OpenAI-compatible drop-in |
+| **REST API** | `POST /v1/deliberate` | Full control (DAG, overrides, trace) |
+| **REST API** | `GET /v1/models` | Model catalog with weights |
+| **REST API** | `GET /v1/formations` | Available formation presets |
+| **CLI** | `chimera deliberate` | Command-line usage |
+| **MCP** | `chimera_deliberate` | Hermes / AI agent integration |
+
+## 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:
+
+| Provider | Direct API | Via OpenRouter | Models |
+|---|---|---|---|
+| **DeepSeek** | ✅ | ✅ | v4-flash, v4-pro, r1 |
+| **Anthropic** | — | ✅ | Sonnet 4, Opus 4.7/4.8, Haiku 4.5 |
+| **OpenAI** | — | ✅ | GPT-5.5, GPT-5.1 |
+| **xAI** | — | ✅ | Grok 4.20 |
+| **Google** | — | ✅ | Gemini 3.5 Flash, 3.1 Pro, 2.5 Flash |
+| **Z.AI** | ✅ (direct) | ✅ | GLM-5.2 |
+| **MoonshotAI** | — | ✅ | Kimi K2.7 Code, K2.6 |
+| **MiniMax** | — | ✅ | M3 |
+| **Meta** | — | ✅ | Llama 4 Maverick |

chimera_deliberation-0.1.0/bin/chimera-mcp-hermes

@@ -0,0 +1,3 @@
+#!/bin/bash
+# Chimera MCP wrapper for Hermes
+exec /home/kara/.hermes/hermes-agent/venv/bin/chimera-mcp /home/kara/chimera-v2/chimera.yaml

chimera_deliberation-0.1.0/bin/chimera-mcp-wrapper

@@ -0,0 +1,4 @@
+#!/bin/bash
+# Chimera MCP wrapper — ensures chimera.yaml is found
+cd /home/kara/chimera-v2 || exit 1
+exec /home/kara/.hermes/hermes-agent/venv/bin/chimera-mcp