Metadata-Version: 2.4
Name: brains-ai
Version: 1.0.1
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
Requires-Dist: starlette>=1.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/)
[![Python](https://img.shields.io/pypi/pyversions/brains-ai.svg)](https://pypi.org/project/brains-ai/)
[![CI](https://github.com/mekjr1/brains-v2/actions/workflows/ci.yml/badge.svg)](https://github.com/mekjr1/brains-v2/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/mekjr1/brains-v2/branch/main/graph/badge.svg)](https://codecov.io/gh/mekjr1/brains-v2)
[![Docker](https://img.shields.io/badge/ghcr.io-brains--v2-blue?logo=docker)](https://github.com/mekjr1/brains-v2/pkgs/container/brains-v2)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](#status--stability)

> **A smart local proxy for AI coding agents.**
> Faithful proxy by default — your explicit model picks are never silently rewritten.
> Opt-in classifier routing sends `brains/auto` to the cheapest model that can handle the request.
> One admin key, one audit log, one coordination plane shared across every agent.

> ⚠️ **Active alpha — use with care.**
> This project is under heavy development by a single maintainer. The CLI surface, on-wire
> contracts, and dashboard internals can change between releases. Pin to a specific version
> (`pipx install brains-ai==0.1.0a12`) for anything beyond local experimentation. See
> [Status & stability](#status--stability) below.

## 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. By default
it is a **faithful proxy** — every request is passed through to the
exact provider/model you asked for, with `response.model` rewritten to
the real upstream id (no opaque aliasing). Opt-in classifier routing,
gated behind the `brains/auto` alias, classifies each call (trivial /
code_fix / architecture / research / docs_lookup) and routes it to the
cheapest provider + model that can handle that class. 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.** Visibility into every dollar your agents spend, the
ability to swap providers without touching client code, and one shared
coordination plane 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-ai setup                 # init DB + workspace + admin key + wire MCP
brains-ai serve-all             # supervise gateway + dashboard + MCP
```

To keep it running across reboots without a terminal, install it as a
user-level autostart service instead of `serve-all`:

```bash
brains-ai service install       # Windows Task Scheduler / macOS launchd / Linux systemd --user
```

Prefer not to install Python at all? Use the [Docker image](https://github.com/mekjr1/brains-v2/pkgs/container/brains-v2) instead.
Want to hack on brains? Use an editable git checkout — see [CONTRIBUTING.md](CONTRIBUTING.md).

## Quickstart

1. **Install**
   ```bash
   pipx install brains-ai
   ```
2. **One-shot bootstrap** — `setup` is idempotent; re-run it any time:
   ```bash
   brains-ai setup
   ```
   This initializes the DB, registers the current directory as a workspace,
   provisions an admin key (printed to stderr — record it now), wires brains
   into every detected agent's MCP config, and prints the next command.
3. **Start the stack**
   ```bash
   brains-ai serve-all     # gateway :8787, dashboard :9876, MCP :9877
   ```
   Or run it as an autostart service so it survives reboots and login:
   ```bash
   brains-ai service install   # registers + starts; comes back at every login
   ```
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_AUTH_TOKEN=<your-brains-admin-key>
   ```

   …or use the **one-shot launcher** that sets those for you:
   ```bash
   brains-ai run claude       # launches Claude Code through the gateway
   brains-ai run copilot      # launches GitHub Copilot CLI through the gateway
   ```

That's it. Your client now sees the gateway as a faithful proxy: ask for
`claude-sonnet-4.6` and you get `claude-sonnet-4.6`. Ask for
`brains/auto` and the classifier picks the cheapest model that can
handle the request.

## Faithful proxy + opt-in routing

Brains was rebuilt around a single contract: **never silently rewrite
the client's model choice.**

| Request model                 | Behaviour |
|-------------------------------|-----------|
| `provider/model` (e.g. `anthropic/claude-sonnet-4.6`) | Direct match — routes to the exact upstream, no classifier. |
| Catalog id (e.g. `claude-sonnet-4.6`)                 | Direct match — routes to the upstream id with no silent downgrade. |
| `brains/cheap` \| `brains/default` \| `brains/strong` \| `brains/deep` | Tier alias — resolved to the operator-pinned model for that tier. |
| `brains/auto`                  | Classifier runs (only when `routing.enabled = true`) and picks a model. |
| Unknown id                     | `404 model_not_found`. The classifier never rewrites an explicit request. |

`response.model` is **always** rewritten back to the actual upstream
model that served the request — both on Anthropic and OpenAI surfaces,
streaming and non-streaming. Hyphen forms (`brains-auto`, etc.) remain
accepted as legacy aliases.

## What's inside

- **Smart gateway** — Anthropic- *and* OpenAI-compatible endpoints
  (`/v1/messages`, `/v1/chat/completions`, `/v1/responses`),
  faithful-proxy router with toggleable classifier (`routing.enabled`),
  multi-provider (Anthropic, OpenAI, GitHub Copilot, Ollama, OpenRouter,
  LiteLLM, …), namespaced `/v1/models`.
- **Coordination plane** — sessions, tasks, handoffs, advisory locks,
  squads (leader-routed team assignment), autopilots (cron- or
  webhook-triggered recurring work with per-fire run audit), peer-help
  RPC, brain-session resume across tool restarts, multi-operator +
  per-workspace visibility.
- **MCP server** — every brains capability surfaced as an MCP tool;
  `brains-ai setup` (or `brains-ai 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.
- **Launcher** — `brains-ai run <tool>` spawns the target CLI
  (Claude Code, Copilot CLI, …) with the right `ANTHROPIC_*` /
  `OPENAI_*` env-vars already pointing at your local gateway. Useful
  for quickly toggling between vanilla CLI and brains.

## CLI surface

| Command | What it does |
|---|---|
| `brains-ai setup` | First-run wizard: init DB → register workspace → ensure admin key → wire MCP → status (`--service` to also install the autostart service) |
| `brains-ai serve-all` | Supervise gateway + dashboard + MCP in one process |
| `brains-ai service install` / `uninstall` / `status` / `start` / `stop` / `restart` / `logs` | Run serve-all as a user OS service (Windows Task Scheduler / macOS launchd / Linux systemd `--user`) — autostart at login + restart on failure |
| `brains-ai serve` / `brains-ai dashboard` / `brains-ai mcp` | Run a single component |
| `brains-ai features` | List optional subsystems (postgres, telegram, slack, otel, …) and install/enable them |
| `brains-ai wire` | Register / refresh brains MCP entries in detected agent configs |
| `brains-ai unwire` | Remove brains MCP entries from agent configs |
| `brains-ai run <tool>` | Spawn `claude` / `copilot` with gateway env-vars populated; forwards extra flags |
| `brains-ai admin-key show [--reveal]` | Show / rotate the admin key |
| `brains-ai copilot-login` / `copilot-status` / `copilot-logout` | OAuth device-code flow for `github_copilot` provider |
| `brains-ai version` | Print brains version + schema version + installed extras |

> **Pre-1.0 breaking renames.** `brains-ai` is the single binary. The
> `brains` binary, the `install` verb, and the `claude-brains` /
> `copilot-brains` shims were removed in 0.1.0a8 — use `brains-ai`,
> `brains-ai features`, and `brains-ai run claude` / `brains-ai run copilot`
> respectively. Alpha releases may break renames without a deprecation
> cycle; every removal is documented in [CHANGELOG.md](CHANGELOG.md).

## Documentation

- [Providers & routing](docs/providers.md) — supported providers, config
  examples, GitHub Copilot OAuth flow, error envelopes
- [Agent wiring](docs/wiring.md) — `brains-ai wire` reference, per-tool
  configs (Claude Code, 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
- [Remote install](docs/REMOTE_INSTALL.md) — reverse-proxy + MCP +
  multi-machine wiring
- [Protocols](docs/protocols.md) — wire format for coordination-plane tools
- [Security](docs/security.md) — auth model, leak posture, rotation,
  redaction
- [Decision records](docs/decisions/) — load-bearing design choices
- [Roadmap](docs/roadmap.md) · [Changelog](CHANGELOG.md)

## Status & stability

brains is **pre-1.0 alpha** and developed by a single maintainer in the open.

- **Releases are pinned to a single maintainer.** All publishing to PyPI and
  GHCR is gated behind a protected `v*` tag rule that only the repo owner can
  trigger. Forks may build their own; the canonical artifact only ships from
  this repository.
- **Backward compatibility is best-effort within an alpha.** Pre-1.0
  alphas may rename or remove CLI/on-wire surfaces without a
  deprecation cycle; every breaking change is documented in
  [CHANGELOG.md](CHANGELOG.md). Stability tightens at beta.
- **`main` is the supported branch.** Older alphas receive no fixes — pin to
  the latest tag for anything you depend on.
- **Status badge** above will move to `beta` once the router contract,
  dashboard, and admin surface stop changing release-over-release.

## Contributing

Issues and well-scoped PRs are welcome — but please open an issue (or use
[Discussions](https://github.com/mekjr1/brains-v2/discussions)) before
sending a non-trivial PR. See [CONTRIBUTING.md](CONTRIBUTING.md) and the
[Code of Conduct](CODE_OF_CONDUCT.md). For security issues, follow the
private disclosure process in [SECURITY.md](SECURITY.md) — do not open a
public issue.

## License

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