Metadata-Version: 2.4
Name: brains-ai
Version: 0.1.0a5
Summary: Local-first control plane and coordination layer for AI coding agents
Author: mekjr1 and brains contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/mekjr1/brains-v2
Project-URL: Repository, https://github.com/mekjr1/brains-v2
Project-URL: Issues, https://github.com/mekjr1/brains-v2/issues
Keywords: ai-agents,coding-agents,control-plane,openai-compatible,mcp,local-first
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.27
Requires-Dist: pydantic>=2.5
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: httpx>=0.27
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: typer>=0.12
Requires-Dist: mcp>=1.0
Requires-Dist: jinja2>=3.1
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Provides-Extra: litellm
Requires-Dist: litellm>=1.40; extra == "litellm"
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29; extra == "postgres"
Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=21.0; extra == "telegram"
Provides-Extra: slack
Requires-Dist: slack_sdk>=3.27; extra == "slack"
Provides-Extra: whatsapp
Requires-Dist: httpx>=0.27; extra == "whatsapp"
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.25; extra == "otel"
Requires-Dist: opentelemetry-sdk>=1.25; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25; extra == "otel"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.46b0; extra == "otel"
Provides-Extra: all
Requires-Dist: litellm>=1.40; extra == "all"
Requires-Dist: asyncpg>=0.29; extra == "all"
Requires-Dist: psycopg[binary]>=3.1; extra == "all"
Requires-Dist: python-telegram-bot>=21.0; extra == "all"
Requires-Dist: slack_sdk>=3.27; extra == "all"
Requires-Dist: opentelemetry-api>=1.25; extra == "all"
Requires-Dist: opentelemetry-sdk>=1.25; extra == "all"
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25; extra == "all"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.46b0; extra == "all"
Dynamic: license-file

# Brains

[![PyPI](https://img.shields.io/pypi/v/brains-ai.svg)](https://pypi.org/project/brains-ai/)
[![Docker](https://img.shields.io/badge/ghcr.io-brains--v2-blue?logo=docker)](https://github.com/mekjr1/brains-v2/pkgs/container/brains-v2)
[![CI](https://github.com/mekjr1/brains-v2/actions/workflows/ci.yml/badge.svg)](https://github.com/mekjr1/brains-v2/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> **A smart local proxy for AI coding agents.**
> Routes each request to the right-sized model (no more
> flagship-by-default), proves the dollars saved on the dashboard, and
> lets every agent share one brain — sessions, tasks, handoffs,
> recurring jobs.

## Why brains

**The problem.** Every AI coding tool ships its own provider, its own
config, its own session memory. Each one defaults to a flagship model
for *every* request — including the trivial ones — so you pay
sonnet / o1 rates to "rename this variable." Worse, providers quietly
dumbify their flagship tiers under load and then upsell you to the next
tier.

**What brains does.** A local gateway in front of your agents. Every
request is classified (trivial / code_fix / architecture / research /
docs_lookup), routed to the cheapest provider + model that can handle
that class, and logged. Anthropic- *and* OpenAI-compatible endpoints
mean Claude Code, Codex, Copilot CLI, Cursor, and aider all work with
no code changes — just a base-URL swap.

**What you get.** A real number, on the dashboard, every day:
*"$X saved this week vs. flagship-default."* One admin key. One audit
log. One coordination fabric so your agents share sessions, hand off
tasks, and stop stepping on each other.

## Install

```bash
pipx install brains-ai          # or: uv tool install brains-ai
brains up                       # init + gateway + dashboard + MCP
brains wire                     # register brains into every detected agent
```

Prefer not to install Python at all? Use the Docker image instead.
Want to hack on brains? Use a git checkout. Both paths are documented in
[Operations](docs/operations.md).

## What's inside

- **Smart gateway** — Anthropic- *and* OpenAI-compatible endpoints
  (`/v1/messages`, `/v1/chat/completions`, `/v1/responses`),
  classifier-based routing with an on/off toggle *(toggle + full
  Anthropic streaming / tool-use facade land in v1.1 — see
  [Roadmap](docs/roadmap.md))*, per-request savings ledger *(v1.1)*,
  multi-provider (Anthropic, OpenAI, GitHub Copilot, Ollama, OpenRouter,
  LiteLLM, …).
- **Coordination plane** — sessions, tasks, handoffs, advisory locks,
  recurring jobs, peer-help RPC, brain-session resume across tool
  restarts, multi-operator + per-workspace visibility.
- **MCP server** — every brains capability surfaced as an MCP tool;
  one command (`brains wire`) registers it into Claude Code, Codex,
  Copilot CLI, and Cursor.
- **Dashboard + admin** — provider health, runtime config (no
  restarts), audit log, operator presence, runtime overlay editor.
  *Savings panel and provider-first config UI land in v1.1.*

## Quickstart

1. **Install**
   ```bash
   pipx install brains-ai
   ```
2. **Start the stack**
   ```bash
   brains up      # supervises gateway :8787, dashboard :9876, MCP :9877
   ```
   On first run, brains generates an admin key and prints it to stderr.
   View it later with `brains admin-key show --reveal`.
3. **Wire your agents**
   ```bash
   brains wire                       # all detected tools (SSE, global)
   brains wire --status              # show what's registered
   ```
4. **Open the dashboard** — <http://127.0.0.1:9876/admin> and sign in
   with the admin key.
5. **Point a tool at the gateway** (so its traffic flows through brains):
   ```bash
   # OpenAI-compatible (Codex, Copilot CLI, aider, Continue, …)
   export OPENAI_BASE_URL=http://127.0.0.1:8787/v1
   export OPENAI_API_KEY=<your-brains-admin-key>

   # Claude Code (Anthropic-compatible)
   export ANTHROPIC_BASE_URL=http://127.0.0.1:8787
   export ANTHROPIC_API_KEY=<your-brains-admin-key>
   ```

That's it. Every request is now classified, routed, audited, and
shared.

## Documentation

- [Providers & routing](docs/providers.md) — supported providers, config
  examples, GitHub Copilot OAuth flow, error envelopes
- [Agent wiring](docs/wiring.md) — `brains wire` reference, strict
  enforcement, per-tool configs (Claude Desktop, Cursor, Copilot CLI,
  Codex)
- [Operations](docs/operations.md) — Docker, dev install, upgrades,
  extras, admin-key management, auth & secrets, dashboard internals,
  full CLI catalog
- [Architecture](docs/architecture.md) — runtime flow, components,
  process topology
- [Protocols](docs/protocols.md) — wire format for coordination-plane
  tools
- [Decision records](docs/decisions/) — load-bearing design choices
- [Roadmap](docs/roadmap.md) · [Changelog](CHANGELOG.md) · [Security](SECURITY.md)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) and the
[Code of Conduct](CODE_OF_CONDUCT.md). For security issues, follow the
disclosure process in [SECURITY.md](SECURITY.md).

## License

[MIT](LICENSE) © mekjr1 and brains contributors.
