chimera-agent 0.4.1__tar.gz

chimera_agent-0.4.1/.dockerignore

@@ -0,0 +1,24 @@
+# Keep the build context small and secrets out of the image.
+.git
+.github
+.venv
+venv
+__pycache__
+*.pyc
+*.pyo
+.pytest_cache
+.mypy_cache
+.ruff_cache
+.chimera
+dist
+build
+*.egg-info
+.env
+.env.*
+!.env.example
+tests
+benchmarks
+docs
+assets
+*.md
+!README.md

chimera_agent-0.4.1/.env.example

@@ -0,0 +1,148 @@
+# Chimera configuration (copy to .env and fill what you use).
+# All variables are optional at import time — the agent only needs a key
+# for the providers you actually call.
+
+# --- Provider keys (use whichever you have) ---
+# Recommended: a single OpenRouter key unlocks 100+ models for the fusion panel.
+OPENROUTER_API_KEY=
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+GEMINI_API_KEY=
+DEEPSEEK_API_KEY=
+
+# --- Credential pools (optional): multiple keys per provider, rotated round-robin ---
+# Spreads load and fails over to the next key if one is rate-limited / invalid.
+# When set, the pool replaces the single key above for that provider.
+# e.g. CHIMERA_OPENROUTER_KEYS=sk-or-key1,sk-or-key2,sk-or-key3
+CHIMERA_OPENROUTER_KEYS=
+CHIMERA_OPENAI_KEYS=
+CHIMERA_ANTHROPIC_KEYS=
+CHIMERA_GEMINI_KEYS=
+CHIMERA_DEEPSEEK_KEYS=
+
+# --- Default models (LiteLLM-style "provider/model" slugs) ---
+# Single fast model used for Tier 1 and cheap tasks. Any LiteLLM slug works
+# (openai/..., anthropic/..., gemini/..., ollama/..., openrouter/..., etc.).
+CHIMERA_DEFAULT_MODEL=openrouter/openai/gpt-5.5
+
+# Custom endpoint for self-hosted / OpenAI-compatible servers (Ollama, vLLM, ...).
+# e.g. CHIMERA_API_BASE=http://localhost:11434  with CHIMERA_DEFAULT_MODEL=ollama/llama3
+CHIMERA_API_BASE=
+
+# Comma-separated fallback chain: if the primary model errors, the next is tried.
+# e.g. CHIMERA_FALLBACK_MODELS=openrouter/openai/gpt-4o-mini,ollama/llama3
+CHIMERA_FALLBACK_MODELS=
+
+# Execution sandbox for the shell tool: local (host, default) or docker (isolated).
+# docker runs each command in an ephemeral, network-off container; see docker/README.md.
+CHIMERA_SANDBOX=local
+CHIMERA_SANDBOX_IMAGE=python:3.12-slim
+# Optional hardened OCI runtime for the docker sandbox. Set to runsc to run under gVisor
+# (userspace kernel; intercepts syscalls, shrinks host-kernel attack surface). Requires
+# gVisor installed on the host. Empty = the daemon default (runc).
+CHIMERA_SANDBOX_RUNTIME=
+
+# Per-session tool allowlist/denylist (comma-separated tool names). An allowlist grants
+# ONLY those tools (everything else is dropped, not just gated); empty = no restriction.
+# The denylist removes tools even if allowed. CLI --allow-tools/--deny-tools override these.
+CHIMERA_TOOL_ALLOWLIST=
+CHIMERA_TOOL_DENYLIST=
+
+# Cache identical tool-free completions (HORIZON prompt caching): on | off (default off).
+# Saves cost/latency for repeated reasoning turns (fusion, planner, benchmarks).
+CHIMERA_CACHE=off
+
+# Long-term memory backend: json (default, zero-dependency) or sqlite (SQLite + FTS5
+# full-text recall that scales past the JSON store). Both persist under CHIMERA_HOME.
+CHIMERA_MEMORY_BACKEND=json
+
+# Discord bot token — only needed for `chimera serve --discord` (install the extra:
+# `uv sync --extra messaging`). Create a bot at https://discord.com/developers, enable the
+# Message Content intent, and paste its token here. Leave empty if you don't use Discord.
+CHIMERA_DISCORD_BOT_TOKEN=
+
+# Telegram bot token — only needed for `chimera serve --telegram` (no extra dependency).
+# Create a bot with @BotFather, then paste the token here. Leave empty if unused.
+CHIMERA_TELEGRAM_BOT_TOKEN=
+
+# Slack tokens — only needed for `chimera serve --slack` (install `uv sync --extra
+# messaging`). Enable Socket Mode on your app: the bot token is xoxb-... and the
+# app-level token is xapp-... . Leave empty if unused.
+CHIMERA_SLACK_BOT_TOKEN=
+CHIMERA_SLACK_APP_TOKEN=
+
+# WhatsApp Cloud API — lets the agent SEND WhatsApp messages via the send_message tool
+# (works in any `chimera serve` mode). Create a Meta app + WhatsApp product to get these.
+# Two-way (receiving) needs a public Meta webhook wired to your endpoint; see the docs.
+CHIMERA_WHATSAPP_ACCESS_TOKEN=
+CHIMERA_WHATSAPP_PHONE_NUMBER_ID=
+# For two-way WhatsApp: point the Meta app webhook at https://<host>/whatsapp and set the
+# same verify token here (any string you choose). `chimera serve` then serves it.
+CHIMERA_WHATSAPP_VERIFY_TOKEN=
+
+# Signal — two-way via a signal-cli-rest-api bridge you run (Docker:
+# bbernhard/signal-cli-rest-api), linked to your number. `chimera serve --signal`.
+CHIMERA_SIGNAL_API_URL=          # e.g. http://localhost:8080
+CHIMERA_SIGNAL_NUMBER=           # this bot's Signal number, E.164
+
+# Auto-fuse error-sensitive turns in solve/crew without passing --fuse: on | off (default
+# off, since fusion costs 2-3x). When on, the cost-aware router still keeps cheap/tool
+# turns single-model and only fuses deep or exact-answer turns (arithmetic, counting, ...).
+CHIMERA_AUTO_FUSE=off
+
+# --- Fusion engine (panel -> judge -> synthesizer) ---
+# Comma-separated panel of models. Diversity (frontier + open) helps,
+# but the synthesis step is what drives the lift. The default below is a frontier
+# panel — best quality, but it costs real money on every fused turn.
+#
+# Budget tip: for cheap-but-reliable fusion, this panel works well and stays fast:
+#   CHIMERA_FUSION_PANEL=openrouter/deepseek/deepseek-chat,openrouter/openai/gpt-4o-mini,openrouter/meta-llama/llama-3.3-70b-instruct
+# Avoid OpenRouter ":free" model slugs in a panel: they rate-limit (HTTP 429) under
+# real load, so fusion silently degrades to whatever paid model is left in the panel.
+CHIMERA_FUSION_PANEL=openrouter/anthropic/claude-opus-4-8,openrouter/openai/gpt-5.5,openrouter/google/gemini-3.1-pro
+CHIMERA_FUSION_JUDGE=openrouter/anthropic/claude-opus-4-8
+CHIMERA_FUSION_SYNTHESIZER=openrouter/anthropic/claude-opus-4-8
+
+# Selective fusion (ON by default). Probe the first CHIMERA_FUSION_PROBE_K panel models;
+# if they agree closely (a cheap LOCAL text-similarity check, no extra model call), skip
+# the rest of the panel + the judge and synthesize from the agreeing answers. If they
+# disagree, escalate to the full pipeline — which costs exactly the same as full fusion,
+# so hard turns are never penalized. In 3 runs of `chimera fusion-bench --tasks hard` this
+# cut tokens ~20-28% and was correct on every turn it short-circuited (16/16). Set to
+# "full" to always run the whole panel + judge.
+CHIMERA_FUSION_MODE=selective
+CHIMERA_FUSION_PROBE_K=2
+CHIMERA_FUSION_AGREEMENT=0.8
+
+# --- Optional feature credentials (pre-set slots; set only what you use) ---
+# Run `chimera features` to see which are active. Fill a slot and the matching
+# capability lights up. Vision / Deliverable / Pets are built in (no key).
+TAVILY_API_KEY=          # Web Search & Extract -> the web_search tool auto-registers
+BRAVE_API_KEY=           #   (alternative web search provider; same pattern)
+SERPAPI_API_KEY=         #   (alternative web search provider; same pattern)
+X_BEARER_TOKEN=          # X (Twitter) search
+STABILITY_API_KEY=       # (reserved) alternative image provider
+ELEVENLABS_API_KEY=      # lights up the text_to_speech reference tool
+SPOTIFY_CLIENT_ID=       # Spotify (OAuth app); import its OpenAPI spec as tools
+SPOTIFY_CLIENT_SECRET=
+# OPENAI_API_KEY (above) lights up the generate_image reference tool.
+# SMTP lights up the send_email reference tool (all three must be set):
+CHIMERA_SMTP_HOST=       # e.g. smtp.gmail.com
+CHIMERA_SMTP_PORT=587
+CHIMERA_SMTP_USER=       # your SMTP username / email
+CHIMERA_SMTP_PASSWORD=   # your SMTP password / app password
+CHIMERA_SMTP_FROM=       # optional From address (defaults to SMTP_USER)
+# IMAP lights up the read_email reference tool:
+CHIMERA_IMAP_HOST=       # e.g. imap.gmail.com
+CHIMERA_IMAP_PORT=993
+CHIMERA_IMAP_USER=
+CHIMERA_IMAP_PASSWORD=
+# An iCalendar (.ics) feed URL lights up the calendar_events reference tool:
+CHIMERA_CALENDAR_ICS_URL=
+# Browser automation needs `pip install playwright && playwright install`.
+# Computer use (desktop control) is advanced and off the server path.
+
+# --- Behaviour ---
+CHIMERA_LOG_LEVEL=INFO
+# Where Chimera keeps its externalized state (memory, experience buffer).
+CHIMERA_HOME=.chimera

chimera_agent-0.4.1/.gitattributes

@@ -0,0 +1,5 @@
+# Normalize line endings to LF in the repository (Python project, cross-platform).
+* text=auto eol=lf
+*.png binary
+*.jpg binary
+*.gif binary

chimera_agent-0.4.1/.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# Enables the "Sponsor" button on the GitHub repo.
+# Chimera is free and open-source; donations support its development.
+custom: ["https://donate.stripe.com/9B63cofM491m4SBfe177O00"]

chimera_agent-0.4.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Report a problem so we can fix it
+title: "[bug] "
+labels: bug
+---
+
+## Describe the bug
+A clear and concise description of what went wrong.
+
+## To reproduce
+Steps or the exact command(s):
+
+```bash
+chimera ...
+```
+
+## Expected behavior
+What you expected to happen.
+
+## Environment
+- Chimera version: `uv run chimera version`
+- OS:
+- Python: `python --version`
+- Provider(s): (OpenRouter / OpenAI / Anthropic / ...)
+
+## Logs / output
+Paste any relevant output (redact secrets).

chimera_agent-0.4.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Questions & ideas
+    url: https://github.com/brcampidelli/chimera-agent/discussions
+    about: Ask a question, share what you built, or float an idea in Discussions.
+  - name: Security vulnerability
+    url: https://github.com/brcampidelli/chimera-agent/security/advisories/new
+    about: Please report security issues privately (see SECURITY.md), not as public issues.

chimera_agent-0.4.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest an idea or capability
+title: "[feat] "
+labels: enhancement
+---
+
+## Problem / motivation
+What are you trying to do, and why is it hard today?
+
+## Proposed solution
+What you'd like to see. Which tier/subsystem does it touch (fusion, core, evolution,
+governance, orchestration, ecosystem, integrations, ...)?
+
+## Alternatives considered
+Other approaches you thought about.
+
+## Additional context
+Links, references, or papers.

chimera_agent-0.4.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+## What & why
+Briefly describe the change and the motivation.
+
+## How to test
+Commands or steps to verify the change.
+
+## Checklist
+- [ ] `uv run ruff check .` passes
+- [ ] `uv run mypy chimera` passes (strict)
+- [ ] `uv run pytest -q` passes
+- [ ] New logic has tests
+- [ ] Docs/README updated if behavior changed
+- [ ] Commit messages follow Conventional Commits
+
+## Related issues
+Closes #

chimera_agent-0.4.1/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: lint · type-check · test
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Ruff (lint)
+        run: uv run ruff check .
+
+      - name: Mypy (strict type-check)
+        run: uv run mypy chimera
+
+      - name: Pytest
+        run: uv run pytest -q
+
+  integration:
+    name: live integration (real provider)
+    runs-on: ubuntu-latest
+    needs: quality
+    # Only on direct pushes to main (not fork PRs), where the secret is available.
+    # The test self-skips when the secret is unset, so this job is green either way.
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --extra dev --extra mcp
+
+      - name: Integration smoke test
+        env:
+          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+        run: uv run pytest -m integration -q

chimera_agent-0.4.1/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+# Publishes the package to PyPI using OIDC Trusted Publishing — there is NO API
+# token stored in the repo or entered by anyone. PyPI verifies the workflow's
+# short-lived OIDC identity instead. One-time setup on PyPI (pending publisher):
+#   https://pypi.org/manage/account/publishing/
+#   Owner: brcampidelli · Repo: chimera-agent · Workflow: publish.yml · Env: (blank)
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  pypi-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # mint the OIDC token PyPI checks — this is the whole point
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build wheel + sdist
+        run: uv build
+
+      - name: Publish to PyPI (Trusted Publishing — no token)
+        uses: pypa/gh-action-pypi-publish@release/v1

chimera_agent-0.4.1/.github/workflows/quality-bench.yml

@@ -0,0 +1,39 @@
+name: quality-bench
+
+# A quality gauge, not a build gate: runs `chimera solve` on the local pytest-graded task set with a
+# cheap/free model and reports the pass-rate (does a change move the number?). Manual-trigger only so
+# it never spends API on a routine push — add a `schedule:` block if you want it periodic.
+on:
+  workflow_dispatch:
+    inputs:
+      model:
+        description: "OpenRouter model slug (a free one to avoid cost)"
+        default: "openrouter/qwen/qwen3-coder:free"
+      timeout:
+        description: "Per-solve timeout in seconds"
+        default: "300"
+
+jobs:
+  bench:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Install (with dev extras for pytest)
+        run: uv sync --extra dev
+      - name: Run the quality gauge
+        env:
+          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+          BENCH_MODEL: ${{ github.event.inputs.model }}
+          BENCH_TIMEOUT: ${{ github.event.inputs.timeout }}
+        run: uv run --no-sync python bench/local_lift/run_ci.py
+      - name: Upload results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: quality-bench-results
+          path: bench/local_lift/results/ci.json
+          if-no-files-found: ignore

chimera_agent-0.4.1/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# Virtual envs / uv
+.venv/
+.uv/
+uv.lock
+
+# Env / secrets
+.env
+.env.local
+*.key
+
+# Caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.cache/
+
+# Chimera runtime data (state lives outside the LLM context)
+.chimera/
+data/
+*.sqlite
+*.sqlite3
+*.db
+
+# OS / editors
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# mkdocs build output
+site/
+
+# Local benchmark run outputs (harness + tasks are tracked; per-run results are not)
+bench/local_lift/results/
+
+# Terminal-Bench official runner: local venv, built wheel, run outputs (tracked: scripts only)
+bench/terminal_bench/.venv/
+bench/terminal_bench/dist/
+bench/terminal_bench/results/