tanglebrain 0.16.0__py3-none-any.whl

tanglebrain/classifier.py

@@ -0,0 +1,99 @@
+"""Cheap local classifier gate — OFF by default.
+
+The default routing strategy is frontier-first with orchestrator rotation. An optional escape valve:
+put a **cheap local classifier in front** that does one narrow job — decide whether a request is
+*trivial* (the free local backend can fully handle it) or *needs-frontier* (route to the
+orchestrator). Trivial requests then skip the orchestrators entirely.
+
+Two deliberate design rules:
+
+- **Narrow classification, not self-judgement.** The classifier rates *task complexity*, it does not
+  ask the local model "can YOU do this?" — that framing is unreliable.
+- **Fail safe toward the capable path.** Any ambiguity, parse miss, or classifier error resolves to
+  ``frontier``. The gate must never trap a hard task on the local tier because the classifier was
+  unsure or broke — at worst it falls back to normal frontier-first routing.
+
+It is inert unless explicitly enabled (``classifier_gate_enabled`` in settings, or ``--gate`` on the
+CLI).
+"""
+from __future__ import annotations
+
+import re
+from typing import Callable
+
+from tanglebrain.adapters import OpenAICompatAdapter
+from tanglebrain.adapters.base import Adapter
+from tanglebrain.roster import Roster, load_roster
+from tanglebrain.selector import select_local
+
+TRIVIAL = "trivial"
+FRONTIER = "frontier"
+
+# A local reasoning model spends part of its budget on internal reasoning, so give the classify call
+# enough headroom to finish reasoning AND emit the verdict; a truncated (null) response just fails
+# safe to FRONTIER. Kept modest because this runs in front of every gated request.
+CLASSIFY_MAX_TOKENS = 1024
+
+_INSTRUCTIONS = (
+    "You are a routing classifier. Decide how complex the USER REQUEST below is, so a dispatcher "
+    "can send simple work to a small local model and hard work to a frontier model.\n\n"
+    "Classify by the TASK's intrinsic complexity (not by who should do it):\n"
+    "- TRIVIAL: short, well-specified, single-step work — a factual lookup, a small/simple code "
+    "snippet, a quick rewrite or format, a direct question with a known answer.\n"
+    "- FRONTIER: anything needing multi-step reasoning, decomposition, architecture or design, "
+    "debugging across files, careful trade-offs, or ambiguous/open-ended judgement.\n\n"
+    "Decide quickly; do not overthink and do not attempt the task. When unsure, answer FRONTIER."
+)
+
+
+def _build_prompt(user_request: str) -> str:
+    """Fold the classify instructions and the request into one user message (the adapter sends one)."""
+    return (
+        f"{_INSTRUCTIONS}\n\n--- USER REQUEST ---\n{user_request}\n--- END REQUEST ---\n\n"
+        "Answer with exactly one word: TRIVIAL or FRONTIER."
+    )
+
+
+def _parse_verdict(text: str) -> str:
+    """Map a classifier response to ``TRIVIAL`` or ``FRONTIER``, defaulting to ``FRONTIER``.
+
+    We instruct the model to answer with exactly one word, so the verdict is ``TRIVIAL`` **only** when
+    the response's first word token is exactly ``trivial`` and ``frontier`` appears nowhere. Anything
+    else — ``frontier``, a both-words answer, prose, a *negation* like "not trivial", junk, empty — is
+    ``FRONTIER`` (the safe default). The first-token rule is deliberately strict: free-form prose can't
+    leak a spurious ``TRIVIAL`` and strand a hard task on local.
+    """
+    words = re.findall(r"[a-z]+", (text or "").lower())
+    if "frontier" in words:
+        return FRONTIER
+    return TRIVIAL if words[:1] == ["trivial"] else FRONTIER
+
+
+def classify(
+    prompt: str,
+    roster: Roster | None = None,
+    adapter_factory: Callable[..., Adapter] = OpenAICompatAdapter.from_entry,
+    max_tokens: int = CLASSIFY_MAX_TOKENS,
+) -> str:
+    """Classify ``prompt`` as :data:`TRIVIAL` or :data:`FRONTIER` using free local gpt-oss.
+
+    Never raises and never blocks routing: any failure (no local entry, transport error, truncated
+    or unparsable response) resolves to :data:`FRONTIER`, so a broken classifier degrades to today's
+    normal frontier-first routing rather than trapping a task on the local tier.
+
+    Args:
+        prompt: The user request to classify.
+        roster: The loaded roster (defaults to the packaged roster).
+        adapter_factory: Builds the local adapter from the selected entry (injectable for tests).
+        max_tokens: Budget for the classify call (gpt-oss needs reasoning headroom; see the constant).
+
+    Returns:
+        :data:`TRIVIAL` or :data:`FRONTIER`.
+    """
+    try:
+        entry = select_local(roster if roster is not None else load_roster())
+        adapter = adapter_factory(entry)
+        text = adapter.run(_build_prompt(prompt), {"max_tokens": max_tokens})
+    except Exception:  # noqa: BLE001 — deliberately total: a broken classifier must fail safe, never block
+        return FRONTIER
+    return _parse_verdict(text)

tanglebrain/cli.py

@@ -0,0 +1,251 @@
+"""TangleBrain CLI — route one request and print the response.
+
+Thin wiring over :func:`run_once`; the routing logic lives in the router/selector/adapters. The
+path is chosen by flag precedence ``--model`` > ``--local`` > the frontier-first router (the
+default): the router selects + rotates an orchestrator, fails over on errors, and gives it the
+local-delegate tool so it offloads sub-tasks to the free local backend.
+
+Usage::
+
+    tanglebrain "Refactor this module and add tests."        # default: frontier-first router
+    tanglebrain --task code "..."                            # task-fit hint for the router
+    tanglebrain --local "Write a haiku about local inference."   # force the free local tier
+    tanglebrain --model gemini "Summarize this long document."   # pin a specific roster entry
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+import uuid
+
+from tanglebrain import __version__
+from tanglebrain.adapters import AdapterError
+from tanglebrain.classifier import TRIVIAL, classify
+from tanglebrain.measurement import (
+    format_rollup,
+    load_pricing,
+    read_records,
+    record_task,
+    rollup,
+)
+from tanglebrain.roster import RosterError, load_roster
+from tanglebrain.router import Router, RouterError
+from tanglebrain.selector import SelectionError, build_adapter, select_by_id, select_local
+from tanglebrain.settings import load_settings
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser for the ``tanglebrain`` command.
+
+    Returns:
+        The configured :class:`argparse.ArgumentParser`.
+    """
+    parser = argparse.ArgumentParser(
+        prog="tanglebrain",
+        description=(
+            "Route one request to the cheapest capable tier (frontier-first by default), or "
+            "print the 'spend avoided' rollup with --stats."
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+        help="Print the TangleBrain version and exit.",
+    )
+    parser.add_argument(
+        "prompt",
+        nargs="?",
+        default=None,
+        help="The prompt to route. Optional only when --stats is given.",
+    )
+    parser.add_argument(
+        "--roster",
+        default=None,
+        help="Path to a roster YAML (defaults to the packaged tanglebrain/config/roster.yaml).",
+    )
+    parser.add_argument(
+        "--model",
+        default=None,
+        help=(
+            "Route to a specific roster entry by id (e.g. 'claude'). Without it, the default "
+            "local-first selection is used. This is an explicit override of routing."
+        ),
+    )
+    parser.add_argument(
+        "--local",
+        action="store_true",
+        help=(
+            "Force the free local tier (gpt-oss) instead of the default frontier-first router. "
+            "Use for a quick, $0, no-orchestration answer."
+        ),
+    )
+    parser.add_argument(
+        "--route",
+        action="store_true",
+        help="Deprecated/no-op: the frontier-first router is now the default. Kept for back-compat.",
+    )
+    parser.add_argument(
+        "--task",
+        default=None,
+        help="Task-fit hint for the router (a good_at tag, e.g. 'code', 'reasoning', 'long-context').",
+    )
+    gate_group = parser.add_mutually_exclusive_group()
+    gate_group.add_argument(
+        "--gate",
+        dest="gate",
+        action="store_true",
+        default=None,
+        help="Force the local classifier gate ON for this run: a cheap local classify sends "
+        "trivial requests straight to the free local backend, and only frontier ones to an "
+        "orchestrator.",
+    )
+    gate_group.add_argument(
+        "--no-gate",
+        dest="gate",
+        action="store_false",
+        help="Force the classifier gate OFF (always frontier-first router), ignoring the setting.",
+    )
+    parser.add_argument(
+        "--max-tokens",
+        type=int,
+        default=None,
+        help="Override the completion token cap (defaults to the adapter's 2048).",
+    )
+    parser.add_argument(
+        "--stats",
+        action="store_true",
+        help=(
+            "Print the 'spend avoided' rollup (cloud-equivalent cost of every routed task so far) "
+            "and exit. No prompt needed."
+        ),
+    )
+    return parser
+
+
+def _served(path: str, entry) -> dict | None:
+    """Build the ``{path, tier, model}`` served-summary for a routed task, or ``None``."""
+    if entry is None:
+        return None
+    return {"path": path, "tier": entry.tier, "model": entry.id}
+
+
+def run_once(
+    prompt: str,
+    roster_path: str | None = None,
+    max_tokens: int | None = None,
+    model: str | None = None,
+    local: bool = False,
+    task: str | None = None,
+    return_served: bool = False,
+    gate: bool | None = None,
+):
+    """Route a single prompt to a roster tier and return the response text.
+
+    Paths, in precedence order:
+
+    - ``model`` set → select that named entry explicitly (an override, not a routing decision).
+    - ``local`` true → the free local tier directly, no orchestration.
+    - otherwise → the default routing path. With the **classifier gate** off (the default), this
+      is **the frontier-first** :class:`~tanglebrain.router.Router`: task-fit orchestrator selection +
+      rotation + failover across the orchestrators, each given the local-delegate tool. With the gate
+      on, a cheap local classify runs first: a *trivial* request is handled directly on the free local
+      backend (path ``gate-local``, skipping the orchestrators), and everything else falls through to
+      the router.
+
+    Args:
+        prompt: The prompt to route.
+        roster_path: Optional roster YAML path (defaults to the packaged roster).
+        max_tokens: Optional completion token cap (honoured by the openai-compat adapter; the
+            CLI adapter ignores it, as each CLI controls its own limits).
+        model: Optional roster entry id to route to explicitly.
+        local: Force the free local tier instead of the frontier-first router.
+        task: Optional task-fit hint for the router (a ``good_at`` tag).
+        return_served: When ``True``, return ``(text, served)`` where ``served`` is
+            ``{path, tier, model}`` for the entry that served the task (or ``None`` if unknown).
+            The GUI uses this so it needn't re-read the usage log. Default ``False`` returns the
+            plain text string, so existing callers (``main``) are unchanged.
+        gate: Override for the classifier gate on the default path. ``None`` (default) uses the
+            ``classifier_gate_enabled`` setting; ``True``/``False`` force the gate on/off for this
+            call. Ignored when ``model`` or ``local`` is set.
+
+    Returns:
+        The response text (``str``), or ``(text, served)`` when ``return_served`` is ``True``.
+
+    Raises:
+        RosterError: If the roster cannot be loaded.
+        SelectionError: If ``model``/``local`` is used and no suitable entry is available.
+        RouterError: If the router runs and no orchestrator can serve the request.
+        AdapterError: If the adapter cannot produce text.
+    """
+    roster = load_roster(roster_path)
+    # Mint a task id for this routed task. It is recorded on the task and threaded through opts so
+    # the orchestrator-CLI adapter can propagate it to delegated sub-calls (see CliAdapter.run /
+    # PARENT_TASK_ID_ENV), linking the delegation tree back to this task. Cheap and side-effect-free
+    # to mint on every path; only the router path (orchestrators with the delegate tool) acts on it.
+    task_id = uuid.uuid4().hex
+    opts: dict = {"task_id": task_id}
+    if max_tokens is not None:
+        opts["max_tokens"] = max_tokens
+
+    if model is not None:
+        path, entry = "model", select_by_id(roster, model)
+        text = build_adapter(entry).run(prompt, opts)
+    elif local:
+        path, entry = "local", select_local(roster)
+        text = build_adapter(entry).run(prompt, opts)
+    else:
+        gate_on = load_settings().classifier_gate_enabled if gate is None else gate
+        if gate_on and classify(prompt, roster=roster) == TRIVIAL:
+            # classifier gate: a trivial request skips the orchestrators and is handled directly on
+            # the free local backend. Frontier (or any classifier failure) falls through to the router.
+            path, entry = "gate-local", select_local(roster)
+            text = build_adapter(entry).run(prompt, opts)
+        else:
+            path = "router"
+            router = Router(roster)
+            text = router.route(prompt, task=task, opts=opts)
+            entry = router.last_served
+
+    record_task(path=path, entry=entry, prompt=prompt, response=text, task_id=task_id)
+    return (text, _served(path, entry)) if return_served else text
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Console entry point.
+
+    Args:
+        argv: Optional argument list (defaults to ``sys.argv[1:]``).
+
+    Returns:
+        Process exit code: ``0`` on success, ``1`` on a known TangleBrain error.
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.stats:
+        print(format_rollup(rollup(read_records()), load_pricing()))
+        return 0
+
+    if args.prompt is None:
+        parser.error("prompt is required (unless --stats is given)")
+
+    try:
+        text = run_once(
+            args.prompt,
+            roster_path=args.roster,
+            max_tokens=args.max_tokens,
+            model=args.model,
+            local=args.local,
+            task=args.task,
+            gate=args.gate,
+        )
+    except (RosterError, SelectionError, RouterError, AdapterError) as exc:
+        print(f"tanglebrain: {exc}", file=sys.stderr)
+        return 1
+    print(text)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tanglebrain/config/pricing.yaml

@@ -0,0 +1,14 @@
+# Cloud-equivalent reference pricing for the "spend avoided" rollup.
+#
+# Methodology: for each routed task, estimate what it WOULD have cost on a paid frontier API,
+# valued at a reference frontier price — here Claude Sonnet, $3/MTok input, $15/MTok output. The
+# rollup multiplies estimated tokens (a chars/4 heuristic over the visible prompt + response) by
+# these rates. Values are US dollars per 1,000,000 tokens. Tune them to whatever frontier model you
+# want to compare against.
+#
+# Set `placeholder: true` if your rates are rough/illustrative — the `tanglebrain --stats` rollup
+# then flags every figure as PLACEHOLDER so no number is mistaken for a precise cost.
+placeholder: false
+reference_model: "Claude Sonnet ($3/$15 per MTok)"
+input_per_mtok: 3.00
+output_per_mtok: 15.00

tanglebrain/config/roster.yaml

@@ -0,0 +1,129 @@
+# 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 / Gemini). 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: gemini
+#   tier: sub
+#   invoke:
+#     kind: cli
+#     # -p requires the prompt as its value, so {prompt} marks the injection point.
+#     cmd: ["gemini", "-p", "{prompt}", "--output-format", "json"]
+#     parse: gemini-json
+#     # gemini has no per-invocation MCP-server config — it needs a one-time
+#     #   gemini mcp add tanglebrain-delegate -- <python> -m tanglebrain.mcp_server
+#     # (see README); these per-invocation flags then allow + auto-approve the tool.
+#     delegate_args: ["--allowed-mcp-server-names", "tanglebrain-delegate", "--approval-mode", "yolo"]
+#   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

tanglebrain/config/settings.yaml

@@ -0,0 +1,39 @@
+# TangleBrain global settings — knobs that are NOT per roster entry.
+#
+# The roster (roster.yaml) is a list of routable backends; per-entry policy lives there. The few
+# truly global switches live here.
+#
+# api_billing_enabled — THE PAID-API BILLING GATE. This is the durable safety contract: paid
+# billing is OFF unless this is explicitly `true`.
+#
+#   false (default) → every `tier: api` roster entry still parses and is inspectable, but is
+#                     NEVER routable — the adapter factory refuses to build it. Inert.
+#   true            → enabled `tier: api` entries become routable (still last-resort), each
+#                     fronted through a budget-scoped key (key_ref) on an OpenAI-compatible gateway.
+#
+# The durable rule: *no paid billing without this explicit toggle.* Keep it false unless you mean it.
+
+api_billing_enabled: false
+
+# classifier_gate_enabled — the LOCAL CLASSIFIER GATE (default false = normal frontier-first).
+#
+#   false (default) → every request goes through the frontier-first router (orchestrator rotation).
+#   true            → a cheap local classify runs FIRST: trivial requests are handled directly by
+#                     the free local backend and never reach an orchestrator; only frontier requests
+#                     do. Per CLI run, `--gate` / `--no-gate` overrides this.
+#
+# Classification fails safe to "frontier" — it never traps a hard task on local.
+
+classifier_gate_enabled: false
+
+# delegate_max_concurrency — cap on how many sub-tasks `delegate_many` fans out AT ONCE.
+#
+#   unset (default) → TangleBrain derives the cap from this machine (os.cpu_count()).
+#   <positive int>  → pin the cap. The TRUE limit is your backend's parallelism, which TangleBrain
+#                     can't portably detect — set this to match it (e.g. your local model server's
+#                     OLLAMA_NUM_PARALLEL, or your provider's safe concurrent-request budget).
+#
+# A per-call `max_concurrency` argument may LOWER this but never exceed it. Left unset below so the
+# derived default applies out of the box.
+#
+# delegate_max_concurrency: 4