tanglebrain 0.16.0__py3-none-any.whl

tanglebrain/router.py

@@ -0,0 +1,232 @@
+"""Frontier-first router — pluggable orchestrator selection + rotation + failover.
+
+The control plane: route a task to an orchestrator (a ``can_orchestrate`` backend), rotate the
+orchestrator role across the eligible set, and fail over to the next when one errors. Rotation and
+failover give resilience and even load, independent of local delegation.
+
+This module stays a deterministic control plane. It does not classify tasks for the caller — the
+caller passes a ``task`` hint or gets pure rotation; the optional classifier gate lives in
+:mod:`tanglebrain.classifier`. Orchestrators offload sub-tasks to the free local backend via the
+``delegate_local`` tool, which the router injects into their invocations.
+
+Rotation state persists across processes (each ``tanglebrain`` run is a new process), so successive
+requests rotate across the orchestrators.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Callable, Mapping
+
+from tanglebrain.adapters import AdapterError
+from tanglebrain.adapters.base import Adapter
+from tanglebrain.roster import RosterEntry, Roster
+from tanglebrain.selector import build_adapter
+from tanglebrain.settings import Settings, load_settings
+
+STATE_DIR_ENV = "TANGLEBRAIN_STATE_DIR"
+DEFAULT_STATE_SUBDIR = ".cache/tanglebrain"
+STATE_FILENAME = "router-state.json"
+
+# Substrings that mark an orchestrator failure as a rate-limit/capacity issue rather than a hard
+# error. Used only to annotate the failover log — failover happens on *any* AdapterError.
+_RATE_LIMIT_RE = re.compile(r"429|rate.?limit|quota|resource_exhausted|overloaded|too many requests", re.IGNORECASE)
+
+
+class RouterError(RuntimeError):
+    """Raised when no orchestrator can serve a request.
+
+    Two cases: the roster has no orchestrator-capable entry, or every orchestrator tried failed.
+    The message names each per-orchestrator failure so the caller can see what went wrong.
+    """
+
+
+def _looks_like_rate_limit(message: str) -> bool:
+    """Return whether an error message looks like a rate-limit / capacity rejection.
+
+    Args:
+        message: The error text (e.g. an ``AdapterError`` string).
+
+    Returns:
+        ``True`` if it matches a known rate-limit/capacity pattern.
+    """
+    return bool(_RATE_LIMIT_RE.search(message or ""))
+
+
+def default_state_path() -> Path:
+    """Return the rotation-state file path.
+
+    Honors ``TANGLEBRAIN_STATE_DIR`` (``~`` expanded); otherwise ``~/.cache/tanglebrain/``.
+
+    Returns:
+        The absolute path to the router state JSON file.
+    """
+    base = os.environ.get(STATE_DIR_ENV)
+    root = Path(base).expanduser() if base else Path.home() / DEFAULT_STATE_SUBDIR
+    return root / STATE_FILENAME
+
+
+def _read_cursor(path: Path) -> int:
+    """Read the rotation cursor from the state file, tolerating missing/corrupt state.
+
+    Args:
+        path: The state file path.
+
+    Returns:
+        The stored cursor (>= 0), or ``0`` if the file is absent, unreadable, or malformed —
+        bad state must never crash routing.
+    """
+    try:
+        data = json.loads(path.read_text())
+        cursor = int(data["cursor"])
+    except (OSError, ValueError, TypeError, KeyError, json.JSONDecodeError):
+        return 0
+    return cursor if cursor >= 0 else 0
+
+
+def _write_cursor(path: Path, cursor: int) -> None:
+    """Persist the rotation cursor, creating the parent directory as needed.
+
+    The write is not locked or atomic: two concurrent ``--route`` processes can read the same
+    cursor and both write (last-writer-wins), so a rotation slot may be skipped or repeated. That
+    is intentionally accepted — the cursor is a load-spread *hint*, not a correctness invariant, so
+    a lost update only mildly perturbs the spread, never breaks routing.
+
+    Args:
+        path: The state file path.
+        cursor: The cursor value to store.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps({"cursor": cursor}))
+
+
+class Router:
+    """Frontier-first orchestrator router: task-fit selection + rotation + failover."""
+
+    def __init__(
+        self,
+        roster: Roster,
+        state_path: str | os.PathLike[str] | None = None,
+        adapter_factory: Callable[..., Adapter] = build_adapter,
+        inject_delegate: bool = True,
+        settings: Settings | None = None,
+    ) -> None:
+        """Configure the router.
+
+        Args:
+            roster: The loaded roster; its ``can_orchestrate`` entries form the rotation set.
+            state_path: Path to the rotation-state file. Defaults to :func:`default_state_path`.
+                Inject a temp path in tests so they never touch the real cache.
+            adapter_factory: Builds an adapter for an entry. Defaults to the selector's
+                ``build_adapter``; injectable for tests. Called as
+                ``adapter_factory(entry, inject_delegate=...)``.
+            inject_delegate: Make the local-delegate tool available to each orchestrator, so it
+                offloads sub-tasks to the free local backend. On by default; set false to route to
+                bare orchestrators (e.g. for debugging).
+            settings: Global settings carrying the paid-API billing gate. Loaded from the
+                packaged ``config/settings.yaml`` when ``None``. The router consults
+                ``api_billing_enabled`` to decide whether the last-resort paid-API fallback is live;
+                with the gate off (the default) the router never reaches a paid tier.
+        """
+        self.roster = roster
+        self.state_path = Path(state_path) if state_path is not None else default_state_path()
+        self._adapter_factory = adapter_factory
+        self.inject_delegate = inject_delegate
+        self.settings = settings if settings is not None else load_settings()
+        # The entry that served the most recent successful route(), or None before any success.
+        # Surfaced so the CLI's measurement seam can record which tier/model handled a task
+        # without changing route()'s str return type.
+        self.last_served: RosterEntry | None = None
+
+    def route(
+        self,
+        prompt: str,
+        task: str | None = None,
+        opts: Mapping[str, object] | None = None,
+    ) -> str:
+        """Route ``prompt`` to an orchestrator sub, with task-fit, rotation, and failover.
+
+        Selection: among the ``can_orchestrate`` entries, walk in round-robin order starting from
+        the persisted cursor; if ``task`` is given, prefer entries whose ``good_at`` contains it
+        (falling back to all orchestrators when none match — task-fit is a preference, not a gate).
+        Try each in order; on an :class:`~tanglebrain.adapters.base.AdapterError` from one, fail
+        over to the next. On success, advance the persisted cursor past the served orchestrator so
+        the next request starts elsewhere (load-spread).
+
+        Last resort: if **every** orchestrator fails and the paid-API billing gate is on
+        (``settings.api_billing_enabled``), fall through to the enabled ``tier: api`` entries in
+        roster order — the genuine last resort. With the gate off (the default) the router never
+        reaches a paid tier. A paid success does not advance the orchestrator rotation cursor.
+
+        Args:
+            prompt: The task prompt.
+            task: Optional task-fit hint — a ``good_at`` tag (e.g. ``code``, ``reasoning``,
+                ``long-context``).
+            opts: Optional per-call adapter options (passed straight through to ``adapter.run``).
+
+        Returns:
+            The serving entry's response text (an orchestrator, or a paid-API fallback when the gate
+            is on and all orchestrators failed). The served entry is exposed on ``last_served``.
+
+        Raises:
+            RouterError: If the roster has no orchestrator-capable entry, or every candidate tried
+                (all orchestrators, plus any enabled paid-API fallback) failed.
+        """
+        orchestrators = self.roster.orchestrators()
+        if not orchestrators:
+            raise RouterError(
+                "no orchestrator-capable entries in roster (need at least one can_orchestrate: true)"
+            )
+
+        n = len(orchestrators)
+        cursor = _read_cursor(self.state_path) % n
+        rotated = [orchestrators[(cursor + i) % n] for i in range(n)]
+
+        if task:
+            candidates = [e for e in rotated if task in e.good_at] or rotated
+        else:
+            candidates = rotated
+
+        failures: list[tuple[str, str]] = []
+        for entry in candidates:
+            adapter = self._adapter_factory(entry, inject_delegate=self.inject_delegate)
+            try:
+                text = adapter.run(prompt, opts)
+            except AdapterError as exc:
+                failures.append((entry.id, str(exc)))
+                continue
+            served_pos = next(i for i, e in enumerate(orchestrators) if e.id == entry.id)
+            _write_cursor(self.state_path, (served_pos + 1) % n)
+            self.last_served = entry
+            return text
+
+        # Last-resort paid-API fallback. Only after EVERY orchestrator has failed, and only when
+        # billing is explicitly enabled, fall through to a paid `api` entry (the genuine last
+        # resort). With the gate off — the default — this block is skipped entirely, so the router
+        # can never reach a paid tier. Enabled paid entries are tried in roster order; a paid success
+        # does NOT advance the orchestrator rotation cursor (api is not part of the rotation). This
+        # requires at least one orchestrator above — the router never paid-routes a roster that has no
+        # orchestrators to exhaust (use ``--model`` for an explicit paid call).
+        if self.settings.api_billing_enabled:
+            attempted = {eid for eid, _ in failures}
+            for entry in self.roster.in_tier("api"):
+                # Skip disabled entries, and any already tried above (a degenerate roster could flag
+                # a paid entry ``can_orchestrate: true``, putting it in the rotation — don't re-run it).
+                if not entry.enabled or entry.id in attempted:
+                    continue
+                adapter = self._adapter_factory(entry, inject_delegate=self.inject_delegate)
+                try:
+                    text = adapter.run(prompt, opts)
+                except AdapterError as exc:
+                    failures.append((entry.id, str(exc)))
+                    continue
+                self.last_served = entry
+                return text
+
+        detail = "; ".join(
+            f"{eid}{' [rate-limit]' if _looks_like_rate_limit(msg) else ''}: {msg}"
+            for eid, msg in failures
+        )
+        raise RouterError(f"all {len(failures)} candidate(s) failed: {detail}")

tanglebrain/selector.py

@@ -0,0 +1,117 @@
+"""Direct selection — explicit entry / local-first resolution.
+
+**This is NOT the router.** The router (:mod:`tanglebrain.router`) — frontier-first decompose,
+task-fit orchestrator selection, rotation, failover — lives in its own module.
+
+This module's job is narrow: resolve a single entry (an explicit ``--model`` id, or the free local
+tier) and build its adapter. The logic here is deliberately minimal; do not grow it into the router
+— that belongs in its own module so the two don't get conflated.
+"""
+from __future__ import annotations
+
+from tanglebrain.adapters import ApiAdapter, AdapterError, CliAdapter, OpenAICompatAdapter
+from tanglebrain.adapters.base import Adapter
+from tanglebrain.roster import Roster, RosterEntry
+from tanglebrain.settings import Settings, load_settings
+
+
+class SelectionError(RuntimeError):
+    """Raised when no suitable roster entry can be selected for a request."""
+
+
+def select_local(roster: Roster) -> RosterEntry:
+    """Select the free local entry to route to.
+
+    Returns the first ``local``-tier entry invoked via ``openai-compat`` — the free tier the
+    openai-compat adapter can actually call.
+
+    Args:
+        roster: The loaded roster.
+
+    Returns:
+        The selected local :class:`~tanglebrain.roster.RosterEntry`.
+
+    Raises:
+        SelectionError: If the roster has no invocable local entry.
+    """
+    for entry in roster:
+        if entry.tier == "local" and entry.invoke.kind == "openai-compat":
+            return entry
+    raise SelectionError(
+        "no invocable local entry in roster (need tier=local, invoke.kind=openai-compat)"
+    )
+
+
+def select_by_id(roster: Roster, entry_id: str) -> RosterEntry:
+    """Select a roster entry by id (lets the CLI drive a named entry end-to-end).
+
+    This is **not** the router — it makes no routing decision, it just resolves an explicit id the
+    caller named. Orchestrator selection / rotation / failover lives in the router.
+
+    Args:
+        roster: The loaded roster.
+        entry_id: The id to select.
+
+    Returns:
+        The matching :class:`~tanglebrain.roster.RosterEntry`.
+
+    Raises:
+        SelectionError: If no entry has that id.
+    """
+    try:
+        return roster.by_id(entry_id)
+    except KeyError:
+        known = ", ".join(e.id for e in roster) or "(empty roster)"
+        raise SelectionError(f"no roster entry with id {entry_id!r}; known ids: {known}")
+
+
+def build_adapter(
+    entry: RosterEntry,
+    inject_delegate: bool = False,
+    settings: Settings | None = None,
+) -> Adapter:
+    """Build the adapter for a roster entry.
+
+    Supports the ``openai-compat`` (free local), ``cli`` (authenticated CLI), and ``api`` (paid,
+    gateway-fronted) adapters. The paid tier is **gated**: an ``api`` entry only builds when the
+    global ``api_billing_enabled`` flag is on *and* the entry's own ``enabled`` flag is on — the
+    durable "no paid billing without the explicit toggle" rule. Otherwise it raises clearly rather
+    than pretending the entry is routable, so a ``tier: api`` entry parses but stays inert by
+    default.
+
+    Args:
+        entry: The roster entry to build an adapter for.
+        inject_delegate: For ``cli`` entries, make the local-delegate tool available to the CLI as
+            an orchestrator — the router sets this so an orchestrator can offload sub-tasks to the
+            free local backend. Ignored for non-``cli`` kinds.
+        settings: Global settings carrying the billing gate. Loaded from the packaged
+            ``config/settings.yaml`` when ``None`` (and only when an ``api`` entry is actually being
+            built, so non-paid builds never touch the file). Injectable for tests.
+
+    Returns:
+        An :class:`~tanglebrain.adapters.base.Adapter` for the entry.
+
+    Raises:
+        AdapterError: If an ``api`` entry is selected while billing is gated off or the entry is
+            disabled, or if the invoke kind is unknown.
+    """
+    if entry.invoke.kind == "openai-compat":
+        return OpenAICompatAdapter.from_entry(entry)
+    if entry.invoke.kind == "cli":
+        return CliAdapter.from_entry(entry, inject_delegate=inject_delegate)
+    if entry.invoke.kind == "api":
+        if settings is None:
+            settings = load_settings()
+        if not settings.api_billing_enabled:
+            raise AdapterError(
+                f"entry {entry.id!r} is a paid-API tier but billing is disabled "
+                "(api_billing_enabled=false in config/settings.yaml); it is inert"
+            )
+        if not entry.enabled:
+            raise AdapterError(
+                f"paid-API entry {entry.id!r} is disabled (enabled=false); not routable"
+            )
+        return ApiAdapter.from_entry(entry)
+    raise AdapterError(
+        f"no adapter for invoke.kind {entry.invoke.kind!r} (entry {entry.id!r})"
+    )

tanglebrain/settings.py

@@ -0,0 +1,132 @@
+"""Global settings loader — the paid-API billing gate.
+
+The roster (``roster.yaml``) is a *list* of routable backends; per-entry policy lives there. But a
+few knobs are **global**, not per-entry — chief among them the paid-API billing gate. Those live
+here, in a separate ``config/settings.yaml`` mapping, so the roster stays a bare list (folding a
+global flag into it would force a breaking list→mapping parse change across every roster reader).
+
+``api_billing_enabled`` is the durable safety contract: **paid billing is OFF unless this flag is
+explicitly true.** When false, ``tier: api`` roster entries still
+parse and are inspectable, but :func:`tanglebrain.selector.build_adapter` refuses to build their
+adapter — they are inert. This is the single switch that makes accidental spend structurally hard.
+
+Loading is fault-tolerant in the *missing-file* direction only: an absent settings file yields the
+safe defaults (gate **off**). A present-but-malformed file raises :class:`SettingsError` rather than
+silently falling back, so a typo in the gate can never be mistaken for "billing enabled".
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+
+class SettingsError(ValueError):
+    """Raised when the settings YAML is present but malformed or semantically invalid.
+
+    A subclass of ``ValueError`` so callers can catch it specifically while still treating it as
+    the bad-input error it is. A *missing* file is not an error (it yields defaults); only a
+    present-but-broken file raises.
+    """
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Global, non-per-entry TangleBrain settings.
+
+    Attributes:
+        api_billing_enabled: The paid-API billing gate. ``False`` (the default) means every
+            ``tier: api`` roster entry parses but is **never routable** — the adapter factory
+            refuses to build it. Must be flipped to ``True`` explicitly to permit any paid spend.
+        classifier_gate_enabled: The local classifier gate. ``False`` (the default) keeps the
+            normal frontier-first routing. When ``True``, a cheap local classify runs in front of the
+            router: trivial requests go straight to the free local backend, only frontier requests
+            reach an orchestrator. Off until an operator turns it on.
+        delegate_max_concurrency: Operator cap on how many sub-tasks ``delegate_many`` runs at once.
+            ``None`` (the default) means TangleBrain derives the cap from the system
+            (``os.cpu_count()``). Set a positive int to pin it to the backend's real parallelism
+            (e.g. match a local model server's ``OLLAMA_NUM_PARALLEL``) — the true limit TB can't
+            portably introspect. A per-call ``max_concurrency`` may lower this but never exceed it.
+    """
+
+    api_billing_enabled: bool = False
+    classifier_gate_enabled: bool = False
+    delegate_max_concurrency: int | None = None
+
+
+def default_settings_path() -> Path:
+    """Return the path to the settings YAML shipped with the package.
+
+    Returns:
+        The absolute path to ``tanglebrain/config/settings.yaml``.
+    """
+    return Path(__file__).resolve().parent / "config" / "settings.yaml"
+
+
+def load_settings(path: str | os.PathLike[str] | None = None) -> Settings:
+    """Load global settings, defaulting safely when the file is absent.
+
+    Args:
+        path: Path to the settings YAML. Defaults to the packaged
+            ``tanglebrain/config/settings.yaml`` when ``None``.
+
+    Returns:
+        The parsed :class:`Settings`. A missing file yields :class:`Settings` defaults
+        (billing gate **off**).
+
+    Raises:
+        SettingsError: If the file exists but is not a YAML mapping, or ``api_billing_enabled``
+            is present and not a boolean. Never falls back silently on a malformed gate.
+    """
+    settings_path = Path(path) if path is not None else default_settings_path()
+    if not settings_path.exists():
+        return Settings()
+
+    try:
+        raw = yaml.safe_load(settings_path.read_text())
+    except yaml.YAMLError as exc:
+        raise SettingsError(f"settings file is not valid YAML: {settings_path}: {exc}") from exc
+
+    # An empty file (``raw is None``) is a valid "use all defaults" statement.
+    if raw is None:
+        return Settings()
+    if not isinstance(raw, dict):
+        raise SettingsError(
+            f"settings file must be a YAML mapping, got {type(raw).__name__}: {settings_path}"
+        )
+
+    def _bool(key: str) -> bool:
+        value = raw.get(key, False)
+        # Reject non-bool explicitly — `bool` is a subclass of `int`, but a stray `1`/`"true"` in a
+        # gate must be a hard error, never a coincidental truthy enable.
+        if not isinstance(value, bool):
+            raise SettingsError(
+                f"settings {key!r} must be a boolean (true/false), got "
+                f"{value!r} ({type(value).__name__}): {settings_path}"
+            )
+        return value
+
+    def _opt_positive_int(key: str) -> int | None:
+        value = raw.get(key)
+        if value is None:
+            return None
+        # Reject bool explicitly (bool is an int subclass) so a stray `true` can't pass as a count;
+        # reject floats/strings; require a positive count.
+        if isinstance(value, bool) or not isinstance(value, int):
+            raise SettingsError(
+                f"settings {key!r} must be a positive integer, got "
+                f"{value!r} ({type(value).__name__}): {settings_path}"
+            )
+        if value < 1:
+            raise SettingsError(
+                f"settings {key!r} must be >= 1, got {value!r}: {settings_path}"
+            )
+        return value
+
+    return Settings(
+        api_billing_enabled=_bool("api_billing_enabled"),
+        classifier_gate_enabled=_bool("classifier_gate_enabled"),
+        delegate_max_concurrency=_opt_positive_int("delegate_max_concurrency"),
+    )