Metadata-Version: 2.4
Name: tanglebrain
Version: 0.23.0
Summary: A local-first, config-driven LLM router across OpenAI-compatible backends you own.
Author: Jason Vaughan
License: MIT
Project-URL: Homepage, https://github.com/Jason-Vaughan/TangleBrain
Project-URL: Repository, https://github.com/Jason-Vaughan/TangleBrain
Project-URL: Changelog, https://github.com/Jason-Vaughan/TangleBrain/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/Jason-Vaughan/TangleBrain/issues
Project-URL: Releases, https://github.com/Jason-Vaughan/TangleBrain/releases
Keywords: llm,router,ollama,openai-compatible,litellm,local-llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.27
Requires-Dist: PyYAML<7,>=6.0
Provides-Extra: delegate
Requires-Dist: mcp<3,>=2; extra == "delegate"
Provides-Extra: dev
Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
Requires-Dist: mypy<2.4,>=2.3; extra == "dev"
Requires-Dist: types-PyYAML<7,>=6; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/Jason-Vaughan/project-assets/main/tanglebrain-logo-512.png" alt="TangleBrain logo" width="180">
</p>

# TangleBrain

[![CI](https://github.com/Jason-Vaughan/TangleBrain/actions/workflows/ci.yml/badge.svg)](https://github.com/Jason-Vaughan/TangleBrain/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/tanglebrain)](https://pypi.org/project/tanglebrain/)
[![Python](https://img.shields.io/pypi/pyversions/tanglebrain)](https://pypi.org/project/tanglebrain/)
[![License](https://img.shields.io/badge/license-MIT-green?style=for-the-badge)](LICENSE)

```bash
# 1-Click Installation (PyPI)
pip install tanglebrain
```

A **local-first, config-driven router across OpenAI-compatible backends you own.**

## The Problem: Cloud-by-Default Routing

Most AI tooling sends **every** request to a paid cloud API by default — even the trivial ones, even
when you already run capable models on hardware you own. The spend accrues invisibly, you're coupled
to a single provider's endpoint, and the moment you want to blend a local model, an authenticated CLI
you already pay for, and a bring-your-own-key API, you end up hand-wiring glue and editing source just
to change *where* a request goes. There's no single, plain place to declare "here are the backends I
have — route across them, in this order," and no measurement of what you're actually spending versus
avoiding.

**This is routing debt: vendor lock-in, invisible spend, and routing logic that lives in code instead
of config.**

## The Solution: A Local-First Router You Own

TangleBrain keeps the whole roster of backends in one editable YAML file and routes each request to
the backend you've configured — a free local model server by default. It favors credentials you
already hold: your **local models** and your **authenticated, OAuth-logged-in tools** come first,
while **raw API keys stay a separate, explicitly-gated opt-in** rather than the default (it never
injects a key into a CLI — your tool uses its own session). An optional classifier can **read each
request and route by its complexity** — sending the grunt work to your free local model where it's
cheap, and reserving heavier backends for what actually needs them. And every routed task is logged
with an **estimated cloud-equivalent cost**, so you can see what you're spending versus avoiding.
Adding or removing a backend is a config edit, not a code change.

## Standalone, or part of the Tangle family

TangleBrain runs entirely on its own — clone it, point it at your backends, and go. It's MIT-licensed
and open to contributors: forks and pull requests are welcome. It's also designed to drop in
seamlessly alongside [TangleClaw](https://github.com/Jason-Vaughan/TangleClaw) and the wider **Tangle
family** of tools, so it works the same whether you run it solo or as part of that ecosystem.

**Status:** publicly released and actively developed — see the
[latest release](https://github.com/Jason-Vaughan/TangleBrain/releases) and [`CHANGELOG.md`](https://github.com/Jason-Vaughan/TangleBrain/blob/main/CHANGELOG.md).

## What it does

- **Local-first routing** — ships pointing at a free local model server; nothing leaves your machine
  unless you configure a backend that does.
- **OAuth- and local-first credentials** — prefers your local models and your authenticated
  (OAuth-logged-in) tool sessions; it never injects an API key into a CLI. The raw-API-key tier is a
  deliberate opt-in, off by default behind explicit gates.
- **Prompt-aware routing** — an optional classifier reads each request and sends trivial / grunt work
  straight to your free local model where it's cheap, reserving heavier backends for what actually
  needs them (off by default, fails safe).
- **Config-driven roster** — every routable backend is one entry in a plain YAML list; add, remove,
  or reorganize backends by editing config.
- **Pluggable CLI-backed orchestration** — drive authenticated command-line tools as orchestrators,
  with rotation and failover across them for resilience.
- **Multi-target sub-task delegation (scatter-gather)** — an orchestrator can decompose a task and
  offload sub-tasks through MCP tools: to the free local backend, or to any configured backend **by id
  or by capability** (a `good_at` tag), and **fan several out concurrently** in one call. Each
  delegated sub-call is metered and linked back to the specific top-level task that spawned it, then
  the orchestrator reviews and synthesises the results.
- **Cost measurement** — every routed task is logged with an estimated cloud-equivalent cost;
  `tanglebrain --stats` rolls up what you've spent versus avoided.
- **Your prompts are not in the log** — text is measured, then discarded; only derived counts and
  routing metadata are written. There is no redaction step to trust because nothing needing
  redaction reaches the writer. The one qualification is on the error path, stated in full under
  [Cost avoided](#cost-avoided-measurement).
- **Knob GUI** — a localhost panel to view the roster, pricing, and rollup, edit a focused set of
  config knobs, and run a prompt.
- **Gated paid-API tier** — bring-your-own-key overflow, off by default behind two independent
  switches.

See [`ARCHITECTURE.md`](https://github.com/Jason-Vaughan/TangleBrain/blob/main/ARCHITECTURE.md) for how the pieces fit together, [`CHANGELOG.md`](https://github.com/Jason-Vaughan/TangleBrain/blob/main/CHANGELOG.md)
for development history, and [`DISCLAIMER.md`](https://github.com/Jason-Vaughan/TangleBrain/blob/main/DISCLAIMER.md) for the opt-in / bring-your-own-key
posture.

## Tiers

| Tier | Example | Default |
|---|---|---|
| **Free local** | a local model via Ollama / any OpenAI-compatible server you run | **active** |
| **Subscription / authenticated CLI** | command-line tools you've installed and logged in (e.g. `claude -p`, `codex exec`, `agy -p`) | opt-in (commented) |
| **Paid API** | bring-your-own-key overflow (any OpenAI-compatible endpoint you hold a key for) | opt-in, off by default |

> **Opt-in adapters & your responsibility.** The subscription / authenticated-CLI tier and the
> paid-API tier are **opt-in** — you enable them by editing your own roster. Driving an authenticated
> CLI is your responsibility under that provider's Terms of Service, and the paid tier is
> bring-your-own-key. Read [`DISCLAIMER.md`](https://github.com/Jason-Vaughan/TangleBrain/blob/main/DISCLAIMER.md) before enabling either.

## Install

Requires Python ≥ 3.10.

```sh
pip install tanglebrain               # from PyPI ("tanglebrain[delegate]" adds the MCP server)
```

Or for development, from a clone:

```sh
make venv          # create .venv and install -e . (dev deps included)
```

## Use

The roster of routable backends is a plain, editable YAML list — adding or removing a backend is a
config edit, not a code change. The shipped
[`tanglebrain/config/roster.yaml`](https://github.com/Jason-Vaughan/TangleBrain/blob/main/tanglebrain/config/roster.yaml) is only a **generic example** with
a single active entry (a local Ollama backend); keep your real roster **outside the repo** so updates
never clobber it. It's auto-discovered in order: `$TANGLEBRAIN_ROSTER` →
`~/.config/tanglebrain/roster.yaml` → the packaged example. Copy the example to
`~/.config/tanglebrain/roster.yaml` and edit it there (or pass `--roster <path>`).

```sh
# Route to the free local backend directly — works out of the box once a local server is running:
.venv/bin/tanglebrain --local "Write a haiku about local inference."

# Show the cost-avoided rollup for every task this machine has routed:
.venv/bin/tanglebrain --stats
```

The default `tanglebrain "…"` (no `--local`) uses the **orchestrator router**. Since the packaged
roster ships with no active orchestrators, that path needs at least one opt-in backend enabled first
— see below. Until then, use `--local` for the local backend.

### Orchestrator routing (opt-in)

Enable one or more orchestrator backends by uncommenting an entry in your roster (subscription /
authenticated-CLI examples are provided, commented out, in the shipped roster) and reading
[`DISCLAIMER.md`](https://github.com/Jason-Vaughan/TangleBrain/blob/main/DISCLAIMER.md) first. With at least one orchestrator active:

```sh
# Default: route through an orchestrator. Rotates across the configured orchestrators and fails over
# on error; an orchestrator can offload sub-tasks to a configured backend (see "Delegate (MCP)"):
.venv/bin/tanglebrain "Refactor this module and add tests."
.venv/bin/tanglebrain --task code "Refactor this function for clarity."   # task-fit hint

# Force a specific roster entry (explicit override, bypasses the router):
.venv/bin/tanglebrain --model my-backend "Summarize this long document."

# Opt into the local classifier gate for this run (trivial → local backend, else router):
.venv/bin/tanglebrain --gate "What's the capital of France?"
```

An orchestrator is any roster entry flagged `can_orchestrate: true`. The router prefers an
orchestrator whose `good_at` matches the `--task` hint, rotates across the eligible set for
resilience, and on an error fails over to the next; if all fail it reports each failure.

### Classifier gate (optional, off by default)

By default every (non-`--local`) request goes through the router. You can put a **cheap local
classifier in front**: it rates each request's complexity on the local backend and sends **trivial**
work straight to the local backend, while **frontier** work falls through to the router. Enable it
persistently with `classifier_gate_enabled: true` in
[`tanglebrain/config/settings.yaml`](https://github.com/Jason-Vaughan/TangleBrain/blob/main/tanglebrain/config/settings.yaml), or per run with `--gate` /
`--no-gate`. It is **off by default** and **fails safe** — any classifier error or ambiguity routes
to frontier, so a hard task is never trapped on the local tier. (Fail-safe covers the
*classification*; a trivial-classified task that then fails to execute on local surfaces that error,
the same as `--local` — it doesn't silently re-route.) Gated runs show up as `gate-local` in
`--stats`. If the gate ever seems to route *everything* to frontier, the classify call is likely
truncating — raise its token budget.

### Cost avoided (measurement)

Every routed task is logged as one JSON line in an append-only usage log
(`~/.local/share/tanglebrain/usage.jsonl`, or under `XDG_DATA_HOME` /
`TANGLEBRAIN_STATE_DIR`): path, tier, model,
estimated tokens, and the **cloud-equivalent cost it avoided** — what the work would have cost on a
paid frontier API.

`tanglebrain --stats` reports a **lifetime** figure for **this machine**, summed from two files:
`totals.json` beside the log holds permanent aggregates, and the log holds the recent rows.
Compaction folds the oldest rows into the totals and then drops them, so the log stays a bounded
window without the lifetime figure shrinking as it shrinks. It runs on a size cap (5 MiB, roughly
15,000 records) — no maintenance, and nothing to schedule. Delete either file and the figure falls
back to whatever the other one holds — a smaller number, never an error. When the store cannot do
its job at all — a log that is not writable, or a `totals.json` that is present and unreadable —
`--stats` prints a `⚠ measurement:` line beside the figure, so a short number is never presented as
a confident one; what it checks, and the limits of that check, are in
[`docs/design/observability.md`](docs/design/observability.md) § Store health.

**Lifetime, not fleet-wide.** Each machine keeps its own log and totals, and nothing merges them —
merging is a decided non-goal rather than a missing feature, because a combined figure would need
stable machine identity, cross-host de-duplication and a conflict rule for compaction running
independently on each. A second machine starting at zero is the design working. If you do want a
combined view, the format is one JSON object per line so the logs concatenate. Read the result
under a throwaway state root rather than writing it back over a live log:

```sh
mkdir -p /tmp/merged
cat machine-a/usage.jsonl machine-b/usage.jsonl > /tmp/merged/usage.jsonl
TANGLEBRAIN_STATE_DIR=/tmp/merged .venv/bin/tanglebrain --stats
```

**Use `TANGLEBRAIN_STATE_DIR` specifically, not `XDG_DATA_HOME`.** Every entry point migrates a
pre-0.21 cache-tier state root forward before it reads anything, `--stats` included.
`TANGLEBRAIN_STATE_DIR` is the one override the migration reads too, so it resolves source and
destination to the same directory and copies nothing; point `XDG_DATA_HOME` at a scratch root
instead and the migration copies `~/.cache/tanglebrain` into it, so the "merged" view silently
carries a third machine's history. See
[`docs/design/operations.md`](docs/design/operations.md) for what that view does and does not cover.

Tokens are *estimated* with a uniform `chars/4` heuristic over the visible prompt + response — the
authenticated CLIs expose no usable token counts, so one consistent (if approximate) methodology is
applied to every tier. The reference frontier price lives in
[`tanglebrain/config/pricing.yaml`](https://github.com/Jason-Vaughan/TangleBrain/blob/main/tanglebrain/config/pricing.yaml) — tune it to whatever frontier
model you want to compare against. A `placeholder` flag makes the rollup render a PLACEHOLDER caveat
when the rates are rough. Logging is best-effort and never affects the returned answer.

**What the log never contains: your prompts, and the model's replies.** Each task's text is run
through the `chars/4` estimate and then discarded — only the derived counts and the routing metadata
are written. That is what makes the log safe to keep forever and safe to render in a browser. It is
a property of the shape of the code rather than a filter you have to trust: there is no redaction
step because nothing that would need redacting ever reaches the writer.

**The exception, stated plainly: backend error messages.** When a backend fails, the diagnostic
explaining why is persisted next to the failed attempt, because a router that hides why it fell back
is not debuggable. Every one of those messages that could carry a model's reply now reports the
reply's *shape* — `52 chars of text`, `object with keys ['result', 'subtype']` — instead of quoting
it, and a test drives a real malformed response onto disk to prove nothing of it survives.

Two things are still kept as-is, deliberately. **Strings only a provider or a CLI produces** — an
HTTP error body, a stream's error envelope, a failed subprocess's stderr — stay readable, because
rendering `invalid api key` as `object with keys ['error']` would gut the diagnostic for the single
most common setup failure there is. Those are error metadata rather than model output, but an
upstream that echoes your request back inside one — a 400, a content-filter rejection — would put
that text in the log; that turns on what the provider returns, not on TangleBrain. And **the shape
summary itself has to guess once**: it names an object's keys when they look like schema, so a key
that is a single identifier-shaped token is reproduced rather than counted, and that one can come
from the model's own reply. Telling a schema field name from content is not decidable, so it is a
judgement by construction rather than something a later fix closes.
[`docs/design/security-model.md`](docs/design/security-model.md) enumerates both and is the
authoritative accounting.

**Editing the price never restates history.** Each task is priced when it runs and keeps that
figure, so tuning `pricing.yaml` cannot retroactively inflate what you have already saved. The
`Pricing ref:` line names the revision a figure was computed under; once your history spans an
edit it reports how many revisions it spans instead of asserting one.

### Knob panel (`tanglebrain-gui`)

A thin **localhost-only** web panel over the config — zero extra dependencies (stdlib `http.server`
+ a single vanilla HTML/CSS/JS page):

```sh
.venv/bin/tanglebrain-gui          # serves http://127.0.0.1:3250/  (Ctrl-C to stop)
.venv/bin/tanglebrain-gui --port 3260   # override the port if 3250 is busy
```

The panel has two views, switched from the sidebar and addressable by fragment. **Chat**
(`#/chat`, where it opens) lets you **run a prompt** through the router, showing which tier/model
served it. **Settings** (`#/settings`) holds the knobs: the cost-avoided rollup, the roster, and the
pricing reference. The **pricing card is
editable** — change the rates / reference label / placeholder flag and Save; it writes the tracked
`tanglebrain/config/pricing.yaml` (strict validation, atomic write, a backup to the state dir, and
the methodology header preserved), so the edit is git-visible for you to commit. The **roster is
editable for a focused set of per-entry fields** — `enabled`, `can_orchestrate`, `budget_usd_month`,
and `good_at` (each row has its own Save). Edits are surgical and **comment-preserving**: only the
targeted value on the targeted line changes, so the curated inline comments and the nested `invoke`
block survive byte-for-byte (same validate → backup → atomic-write safety as pricing; the candidate
is re-parsed before any write). Adding/removing entries and editing the `invoke` block are still
hand-edits. The panel binds `127.0.0.1` only: running a prompt spends real backend quota and it reads
the roster, so it is never network-exposed. The roster view shows each entry's `key_ref` as the
reference string only — secrets are never resolved or sent to the browser.

### Server mode (`tanglebrain-serve`) — the router as an OpenAI-compatible endpoint

`tanglebrain-serve` exposes the same routing path the CLI uses as a local
**OpenAI-compatible endpoint**, so any OpenAI-compat consumer (an agent framework, an engine
config, a plain `openai` client) can point its `base_url` at TangleBrain and pick a *routing
strategy* instead of a model. Zero extra dependencies (stdlib `http.server`):

```sh
.venv/bin/tanglebrain-serve             # serves http://127.0.0.1:3251/v1  (Ctrl-C to stop)
.venv/bin/tanglebrain-serve --port 3261 # override the port if 3251 is busy

curl -s http://127.0.0.1:3251/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "Refactor this module."}]}'
```

The `model` param is a **routing directive**:

| `model` | Behavior |
|---|---|
| `auto` (or absent) | The full router — identical to a bare `tanglebrain "…"` run (classifier gate honored per settings). |
| a roster entry id | Explicit pin, parity with `--model <id>`. |
| anything else | A clear `model_not_found` error — never a silent fallback. |

`GET /v1/models` lists `auto` plus every roster id. Chat `messages` arrays are flattened to a
role-tagged transcript for the serving backend; text content parts are concatenated, and non-text
parts (images) are rejected loudly rather than dropped. `max_tokens` is honored; sampling knobs
(`temperature`, `top_p`, …) and tool definitions are accepted and ignored — the serving backend
controls its own generation, and orchestrator CLIs bring their own tools. The response's `model`
field reports **which backend actually served**; the requested directive and routing detail ride
in a `tanglebrain` extension field, and `usage` carries the same `chars/4` estimate the
measurement log uses (served requests are metered exactly like CLI runs).

Served requests are attributed in the usage log: each record carries `origin: "serve"` (CLI runs
tag `cli`, panel runs `gui`), and `tanglebrain --stats` shows the per-origin split. A caller can
additionally send an optional `X-TangleBrain-Parent-Task` header carrying its own task/session
identity — trimmed, capped at 128 chars, recorded onto the usage record as `parent_task_id` for
cross-system attribution, and never routed on. The reverse linkage already exists: the response's
completion id is `chatcmpl-<task_id>`, the same task id the usage record carries.

Caveats, by design:

- **Streaming is real where the backend can stream.** `stream: true` delivers incremental
  `chat.completion.chunk` deltas from backends that stream (a pinned `openai-compat`/`api`
  entry, or the classifier-gate's local path). Backends that can't — subprocess CLIs, and the
  full-router `auto` path they serve — still work but deliver the completed response as a
  single chunk, which can take minutes when an orchestrator CLI serves the request; set
  generous client read timeouts for those. A stream that dies mid-way ends with an in-stream
  `{"error": ...}` event and no `[DONE]` terminator, never a fake `finish_reason: stop`.
- **Localhost-only, keyless.** The endpoint binds `127.0.0.1` (not configurable) and **ignores
  the `Authorization` header** — local callers need no key, and a client that insists on sending
  a dummy bearer works as-is. It is deliberately never network-exposed: a request spends real
  backend quota, and real money if the paid-API gates are on. Those gates are unchanged — server
  mode adds no paid path that the CLI doesn't have. POSTs must send
  `Content-Type: application/json` (every OpenAI client does; this also keeps no-preflight
  cross-origin browser requests from ever reaching routing).

### Delegate (MCP) — let an orchestrator offload sub-tasks to a configured backend

`tanglebrain-delegate` is an MCP server that lets an orchestrator offload bulk sub-tasks instead of
running them itself, then review the results — a decompose → delegate → review loop that is emergent
from the orchestrator simply having the tool (no graph engine required). It reuses the same roster +
adapters as the CLI above, so endpoints and keys live in one place. It exposes four tools:

- **`delegate_local(prompt, max_tokens?)`** — route a sub-task to the free local tier (the $0
  default).
- **`delegate(prompt, target?, task?, max_tokens?)`** — route a sub-task to a *configured* backend,
  two ways (precedence: `target` > `task` > local):
  - **`target`** — an explicit roster id flagged `can_delegate: true`. The orchestrator names the
    exact backend.
  - **`task`** — a capability tag (a `good_at` value, e.g. `code`). TangleBrain picks the **cheapest
    `can_delegate` backend** good_at it (`local` before `sub`); the orchestrator just says *what kind
    of work it is* and doesn't need to know ids. **Paid `api` backends are never auto-selected by
    `task`** (reach one only by naming it as `target`). If nothing fits, the tool hands the sub-task
    **back to the orchestrator to do itself** — not an error, just a signal that it's the most capable
    backend available.

  A target is invoked as a leaf (it never gets its own delegate tool — no recursion); `api` targets
  named explicitly still obey the billing gate, so a paid target raises rather than spending while
  billing is off.
- **`delegate_many(tasks, max_concurrency?)`** — fan **several sub-tasks out concurrently** in one
  call and collect them, instead of delegating one at a time. Each item is `{prompt, target?, task?,
  max_tokens?}` (same routing as `delegate`), so a batch can mix backends. Returns a JSON array, one
  entry per task **in input order**, each `{index, status}` — `ok` (+`text`), `no_fit` (+`message`),
  or `error` (+`error`); a failing sub-task never sinks the others. Concurrency is bounded
  automatically from the host (`os.cpu_count()`), overridable by the operator
  (`delegate_max_concurrency` in `settings.yaml` — pin it to your backend's real parallelism, e.g.
  `OLLAMA_NUM_PARALLEL`) and lowerable per call. Dispatch + collect only — the orchestrator
  synthesises the results.
- **`delegate_targets()`** — list the configured targets (`id`, `tier`, `good_at`, `cost`, `kind`)
  so the orchestrator can decide based on what's available. The `delegate` tool's description also
  enumerates them (built at server startup; the tool reflects the live roster).

Make a backend a delegate target by flagging its roster entry `can_delegate: true` (mirrors
`can_orchestrate`). The shipped example flags the local tier, so the menu is non-empty out of the
box. **Delegated sub-calls are now metered**: each is logged as a `kind: delegate` usage record, and
`tanglebrain --stats` (and the knob panel) show a "Delegated sub-tasks" breakdown by backend (count,
est tokens, informational cloud-equiv). These are kept **out of** the "spend avoided" headline so a
sub-call's saving is never double-counted against its parent task. Any non-local target is opt-in and
your responsibility under that provider's terms — see [DISCLAIMER.md](https://github.com/Jason-Vaughan/TangleBrain/blob/main/DISCLAIMER.md).

**Synthesising fan-out results.** The full pattern is decompose → fan out (`delegate_many`) →
**reduce** → answer. TangleBrain ships the dispatch primitives but deliberately does *not* own the
reduce step: the orchestrator gets the results array back and combines it itself, because it holds
the original task context that makes for good synthesis — something a fresh reduce backend lacks. If
the reduction is instead **mechanical and large** (concatenating generated files, merging many
summaries into one list — where the original intent doesn't matter), offload that stitch too with a
normal `delegate(prompt="Combine these results: …", task="summarization")` call, keeping the heavy
formatting off your frontier budget. No separate "reduce" tool is needed — the existing `delegate`
covers it.

It needs the optional `mcp` dependency:

```sh
pip install -e ".[delegate]"        # or: make venv (installs the extra)
tanglebrain-delegate                # serve over stdio (for a manual smoke test)
```

Register it with an orchestrator CLI (exact flags vary by CLI version — check `<cli> mcp --help`):

```sh
# Claude Code:
claude mcp add tanglebrain-delegate -- tanglebrain-delegate
# Codex: add a stdio MCP server entry pointing at `tanglebrain-delegate` in its MCP config.
# Antigravity CLI (`agy`, the gemini CLI's successor): no per-invocation MCP flags as of
# 1.0.10 — antigravity orchestrates without the delegate for now (TangleBrain #81).
```

Claude Code users can instead install it as a **plugin** — this repo is its own plugin marketplace
(see [`plugins/tanglebrain-delegate/`](https://github.com/Jason-Vaughan/TangleBrain/tree/main/plugins/tanglebrain-delegate)):

```
/plugin marketplace add Jason-Vaughan/TangleBrain
/plugin install tanglebrain-delegate@tanglebrain
```

The plugin registers the server declaratively — it wires the `tanglebrain-delegate` command, it
doesn't vendor it — so the console script must be on `PATH`: `pip install "tanglebrain[delegate]"`
from PyPI, or `pip install -e ".[delegate]"` from a clone as above.

To point the server at a non-default roster, set `TANGLEBRAIN_ROSTER=/path/to/roster.yaml` in its
environment.

### Paid-API tier (opt-in, off by default)

Paid API is the genuine last resort — it costs real money, so it is **disabled by default** and
gated by a single explicit switch. A `tier: api` roster entry parses and is inspectable at all
times, but it is **never routable** until you turn it on. See [`DISCLAIMER.md`](https://github.com/Jason-Vaughan/TangleBrain/blob/main/DISCLAIMER.md) for
the bring-your-own-key posture.

The durable rule: *no paid billing without the explicit toggle.* Two independent gates must both be
on for a paid entry to build:

1. **Global gate** — `api_billing_enabled: true` in `tanglebrain/config/settings.yaml` (ships
   `false`).
2. **Per-entry switch** — `enabled: true` on the roster entry (a per-key kill-switch).

Custody is **by reference, never embedding**: TangleBrain never holds a raw key in config —
`key_ref` points at an env var (`env:OPENAI_API_KEY`) or a `0600` key file
(`file:~/.config/tanglebrain/keys/paid.key`). Prefer fronting paid APIs through a budget-capped
gateway or a scoped key so spend is bounded **at the source**. A paid entry also records
`budget_usd_month` for visibility — TangleBrain does **not** enforce spend; cap it at your
gateway/provider. A commented example entry is at the bottom of `tanglebrain/config/roster.yaml`.

Once both gates are on, a paid entry runs either when selected explicitly (`--model <id>`) or as the
router's **genuine last resort** — the default `tanglebrain "…"` router falls through to an enabled
`api` entry only after *every* orchestrator has failed/exhausted. It tries paid entries in roster
order and never paid-routes a roster that has no orchestrators to exhaust first.

> **Live status:** the paid tier is **hermetically tested but never run against a real paid
> endpoint** — by design (TangleBrain is deliberately bring-your-own-key; we don't mint billable keys
> just to test). The hooks are in place and the routing/gating/visibility are proven; the live
> `router → ApiAdapter → key → provider` round-trip is unverified until an operator wires a real key.
> See [#23](https://github.com/Jason-Vaughan/TangleBrain/issues/23). Treat it as hermetically correct
> but live-unproven, and file a fix if a live provider needs one.

#### Runbook — enabling a paid key

1. **Get a key for any OpenAI-compatible endpoint you control** — a provider directly, OpenRouter, or
   a self-hosted gateway (e.g. LiteLLM). Prefer a **budget-capped / scoped** key so spend is bounded
   at the source; TangleBrain doesn't enforce spend itself.
2. **Store it outside the repo.** Reference an env var (`key_ref: env:OPENAI_API_KEY`) or a `0600`
   file (`*.key` is gitignored):
   ```sh
   install -m 600 /dev/stdin ~/.config/tanglebrain/keys/paid.key <<< 'sk-your-key'
   ```
3. **Add the roster entry** (uncomment/adapt the example at the bottom of your roster): `tier: api`,
   `invoke.kind: api`, `base_url` = your endpoint, `model` = the model id it exposes,
   `key_ref` = the env/file reference above, `enabled: true`, and `budget_usd_month: 25`
   (display-only — match what you capped at the source).
4. **Flip the global gate**: set `api_billing_enabled: true` in `tanglebrain/config/settings.yaml`.
5. **Verify** in the knob panel (`tanglebrain-gui`): open **Settings** in the sidebar — the panel
   opens on Chat — and the roster card there shows a **Paid-API billing: ON** banner and the entry's
   `budget: $25.00/mo` note; or run `tanglebrain --model <id> "…"` for an explicit paid call. To pause spend without editing keys, set the entry's `enabled: false` (a
   per-key kill-switch) or flip the global gate back to `false`.

## Develop

```sh
make help          # list targets
make lint          # ruff (lint) + mypy (type-check)
make test          # lint + type-check + the unit test suite (hermetic; HTTP is mocked)
make test-live     # opt-in: hit the real local endpoint your roster points at, end-to-end
```

There is deliberately no formatter — see [CONTRIBUTING.md](CONTRIBUTING.md) for what that means
when you send a patch, and `docs/design/nonfunctional-requirements.md` for why.

## Design documents

The reasoning behind the system — what each surface promises, what data survives a crash, what's
protected and what's accepted risk — is published in
[`docs/design/`](https://github.com/Jason-Vaughan/TangleBrain/blob/main/docs/design/README.md).

These are deliberately candid: each document names its own gaps, and every gap named there links to
a tracking issue. If you're evaluating whether to depend on TangleBrain, or looking for somewhere to
start contributing, that directory is the honest picture.

## Contributing

Contributions are welcome — see [`CONTRIBUTING.md`](https://github.com/Jason-Vaughan/TangleBrain/blob/main/CONTRIBUTING.md) for dev setup, branch/PR
conventions, and good first contributions (adding a backend is usually a config edit, not a code
change). All participation is governed by our [`CODE_OF_CONDUCT.md`](https://github.com/Jason-Vaughan/TangleBrain/blob/main/CODE_OF_CONDUCT.md), and the
opt-in / bring-your-own-key posture is in [`DISCLAIMER.md`](https://github.com/Jason-Vaughan/TangleBrain/blob/main/DISCLAIMER.md).

## License

[MIT](https://github.com/Jason-Vaughan/TangleBrain/blob/main/LICENSE).
