pi-smart-router 0.1.0

package/README.md

@@ -0,0 +1,593 @@
+# pi-smart-router
+
+**Auto-model router middleware for the [pi](https://pi.dev) coding agent.**
+
+> **v0.1.0** is initial development (SemVer `0.y.z`). The public API and routing behavior may change until `1.0.0`.
+
+pi-smart-router intercepts every LLM inference request and dynamically routes it to the optimal execution engine — balancing cost, capability, latency, and time-to-first-token (TTFT) — without requiring you to manually pick a model for each turn.
+
+| pi-smart-router is | pi-smart-router is not |
+|--------------------|------------------------|
+| A pi extension that auto-selects the best model per request | A replacement for pi or your LLM provider |
+| A three-tier router: local, economical cloud, frontier cloud | A post-generation output judger (FrugalGPT-style) |
+| Cache-aware with session pinning to preserve prompt-cache economics | A turn-by-turn model switcher that shatters provider caching |
+| Registry-driven in pi (no YAML copy for normal use) | An RL-trained router requiring agent trace datasets |
+
+## How it works
+
+```text
+request → hardware probe → loop escalation → turn envelope → context-fit gate
+        → low-intensity tier gate → session pin → deterministic triage
+        → local zero-tier → HyDRA embedding matcher → safe cloud default
+        → context overflow fallback
+```
+
+The pipeline runs **12 stages sequentially with early exit** — the moment any stage reaches a routing decision, subsequent stages are skipped. Every decision includes the stage name, reason code, candidates considered, estimated cost, and routing latency for full observability.
+
+| Stage | Budget | What it does |
+|-------|--------|--------------|
+| Hardware Probe | — | Checks platform/RAM/battery to gate local inference |
+| Loop Escalation | — | Detects repeated identical tool failures; escalates session to frontier |
+| Turn Envelope | <2ms | Classifies turn type: tool_result, planning, subagent, main_loop |
+| Context-Fit Gate | — | Filters fleet to models whose context window fits estimated input tokens |
+| Low-Intensity Gate | — | Structural tier hint, cluster match, and P(success) expected-cost scoring |
+| Session Pin | <1ms | Returns pinned model if session has one; breaks pin on compaction or overflow |
+| Deterministic Triage | <5ms | Aho-Corasick keyword scan + cyclomatic complexity analysis |
+| Local Zero-Tier | <15ms | Pings LM Studio + Ollama in parallel; routes locally when eligible |
+| HyDRA Matcher | 80-120ms | ONNX embeddings, 3D requirement projection, shortfall gate, multi-objective scoring |
+| Safe Cloud Default | — | First healthy economical-cloud model (context-fit aware) |
+| Context Overflow Fallback | — | Escalates to largest-fit model when economical tiers cannot fit |
+
+## Research lineage
+
+pi-smart-router builds on ideas from several production and research routing systems:
+
+- **Adopted:** [GitHub Copilot HyDRA](https://arxiv.org/abs/2409.08379) (shortfall matching decoupled from model identities), Zero-Tier local edge-cache pattern, [Weave Router](https://github.com/workweave/router) session pinning and multi-objective selection
+- **Rejected:** FrugalGPT sequential cascading (tail latency), RouteLLM matrix factorization (confounder vulnerability), turn-by-turn dynamic routing (cache destruction)
+
+See [docs/PRD.md](docs/PRD.md) for full architectural justification.
+
+## Prerequisites
+
+| Dependency | Required | Notes |
+|------------|----------|-------|
+| [Node.js](https://nodejs.org/) >= 22 | Yes | ES module package; matches CI and `package.json` engines |
+| [pi](https://pi.dev) coding agent | Yes | Extension host |
+| macOS Apple Silicon | MVP | Primary supported platform |
+| Linux (x64/arm64) | Experimental | Probe logic supported; not validated on real hardware |
+| Windows (x64/arm64) | Experimental | Probe logic supported; not validated on real hardware |
+| [LM Studio](https://lmstudio.ai/) or [Ollama](https://ollama.com) | Optional | Required for zero-tier local routing |
+| Authenticated cloud providers in pi | Recommended | Anthropic, OpenAI, Google, etc. |
+
+## Install
+
+> **Security:** Pi packages run with full system access. Extensions execute arbitrary code. Review source before installing third-party packages ([pi packages docs](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md)).
+
+### Via pi (recommended)
+
+Install from [npm](https://www.npmjs.com/package/pi-smart-router) / [pi.dev/packages](https://pi.dev/packages):
+
+```bash
+pi install npm:pi-smart-router
+pi --list-models | grep smart-router
+```
+
+Project-local install (writes to `.pi/settings.json`):
+
+```bash
+pi install -l npm:pi-smart-router
+```
+
+Then in pi:
+
+```text
+/model smart-router/auto
+/smart-router status
+```
+
+**First run:** `pi install` runs `npm install` for package dependencies (`better-sqlite3` compiles natively). The first routed request downloads HyDRA ONNX weights to `.pi-smart-router/models/` under your state directory.
+
+### Via npm (library API)
+
+```bash
+npm install pi-smart-router
+```
+
+Use `createRouter()` / `createRouterFromFleet()` for programmatic integration without the pi extension. See [Optional: YAML fleet (library API)](#optional-yaml-fleet-library-api).
+
+### From source (contributors)
+
+```bash
+git clone https://github.com/beettlle/pi-smart-router.git
+cd pi-smart-router
+npm install
+```
+
+The repo ships a **project-local pi extension** at `.pi/extensions/smart-router/`. pi auto-discovers it when you run `pi` from the repo root (after the project is trusted — see [Develop from clone](#develop-from-clone)).
+
+## Quick start
+
+After installing via `pi install npm:pi-smart-router` (or from clone — see below):
+
+1. Authenticate providers (`/login`) and enable models in your scoped list if you use one (`/scoped-models`)
+2. `/model smart-router/auto` — every turn runs through the routing pipeline
+3. `/smart-router status` or `/smart-router history` — inspect routing decisions
+
+Set `SMART_ROUTER_LOG_ROUTING=1` before starting pi to print each routing decision to stderr (see [Environment variables](#environment-variables)).
+
+## Use with pi
+
+Detailed steps for the operator path above.
+
+### Installed via npm
+
+Global install (`pi install npm:pi-smart-router`) registers the extension from `~/.pi/agent/settings.json`. No project `/trust` prompt is required for npm-installed extensions — start `pi` from any directory.
+
+After auth or model list changes, restart pi or run `/reload`.
+
+### Develop from clone
+
+Project-local extensions under `.pi/extensions/` load only after the project is trusted. Without trust, the smart-router provider is never registered — `smart-router` will not appear in `/scoped-models` or `/model`, and `/smart-router` commands will not exist.
+
+**On first run**, pi prompts you to trust the project when it detects `.pi/extensions/`. Accept the prompt.
+
+**Later or missed prompt:** run `/trust` inside pi to save a trust decision for this directory (or its parent) to `~/.pi/agent/trust.json`. Trust on a **parent folder** (for example `~/Documents/github`) applies to this repo as well. After `/trust`, **restart pi** — the current session is not reloaded automatically.
+
+**Verify the extension loaded** (from the repo root):
+
+```bash
+cd pi-smart-router
+pi --list-models | grep smart-router
+```
+
+You should see `smart-router  auto`. If the line is missing:
+
+1. Confirm `pi` was started with cwd at this repo root (not a parent directory).
+2. Confirm the project is trusted (`/trust`, or check `~/.pi/agent/trust.json`).
+3. Restart pi or run `/reload` after trusting.
+
+Non-interactive one-shot checks can pass `--approve` to trust project-local resources for that run only.
+
+### Select the auto model
+
+Switch to the smart-router provider (from any directory after npm install, or from repo root when developing from clone):
+
+```text
+/model smart-router/auto
+```
+
+If you use **scoped models** (`/scoped-models` or `enabledModels` in settings), enable `smart-router/auto` there first — when a scoped list is active, `/model` only resolves models in that list.
+
+This registers `smart-router` as a custom provider with a single `auto` model. Every inference request runs through the routing pipeline and delegates to the selected underlying provider's streaming API.
+
+#### `cursor/auto` vs `smart-router/auto`
+
+pi exposes two different **auto** models. They are easy to confuse but play different roles:
+
+| Model | Provider | Role |
+|-------|----------|------|
+| `smart-router/auto` | `smart-router` (this extension) | Runs the routing pipeline on every turn and **delegates** to whichever underlying model HyDRA selects |
+| `cursor/auto` | `cursor` (pi registry) | Cursor's opaque auto model — **direct** inference target when selected; Cursor picks the backend model |
+
+**Recommended dogfood setup:** use `/model smart-router/auto` so routing, pinning, and telemetry stay active. Enable `cursor/auto` (and other Cursor models such as `composer-latest`) in your scoped fleet so the router can select them when appropriate — for example on planning turns or when the [Gemini tool-history guard](#gemini-thought_signature-400-errors) excludes Google models.
+
+**When to pin `/model cursor/auto` directly (bypass the router):**
+
+- You want Cursor's opaque auto selection on every turn with no routing overhead
+- You are debugging Cursor SDK auth or delegation outside the router
+- You need a stable, non-routed session for comparison with routed behavior
+
+**When to use `smart-router/auto`:**
+
+- You want cost/capability-aware model selection across your full authenticated fleet
+- You rely on session pinning, failover, or `/smart-router status` / `history` telemetry
+- Tool-heavy sessions should fall back to `cursor/auto` or other non-Gemini models automatically (see [pi-smart-router#38](https://github.com/beettlle/pi-smart-router/issues/38))
+
+Cursor models (`cursor/*`, `composer-*`, and the opaque fleet id `default`) map to **frontier-cloud** tier in `pi-model-mapper.ts` so HyDRA can score them against Gemini and Claude instead of treating them as unknown economical models ([pi-smart-router#40](https://github.com/beettlle/pi-smart-router/issues/40), [pi-smart-router#70](https://github.com/beettlle/pi-smart-router/issues/70)). Related: [pi-smart-router#23](https://github.com/beettlle/pi-smart-router/issues/23) (turn envelope / pin order), [pi-smart-router#37](https://github.com/beettlle/pi-smart-router/issues/37) (Gemini `thought_signature` errors).
+
+#### Cursor subscription quota vs API cost
+
+Cursor models bill against your **Cursor Pro subscription quota**, not per-token API rates. The mapper sets `fallback_cost_per_1m: 0` (no API billing) and a separate **`quota_cost_per_1m`** virtual rate used only for frugality scoring and telemetry ([SP-096](https://github.com/beettlle/pi-smart-router/issues/70)). Economical API models (e.g. `gemini-flash-lite`) can outscore `composer-latest` on routine `main_loop` turns when capabilities are sufficient.
+
+**Quota-sensitive fleet hygiene:** if you are near Cursor usage limits, **exclude `composer-latest`** (and other heavy Cursor frontier models) from your pi scoped fleet enable-list. Leave economical API models enabled so turn envelope and HyDRA prefer paid API tiers over subscription quota. The opaque id `default` is mapped to frontier tier — do not rely on it as an economical fallback.
+
+### Operator commands
+
+| Command | Purpose |
+|---------|---------|
+| `/smart-router` | Same as `status` (default when no subcommand is given) |
+| `/smart-router status` | Show fleet mode, fleet size, pricing freshness/staleness, and the last routing decision (stage, tier, selected model, latency) |
+| `/smart-router history` | Show recent routing telemetry from SQLite (default limit; optional numeric limit, e.g. `/smart-router history 20`) |
+| `/smart-router mode scoped` | Route only among pi's **enabled model patterns** (default) |
+| `/smart-router mode all` | Route among **all authenticated models** in the registry |
+| `/smart-router pricing refresh` | Manually fetch LiteLLM pricing from `LITELLM_PRICING_URL`, persist to SQLite, and rebuild the fleet with updated rates |
+| `/smart-router export dataset [--limit N]` | Export opt-in routing dataset as JSONL (requires `SMART_ROUTER_DATASET=1`) |
+| `/smart-router export telemetry-contrib [--limit N]` | Export privacy-safe community telemetry JSON for calibration contributions |
+| `/smart-router feedback good\|bad` | Label the last auto-routed request outcome (requires `SMART_ROUTER_DATASET=1`) |
+| `/smart-router unpin` | Clear the current session pin (in-memory and SQLite) so the next request runs the full routing pipeline |
+
+Fleet mode persists in the session. Use `scoped` to respect your `/model` enable-list; use `all` when you want the router to consider every provider you have logged into.
+
+After typing `/smart-router ` (with a trailing space), press **TAB** to see subcommands. Continue TAB-completing after `mode` or `pricing` for sub-options (`scoped`/`all`, `refresh`).
+
+### 5. Verify
+
+```bash
+npm run verify:ci
+```
+
+## Fleet behavior
+
+When you use `smart-router/auto`, the extension does **not** read `config/models.yaml`. Instead:
+
+1. **Discover** — `modelRegistry.getAvailable()` returns authenticated models from pi.
+2. **Scope** — In `scoped` mode, filter to patterns from pi settings (`getEnabledModels()`). In `all` mode, use the full registry.
+3. **Map** — `src/config/pi-model-mapper.ts` maps each pi model to a `ModelProfile` (tier, capabilities, pricing) using provider and model-id patterns.
+4. **Route** — `createRouterFromFleet()` runs the 12-stage pipeline on each request.
+5. **Delegate** — The extension resolves the chosen model in the registry and forwards the stream via pi-ai's built-in provider APIs.
+
+Unknown models receive conservative economical-cloud defaults. Local providers (`lmstudio`, `ollama`) map to `zero-tier`. Cursor provider models (`cursor/*`, `composer-*`, opaque id `default`) map to `frontier-cloud` with explicit capability defaults (SP-086, SP-098).
+
+To refresh after auth or settings changes, restart pi or `/reload` extensions.
+
+## Optional: YAML fleet (library API)
+
+For programmatic integration **without** the pi extension, load a static fleet catalog from YAML and route via `GatewayDispatch.dispatch()`:
+
+```bash
+cp config/models.yaml.example ./config/models.yaml
+# Edit config/models.yaml — at least one model per tier
+```
+
+```typescript
+import { createRouter } from 'pi-smart-router';
+
+const router = createRouter({ modelsPath: './config/models.yaml' });
+router.register(piExtensionHooks); // lifecycle only: compaction + model override
+
+const decision = await router.dispatch.dispatch(routingRequest);
+// Embedder forwards inference to decision.selected_model_id
+```
+
+### Embedder integration paths
+
+| Path | When to use | Routing | Lifecycle hooks |
+|------|-------------|---------|-----------------|
+| **Pi extension** (recommended) | Running inside pi | `pi install npm:pi-smart-router` (or project-local `.pi/extensions/smart-router/` when developing from clone) registers `smart-router/auto` and delegates streams | Extension calls `router.register()`; compaction/model overrides wired automatically |
+| **Library API** | Custom host, tests, or non-pi embedders | Your code calls `router.dispatch.dispatch()` (or wraps the pipeline) | Call `router.register(hooks)` to wire compaction and `model_select` events |
+
+The library `createPiRouterMiddleware()` / `RouterHandle.register()` registers **lifecycle hooks only** — not routing, context capture, or `before_provider_request`. Do not expect `middleware` to intercept LLM streams; that is the extension's `streamSimple` path or your embedder's dispatch loop.
+
+`createRouter()` returns a `RouterHandle`:
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| `middleware` | `PiRouterMiddleware` | Lifecycle hook registrar (`register`, `lifecycleHookState`) |
+| `dispatch` | `GatewayDispatch` | Gateway with circuit breaker, failover, rate limiting |
+| `fleet` | `readonly ModelProfile[]` | Loaded fleet catalog |
+| `register` | `(hooks) => void` | Alias for `middleware.register` — attach pi lifecycle hooks |
+
+You can also pass a pre-built fleet:
+
+```typescript
+import { createRouterFromFleet } from 'pi-smart-router';
+
+const router = createRouterFromFleet(myFleetProfiles);
+```
+
+Example fleet entry:
+
+```yaml
+models:
+  - id: local-gemma-4-7b
+    tier: zero-tier
+    provider: lmstudio
+    endpoint: http://localhost:1234/v1
+    capabilities:
+      reasoning: 0.3
+      code_gen: 0.6
+      tool_use: 0.1
+    pricing:
+      registry_key: local/free
+      fallback_cost_per_1m: 0.0
+
+  - id: claude-3.5-haiku
+    tier: economical-cloud
+    provider: anthropic
+    # ...
+
+  - id: claude-3.5-sonnet
+    tier: frontier-cloud
+    provider: anthropic
+    # ...
+```
+
+Tiers: `zero-tier`, `economical-cloud`, `frontier-cloud`. See [config/models.yaml.example](config/models.yaml.example).
+
+### Routing cluster catalog (library API)
+
+Reference prompts grouped by tier bias for semantic cluster matching (SP-099). Operators tune clusters in YAML without code changes. Precomputed centroids live in `config/routing-centroids.json` (SP-114); when that file is absent, centroids are computed at load time as the mean embedding of each cluster's reference prompts.
+
+```bash
+cp config/routing-clusters.yaml.example ./config/routing-clusters.yaml
+cp config/routing-centroids.json.example ./config/routing-centroids.json
+# Edit reference_prompts, min_similarity, and min_margin per cluster
+# Regenerate centroids after catalog changes:
+npm run routing:bootstrap-centroids
+```
+
+The bootstrap script embeds each reference prompt via the HyDRA MiniLM ONNX pipeline (384-dim), mean-pools to centroid vectors, and writes `config/routing-centroids.json` with `{ cluster_id, tier_bias, centroid, reference_count }` per cluster. ONNX artifacts cache under `.pi-smart-router/models/` on first run.
+
+```typescript
+import { loadRoutingClusters } from 'pi-smart-router';
+
+const catalog = await loadRoutingClusters({
+  filePath: './config/routing-clusters.yaml',
+  embedder: myTextEmbedder, // shared ONNX embedder (SP-100)
+});
+// Reason codes: cluster_${id} — e.g. cluster_low_stakes_general
+
+// createClusterMatcher (cluster-matcher module) prefers routing-centroids.json when present.
+```
+
+Cluster IDs are stable reason-code prefixes (`cluster_low_stakes_general`, `cluster_architecture`, etc.). See [config/routing-clusters.yaml.example](config/routing-clusters.yaml.example).
+
+## Configuration
+
+### Environment variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `ROUTER_STATE_DB_PATH` | `./.pi-smart-router/state.db` | Override SQLite state store location (telemetry, pricing catalog, session data) |
+| `SMART_ROUTER_LOG_ROUTING` | (unset) | Set to `1` to log each routing decision to stderr as JSON (debugging dogfood sessions) |
+| `SMART_ROUTER_DATASET` | (unset) | Set to `1` to opt in to privacy-safe routing dataset capture (metadata and feature fields only; 30-day / 10k-row retention). Prompt text, messages, and tool arguments are never stored. Required for outcome labels and P(success) training export. See [#8](https://github.com/beettlle/pi-smart-router/issues/8). |
+| `SMART_ROUTER_DATASET_FINGERPRINT` | (unset) | Set to `1` (requires `SMART_ROUTER_DATASET=1`) to store an install-local HMAC-SHA256 fingerprint of each normalized prompt for duplicate detection within this install. The install pepper lives in `.pi-smart-router/.dataset-key` (gitignored) and is never exported. **Warning:** short or common prompts are vulnerable to offline rainbow-table guessing; use only when you accept that tradeoff. See [#10](https://github.com/beettlle/pi-smart-router/issues/10). |
+| `MODELS_YAML_PATH` | `./config/models.yaml` | Fleet catalog path (library API only) |
+| `ROUTER_SAFE_DEFAULT_TIER` | `economical-cloud` | Fallback tier on any routing failure |
+| `LITELLM_PRICING_URL` | — | LiteLLM pricing JSON source |
+
+### P(success) training export (baseline classifier)
+
+When `SMART_ROUTER_DATASET=1`, the router records privacy-safe dataset rows and behavioral outcome labels (model override, compaction pin break, `/smart-router feedback good|bad`). Export labeled training data from pi:
+
+```bash
+/smart-router export dataset [--limit N]
+```
+
+Each JSONL row joins dataset features with `success_label` and `outcome_signals`. Success means no negative outcome signals were recorded for that `request_id` (for example `model_override` or `feedback_bad` mark failure). Prompt plaintext is never included.
+
+Train a baseline logistic scorer offline from the export (see `src/domain/routing/p-success-classifier.ts`):
+
+- `trainFromExportJsonl(exportContent)` — fit coefficients from labeled JSONL
+- `predictPSuccessCheap(features, weights)` — returns `P_success_cheap` in `[0, 1]`
+
+Copy `config/p-success-weights.json.example` to `config/p-success-weights.json` and replace coefficients after training. **Minimum sample guidance:** collect at least **30** labeled economical-tier rows before relying on non-neutral predictions; below that threshold the classifier returns neutral `P_success_cheap = 0.5`. **Online inference** is active in the low-intensity gate; without trained weights the router uses neutral defaults until you add `config/p-success-weights.json`.
+
+### Community telemetry contribution (calibration)
+
+When `SMART_ROUTER_DATASET=1`, you can export privacy-safe scalar routing features (plus outcome labels) for community calibration training. The export never includes prompt text, messages, raw session identifiers, or install-local pepper fields.
+
+```bash
+/smart-router export telemetry-contrib [--limit N]
+# or from shell (cwd must contain .pi-smart-router/state.db):
+npx pi-smart-router export telemetry-contrib [--limit N]
+```
+
+This writes schema-valid JSON to `.pi-smart-router/exports/telemetry-contrib-<timestamp>.json`. Each row conforms to [`telemetry-contrib.schema.json`](specs/001-build-smart-router/contracts/telemetry-contrib.schema.json).
+
+**How to contribute**
+
+1. Opt in to dataset capture (`SMART_ROUTER_DATASET=1`) and dogfood with `/model smart-router/auto` for several sessions.
+2. Run `export telemetry-contrib` locally and review the export — confirm it contains no prompt content.
+3. Submit anonymized rows via **pull request** under `data/contrib/` (one `.json` array or `.jsonl` file per install) **or** attach the export to a [GitHub Discussion](https://github.com/beettlle/pi-smart-router/discussions) using the community telemetry template.
+4. Maintainers aggregate contributions with `npm run routing:calibration-aggregate -- --contrib-dir data/contrib`; ingest rejects tainted payloads (prompt/message keys) and strips install-local pepper fields before offline training (SP-116, SP-117).
+
+See the synthetic reference file at [`data/contrib/example.json`](data/contrib/example.json).
+
+### Operator tuning (frugality slider)
+
+The multi-objective scoring weights control the cost-vs-quality tradeoff:
+
+| Key | Default | Effect |
+|-----|---------|--------|
+| `frugality.lambda_cost` | 0.5 | Higher favors cheaper models at quality parity |
+| `frugality.lambda_latency` | 0.1 | Higher penalizes slow models |
+| `frugality.lambda_verbosity` | 0.15 | Higher penalizes verbose models |
+
+Additional operator defaults:
+
+| Key | Default | Purpose |
+|-----|---------|---------|
+| `loop_escalation.threshold` | 3 | Consecutive identical failures before escalating to frontier |
+| `local.min_memory_gb_full` | 16 | Minimum RAM for full local inference |
+| `local.battery_threshold_pct` | 20 | Minimum battery to allow local inference |
+| `pricing.staleness_days` | 14 | Max age before re-fetching pricing data |
+
+### HyDRA model cache
+
+The embedding matcher uses `@huggingface/transformers` with the `Xenova/all-MiniLM-L6-v2` ONNX model (384-dim embeddings). Artifacts are downloaded at runtime and cached under `.pi-smart-router/models/` (configurable via `hydra.artifact_cache_path`). This directory is gitignored.
+
+## Architecture
+
+### Three execution tiers
+
+| Tier | Catalog Name | Purpose | Example |
+|------|-------------|---------|---------|
+| Local | `zero-tier` | Free on-device inference for trivial tasks | Gemma via LM Studio |
+| Cheap Cloud | `economical-cloud` | Budget API models for routine work | Claude Haiku |
+| Frontier Cloud | `frontier-cloud` | Top-tier models for complex reasoning | Claude Sonnet |
+
+### Pi extension
+
+The pi integration path (npm install or project-local clone):
+
+- Registers provider **`smart-router`** with model **`auto`**
+- Implements **`streamSimple`** — runs the pipeline, resolves the target in `ModelRegistry`, delegates to the built-in streaming API for that provider
+- Wires lifecycle hooks via `router.register()` for session state:
+
+| Event | Purpose |
+|-------|---------|
+| `session_compact` / `session_before_compact` | Breaks session pin on compaction (via `LifecycleHookState`) |
+| `model_select` | Records user-forced model overrides when `source === "set"` |
+| `session_start` | Restores fleet mode from session entries |
+
+Conversation context for routing is read from the stream delegation path (`buildRoutingRequest`), not from a library `context` hook. Library embedders supply `messages` / `prompt_text` when calling `dispatch.dispatch()`.
+
+### Session pinning
+
+Sessions pin to the first routed model to preserve provider-side prompt prefix caching. Pins break only on:
+
+- Session compaction
+- User model override (`/model` in pi)
+- Loop escalation (repeated identical tool failures)
+- Cache-warmup economics threshold
+
+Sub-routing within a pin is allowed: small `tool_result` turns may use an economical model on the same provider without breaking the pin.
+
+### Gateway resilience
+
+The `GatewayDispatch` layer wraps the pipeline with:
+
+- **Circuit breaker** — Per-model, tracks consecutive 5xx/network errors (CLOSED → OPEN → HALF_OPEN). 4xx and safety errors do not trip the breaker.
+- **Failover chains** — On open circuit, routes to same-tier alternative via inverse-cost weighted selection.
+- **Rate limiting** — Per-operator-key token bucket with `429 + Retry-After` responses.
+
+### Troubleshooting
+
+#### Gemini `thought_signature` 400 errors
+
+If Gemini returns **400 INVALID_ARGUMENT** mentioning `thought_signature`, the router treats this as a **protocol validation error** (incomplete tool-call replay), not provider unavailability — it will **not** failover to another model.
+
+This typically happens when a session with prior tool calls is routed to Gemini before [pi preserves thought signatures in replay](https://github.com/earendil-works/pi/issues/6342). See [Google's thought signatures documentation](https://ai.google.dev/gemini-api/docs/generate-content/thought-signatures).
+
+**Automatic guard (SP-077):** sessions with prior tool-call history exclude Google/Gemini models from routing (telemetry `reason_code: gemini_tool_history_excluded`) unless the operator sets `force_model_id` via `/model`. Non-tool sessions are unchanged.
+
+**Empty fleet fail-safe (SP-084):** when the guard filters every model in the scoped fleet (e.g. Google/Gemini-only dogfood configs), the router throws an actionable error instead of delegating with `selected_model_id: unknown`. Add a non-Google model such as `openai/gpt-4o-mini` or `cursor/auto` to the fleet, start `/new`, or pin `/model` to force a specific model.
+
+**Workarounds:**
+
+1. Start a fresh session with `/new` in pi.
+2. Switch to a non-Google model (e.g. `/model openai/gpt-4o-mini`) for tool-heavy sessions until the upstream fix lands.
+
+Related: [pi-smart-router#37](https://github.com/beettlle/pi-smart-router/issues/37), [pi-smart-router#38](https://github.com/beettlle/pi-smart-router/issues/38), [pi-smart-router#40](https://github.com/beettlle/pi-smart-router/issues/40), [pi-smart-router#41](https://github.com/beettlle/pi-smart-router/issues/41), [pi#6342](https://github.com/earendil-works/pi/issues/6342).
+
+### Explain endpoint (library API)
+
+The explain handler runs the identical pipeline but returns the `RoutingDecision` without dispatching upstream inference — guaranteeing bit-for-bit decision equivalence with the live path. Useful for debugging, operator trust, and shadow runs. Exposed via the library API (`src/api/explain/router-explain.ts`); HTTP/CLI wiring is embedder-specific.
+
+## API
+
+### Public exports
+
+```typescript
+import {
+  createRouter,
+  createRouterFromFleet,
+  createPiRouterMiddleware,
+  LifecycleHookState,
+  type RoutingDecision,
+  type ModelProfile,
+  type PiRouterMiddleware,
+  type PiExtensionHooks,
+  type RouterHandle,
+} from 'pi-smart-router';
+```
+
+`createPiRouterMiddleware()` is exported for advanced embedders that need a standalone lifecycle hook registrar. Most callers should use `createRouter()` / `createRouterFromFleet()` and call `register()` on the returned handle.
+
+### `RoutingDecision`
+
+Every routing decision includes:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `selected_model_id` | `string` | Fleet model ID chosen |
+| `tier` | `Tier` | `zero-tier`, `economical-cloud`, or `frontier-cloud` |
+| `stage` | `string` | Pipeline stage that decided (triage, session_pin, local_zero, etc.) |
+| `reason_code` | `string` | Machine-readable reason |
+| `candidates` | `string[]` | Models considered before selection |
+| `estimated_cost_usd` | `number` | Per-request cost estimate |
+| `routing_latency_ms` | `number` | Time spent in the routing pipeline |
+
+## Development
+
+```bash
+git clone https://github.com/beettlle/pi-smart-router.git
+cd pi-smart-router
+npm install
+npm run build
+npm run verify:ci
+```
+
+Contributors must run `npm run build` before publishing or consuming the library API from `dist/`. The pi extension uses TypeScript source directly (via pi's jiti loader) and does not require a local build for clone-based dogfooding.
+
+### Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `npm run build` | Compile library to `dist/` (`tsc --project tsconfig.build.json`) |
+| `npm run release:check` | Pre-release gate (same as `verify:ci`) |
+| `npm run verify:ci` | Full CI parity: build, typecheck, lint, test, coverage |
+| `npm run typecheck` | TypeScript strict mode check (`tsc --noEmit`) |
+| `npm test` | Run test suite (`vitest run`) |
+| `npm run coverage:check` | Tests with line-coverage thresholds |
+| `npm run lint` | ESLint + fleet catalog validation |
+| `npm run routing:bootstrap-centroids` | Regenerate `config/routing-centroids.json` from cluster catalog |
+| `npm run routing:calibration-aggregate` | Aggregate community telemetry for calibration |
+| `npm run routing:train-calibration` | Train routing calibration artifact bundle |
+| `npm run routing:verify-calibration` | Verify calibration bundle against benchmark prompts |
+
+### Releasing
+
+Tag-triggered publish via GitHub Actions (requires `NPMSECRET` repository secret):
+
+1. `npm run release:check`
+2. `npm version 0.1.0` (creates commit + `v0.1.0` tag)
+3. `git push && git push --tags`
+4. Actions → **Release** runs `npm publish` and creates a GitHub Release
+5. Post-publish smoke: `pi install npm:pi-smart-router` and `/model smart-router/auto`
+
+Re-publish a failed release: Actions → Release → Run workflow with existing tag (e.g. `v0.1.0`).
+
+Dry-run tarball contents locally:
+
+```bash
+npm run release:check
+npm pack --dry-run
+```
+
+### Test suite
+
+1117 tests across 61 test files covering:
+
+- Unit tests for every pipeline stage, domain module, and infrastructure component
+- Contract tests validating routing request/decision schemas
+- Integration tests for full pipeline routing, session pinning, latency budgets, and cost baselines
+- Pi extension tests (`tests/integration/pi-extension.test.ts`) for registry → fleet → stream delegation
+- Resilience tests for circuit breaker, failover, and rate limiting
+
+## Documentation
+
+| Document | Purpose |
+|----------|---------|
+| [docs/PRD.md](docs/PRD.md) | Product requirements, research lineage, pipeline specification |
+| [docs/constitution.md](docs/constitution.md) | Project principles and non-negotiable rules |
+| [specs/001-build-smart-router/spec.md](specs/001-build-smart-router/spec.md) | Detailed feature specification |
+| [specs/001-build-smart-router/data-model.md](specs/001-build-smart-router/data-model.md) | Entity definitions, schemas, configuration reference |
+| [specs/001-build-smart-router/quickstart.md](specs/001-build-smart-router/quickstart.md) | Setup and verification guide |
+| [config/models.yaml.example](config/models.yaml.example) | Fleet catalog template (library API) |
+| [config/routing-clusters.yaml.example](config/routing-clusters.yaml.example) | Routing cluster reference-prompt catalog (library API) |
+
+## Built with
+
+- [pi](https://pi.dev) — Coding agent harness (extension host)
+- [@earendil-works/pi-ai](https://pi.dev) — Provider streaming APIs
+- [pi-spine](https://github.com/beettlle/pi-spine) — Batch orchestration (used to build this project)
+- [stet](https://github.com/beettlle/stet) — Local code review (guardrails during development)
+- [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) — Shared state store
+- [zod](https://zod.dev) — Runtime schema validation
+- [@huggingface/transformers](https://huggingface.co/docs/transformers.js) — ONNX embedding inference for HyDRA matcher
+
+## License
+
+MIT

package/bin/pi-smart-router.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+/**
+ * pi-smart-router CLI — offline operator tools (telemetry export, etc.).
+ * Requires `npm run build` so dist/ artifacts exist (release:check runs build first).
+ */
+
+import { join, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const MIN_NODE_MAJOR = 22;
+const nodeMajor = Number.parseInt(process.versions.node.split('.')[0] ?? '0', 10);
+if (nodeMajor < MIN_NODE_MAJOR) {
+  console.error(
+    `pi-smart-router requires Node.js >= ${MIN_NODE_MAJOR}.0.0 (found ${process.versions.node}).`,
+  );
+  process.exit(1);
+}
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+async function loadDist(modulePath) {
+  return import(pathToFileURL(join(packageRoot, modulePath)).href);
+}
+
+function getRouterStateDbPath(cwd) {
+  const configured = process.env.ROUTER_STATE_DB_PATH?.trim();
+  if (configured && configured.length > 0) {
+    return configured;
+  }
+  return join(cwd, '.pi-smart-router/state.db');
+}
+
+function printUsage() {
+  console.error(`Usage:
+  pi-smart-router export telemetry-contrib [--limit N]
+
+Run from a directory with pi routing state (default: ./.pi-smart-router/state.db).`);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const args = argv.join(' ');
+
+  const cli = await loadDist('dist/cli/smart-router-cli.js');
+  const sqlite = await loadDist('dist/infrastructure/persistence/sqlite-store.js');
+
+  if (cli.isExportTelemetryContribInvocation(args)) {
+    const { limit } = cli.parseExportTelemetryContribArgs(args);
+    const cwd = process.cwd();
+    const { store } = sqlite.createResilientStore({
+      dbPath: getRouterStateDbPath(cwd),
+      models: [],
+    });
+
+    const result = await cli.exportTelemetryContrib({ store, cwd, limit });
+    if (result.path) {
+      console.log(`Exported ${result.recordCount} telemetry-contrib record(s) to ${result.path}`);
+      return;
+    }
+
+    if (result.recordCount === 0) {
+      console.log('No telemetry-contrib records to export (opt in with SMART_ROUTER_DATASET=1).');
+      return;
+    }
+
+    console.log(result.json);
+    return;
+  }
+
+  printUsage();
+  process.exit(1);
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exit(1);
+});