roster.yaml

# TangleBrain roster — a GENERIC EXAMPLE list of routable models. Edit it to your own backends.
#
# This shipped file is just a starting point. Your REAL roster lives OUTSIDE the repo and is
# auto-discovered, so a `git pull` never clobbers it. Resolution order (first hit wins):
#   1. $TANGLEBRAIN_ROSTER                      (explicit path)
#   2. ~/.config/tanglebrain/roster.yaml        (your roster — recommended)
#   3. this packaged example                    (fallback)
# Copy this file to ~/.config/tanglebrain/roster.yaml and edit it there.
#
# Add / remove / reorganize entries freely — adding a model is a config edit, never a code change.
# Flag `can_orchestrate: true` to put an entry in the orchestrator rotation. Flag
# `can_delegate: true` to make an entry a delegate target an orchestrator can hand a sub-task to
# (via the `delegate` MCP tool), either by naming its id or by capability — `delegate(task: code)`
# picks the cheapest `can_delegate` entry whose `good_at` lists that tag (local before sub; paid
# `api` is never auto-selected). The free local model is always available as the default target.
#
# invoke.kind ∈ {openai-compat, cli, api}.  key_ref ∈ {file:PATH, env:NAME, none} — a
# credential *reference*, never a raw secret.
#
# For `cli` entries: a literal `{prompt}` token in `cmd` is replaced with the prompt; with no
# token the prompt is appended as the final argument. `parse` names the output parser
# (claude-json | gemini-json | plain). `scrub_env` strips env vars from the subprocess.
#
# The paid-API tier (kind: api) is gated behind `api_billing_enabled` (config/settings.yaml,
# default false) AND each entry's own `enabled` flag — it parses but stays inert until both are
# on. A commented example is at the bottom of this file.

# Free local tier — any OpenAI-compatible local server. This example points at Ollama on its
# default port; run `ollama pull llama3.2` (or any model) first, or swap in your own endpoint.
- id: local-ollama
  tier: local
  invoke:
    kind: openai-compat
    base_url: "http://localhost:11434/v1"
    model: "llama3.2"
    # Local Ollama needs no auth, so no key_ref. For a keyed endpoint, add e.g.
    # key_ref: "file:~/.config/tanglebrain/keys/local.key"  (a reference, never the raw key).
  cost: free
  good_at: [grunt, code, tools]
  can_delegate: true            # an orchestrator may target this backend by id via the delegate tool

# --- OPT-IN delegate target (non-local) — COMMENTED OUT so it stays inert. ---
# A delegate target is a backend an orchestrator can hand a *sub-task* to (not the whole request) —
# e.g. a cheaper sub or a better-fit model. Flag any entry `can_delegate: true` and it joins the
# menu the `delegate` tool advertises; the model picks a target by its `good_at` fit. A target is
# invoked as a leaf (it never gets its own delegate tool — no recursion). `api` targets still obey
# the billing gate; delegated sub-calls are metered separately (see `tanglebrain --stats`). This
# example is an openai-compat backend; uncomment + point it at one you hold.
#
# - id: cheap-remote
#   tier: sub
#   invoke:
#     kind: openai-compat
#     base_url: "https://your-openai-compatible-endpoint/v1"
#     model: "a-cheaper-model"
#     key_ref: "file:~/.config/tanglebrain/keys/cheap.key"   # a reference, never the raw key
#   cost: cheap
#   good_at: [grunt, summarization, extraction]
#   can_delegate: true

# --- OPT-IN subscription / authenticated-CLI tier — COMMENTED OUT so it stays inert. ---
# These entries drive authenticated CLIs you already have installed and logged in (Claude Code /
# Codex / Antigravity). They are OPT-IN: uncomment only the ones you use. Driving these CLIs is YOUR
# responsibility under each provider's terms of service — see DISCLAIMER.md. Once uncommented, an
# entry flagged `can_orchestrate: true` joins the orchestrator rotation (rotation + failover for
# resilience). Adapt the `cmd`/`parse`/`delegate_args` to your installed CLI's flags.
#
# - id: claude
#   tier: sub
#   invoke:
#     kind: cli
#     # --output-format json => one JSON object {"result": ..., "is_error": ...}; prompt appended.
#     cmd: ["claude", "-p", "--output-format", "json"]
#     parse: claude-json
#     scrub_env: ["ANTHROPIC_API_KEY"]   # use the CLI's own authenticated session, not an injected key
#     # Per-invocation delegate injection: {delegate_mcp_json} is substituted with the local-delegate
#     # MCP server config; the tool is mcp__tanglebrain-delegate__delegate_local.
#     delegate_args: ["--mcp-config", "{delegate_mcp_json}", "--allowedTools", "mcp__tanglebrain-delegate__delegate_local", "--strict-mcp-config"]
#   cost: subscription
#   good_at: [reasoning, decomposition, review]
#   can_orchestrate: true                 # joins the orchestrator rotation
#
# - id: codex
#   tier: sub
#   invoke:
#     kind: cli
#     # codex exec prints the answer to stdout (metadata to stderr); prompt appended.
#     cmd: ["codex", "exec"]
#     parse: plain
#     # Register the delegate via -c TOML overrides (codex has no per-invocation --mcp-config), plus
#     # the approval/sandbox bypass codex exec needs to auto-run a tool call headless.
#     delegate_args: ["-c", "mcp_servers.tanglebrain_delegate.command={delegate_mcp_command}", "-c", "mcp_servers.tanglebrain_delegate.args=[\"-m\",\"tanglebrain.mcp_server\"]", "--dangerously-bypass-approvals-and-sandbox"]
#   cost: subscription
#   good_at: [code, agentic-code]
#   can_orchestrate: true
#
# - id: antigravity
#   tier: sub
#   invoke:
#     kind: cli
#     # Antigravity CLI (`agy`) — Google's successor to the sunset `gemini` CLI (individuals,
#     # 2026-06-18). `-p/--print` runs one prompt non-interactively and prints the bare response
#     # to stdout, so parse is `plain`. Rides the same ~/.gemini OAuth as the old CLI.
#     cmd: ["agy", "-p", "{prompt}"]
#     parse: plain
#     # No delegate_args: agy (verified 1.0.10 and 1.0.16) exposes no per-invocation MCP-server
#     # flags, so this orchestrator answers directly instead of offloading to the local delegate
#     # (#81 tracks wiring delegation when agy grows per-call MCP config). No scrub_env either —
#     # unlike the old gemini CLI, agy reads no GEMINI_API_KEY/GOOGLE_API_KEY (verified against
#     # the binary), so there is no API-key path to divert billing through; OAuth is the only auth.
#   cost: subscription
#   good_at: [long-context, structured-json]
#   can_orchestrate: true

# --- Paid-API tier example (bring-your-own-key overflow) — COMMENTED OUT so it stays inert. ---
# Paid API is the genuine last resort. To enable: set api_billing_enabled: true in
# config/settings.yaml, then uncomment and point it at any OpenAI-compatible endpoint you hold a
# key for (OpenRouter, a self-hosted LiteLLM gateway, a provider directly, etc.). Prefer fronting
# it through a budget-capped gateway/virtual key. key_ref is a REFERENCE — never the raw key.
# budget_usd_month is recorded for visibility; enforce the hard cap at your gateway/provider.
#
# - id: paid-overflow
#   tier: api
#   invoke:
#     kind: api
#     base_url: "https://your-openai-compatible-endpoint/v1"  # e.g. OpenRouter or your gateway
#     model: "your-model"                                     # the model id that endpoint exposes
#     key_ref: "env:OPENAI_API_KEY"                           # or file:~/.config/tanglebrain/keys/paid.key
#   cost: paid                  # real $ — last resort only
#   good_at: [reasoning, hard]
#   enabled: true               # per-key kill-switch (false => never routable, even if billing on)
#   budget_usd_month: 25        # display-only in v1; LiteLLM enforces the hard cap on the key