@gabrielsmartin/orbit-sdk 0.3.0 → 0.3.2

package/README.md

@@ -0,0 +1,193 @@
+# orbit-ai
+
+> Stop blasting every query at GPT-4o. Route intelligently. Save 85%.
+
+`orbit-ai` is a drop-in routing layer that reads the fingerprint of every AI query and sends it to the optimal model — automatically, in under 1ms.
+
+```bash
+npm install orbit-ai
+```
+
+---
+
+## 🚀 Pro is live
+
+**[orbit.gtll.app](https://orbit.gtll.app)** — production routing API with managed keys, usage analytics, and team dashboards.
+
+| Plan | Price | What's included |
+|---|---|---|
+| **Founding Pro** | $19/mo | API access · 500k routed queries/mo · savings dashboard |
+| **Founding Team** | $99/mo | Unlimited queries · multi-seat · priority support |
+
+[→ Get Founding Pro](https://buy.stripe.com/6oE5kF3Yz5Co06s9AB) · [→ Get Founding Team](https://buy.stripe.com/9AQ9AV5GH9SEdss6op)
+
+*Founding pricing locks in forever — price goes up at 100 customers.*
+
+---
+
+## How it works
+
+Every query gets fingerprinted across **9 axes** in under 1ms:
+
+| Axis | What it measures |
+|---|---|
+| **Complexity** | Depth of reasoning required |
+| **Creativity** | Open-ended vs deterministic |
+| **Emotional Weight** | Sensitivity — crisis queries always go to Claude |
+| **Recency** | Need for live/current data → Grok |
+| **Context Load** | Window size needed → Claude 200k |
+| **Speed** | Latency sensitivity |
+| **Domain** | Code · Creative · Medical · Legal · General |
+| **Cost Tolerance** | Budget tier (overridable) |
+| **Signal** | Intent code — 777 (completion) · 555 (variation) · 333 (foundation) |
+
+Then it routes to the right model. Invisibly.
+
+---
+
+## Usage
+
+### Zero-config routing decision
+
+```javascript
+import orbit from 'orbit-ai'
+
+const decision = orbit.route("write a haiku about recursion")
+
+console.log(decision.model.name)    // "Claude Sonnet"
+console.log(decision.reason)        // "High creativity score (8/10)..."
+console.log(decision.savings)       // { savings: 0.007245, reductionPct: 97 }
+```
+
+### With signal codes (v0.3.0+)
+
+```javascript
+import { OrbitClient } from 'orbit-ai'
+
+const orbit = new OrbitClient({ log: true })
+
+// 777 — completion mode, forces high-capability model
+orbit.route("finalize the architecture doc", { signal: "777" })
+// → Claude Sonnet (floor enforced)
+
+// 555 — variation mode, maximizes model diversity
+orbit.route("brainstorm 10 unexpected product names", { signal: "555" })
+// → Grok (variation bias)
+
+// 333 — foundation mode, minimizes cost
+orbit.route("summarize this paragraph", { signal: "333" })
+// → Gemini 2.5 Flash
+```
+
+### With your own API keys
+
+```javascript
+import { OrbitClient } from 'orbit-ai'
+
+const orbit = new OrbitClient({
+  cost_tolerance: 'low',  // 'low' | 'medium' | 'high'
+  log: true,
+})
+
+const { model, reason, savings } = orbit.route("explain blockchain simply")
+// [ORBIT] → Gemini 2.5 Flash | saved $0.01455 (97% reduction)
+
+// model.id = 'gemini-2.5-flash', model.provider = 'google'
+// Call the model yourself with your keys
+```
+
+### Full pipeline example
+
+```javascript
+import { OrbitClient } from 'orbit-ai'
+import Anthropic from '@anthropic-ai/sdk'
+import OpenAI from 'openai'
+import { GoogleGenerativeAI } from '@google/generative-ai'
+
+const orbit = new OrbitClient({ log: true })
+
+async function smartQuery(text, signal) {
+  const { model } = orbit.route(text, { signal })
+
+  if (model.provider === 'anthropic') {
+    const client = new Anthropic()
+    return client.messages.create({ model: model.id, max_tokens: 1024, messages: [{ role: 'user', content: text }] })
+  }
+  if (model.provider === 'openai') {
+    const client = new OpenAI()
+    return client.chat.completions.create({ model: model.id, messages: [{ role: 'user', content: text }] })
+  }
+  if (model.provider === 'google') {
+    const client = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY)
+    return client.getGenerativeModel({ model: model.id }).generateContent(text)
+  }
+}
+
+await smartQuery("write a poem about the ocean")                    // → Claude Sonnet
+await smartQuery("what's the latest news on AI funding?")           // → Grok
+await smartQuery("what is 2+2")                                     // → Gemini Flash
+await smartQuery("I've been feeling really overwhelmed")            // → Claude Sonnet (ethics-first)
+await smartQuery("finalize the system design", { signal: "777" })   // → Claude Sonnet (forced)
+```
+
+### Session stats
+
+```javascript
+const stats = orbit.stats()
+console.log(stats.total_savings_formatted)  // "$0.2341"
+console.log(stats.model_usage)              // { "Claude Sonnet": 4, "Gemini 2.5 Flash": 12, ... }
+```
+
+---
+
+## Model matrix
+
+| Model | Provider | Cost/1M | Best for |
+|---|---|---|---|
+| Claude Sonnet 3.5 | Anthropic | $15 | Complex reasoning · Ethics · Long context |
+| Claude Haiku | Anthropic | $1 | Speed · Summaries · Medium tasks |
+| Gemini 2.5 Flash | Google | $0.50 | High volume · Simple queries · Cost |
+| GPT-4o | OpenAI | $30 | Structured output · Broad knowledge |
+| GPT-4o Mini | OpenAI | $0.30 | Classification · Filler tasks |
+| Grok | xAI | $10 | Trending · Real-time web |
+
+---
+
+## The math
+
+Validated by [RouteLLM (UC Berkeley · ICLR 2025)](https://arxiv.org/abs/2406.18665): intelligent routing achieves **85% cost reduction** while maintaining 95% of quality.
+
+For a team running 100k queries/month at GPT-4o:
+- Without ORBIT: **$1,500/month**
+- With ORBIT: **~$225/month**
+- Savings: **$1,275/month · $15,300/year**
+
+---
+
+## Live demo
+
+[orbit-model-flow.base44.app](https://orbit-model-flow.base44.app) — route a real query, see the fingerprint radar, watch the savings counter.
+
+---
+
+## Roadmap
+
+- [x] 8-axis fingerprinting engine
+- [x] 6-model routing matrix
+- [x] TypeScript types
+- [x] Signal-aware routing (777 · 555 · 333)
+- [ ] Streaming support
+- [ ] Custom model matrix (bring your own models)
+- [ ] Automatic provider failover
+- [ ] Usage analytics dashboard integration
+- [ ] Browser extension
+
+---
+
+## License
+
+MIT · Built by [Gabriel Martin](https://github.com/gabrielsmartin)
+
+*"Every model has a gravitational pull. ORBIT decides which one you need."*
+
+777 · 555 · 333

package/index.js

@@ -1,167 +1,14 @@
 /**
- * orbit-ai · v0.3.0
- * Intelligent AI model routing with signal-aware priority bias.
- * Drop in. Save 85%.
- * 
- * https://orbitai.gtll.app
- * github.com/gtllco/orbit
- * npm: @gabrielsmartin/orbit-sdk
+ * @gabrielsmartin/orbit-sdk
+ * Intelligent AI model routing — routes every query to the optimal model in <1ms
  * 
  * 777 · 555 · 333
+ * github.com/gtllco/orbit
  */
 
-import { fingerprint } from './fingerprint.js';
-import { route, calculateSavings, MODEL_MATRIX } from './router.js';
-import { applySignalBias, inferSignalFromEvent, formatSignalResponse, SIGNAL_DESCRIPTIONS } from './signal.js';
-
-export { fingerprint, route, calculateSavings, MODEL_MATRIX };
-export { applySignalBias, inferSignalFromEvent, formatSignalResponse, SIGNAL_DESCRIPTIONS };
-
-/**
- * OrbitClient — the main class
- * Now with signal-aware routing (777 · 555 · 333)
- * 
- * @example
- * import { OrbitClient } from '@gabrielsmartin/orbit-sdk'
- * const orbit = new OrbitClient()
- * 
- * // Without signal — standard 8-axis routing
- * const result = orbit.route("summarize this contract")
- * 
- * // With signal — priority-aware routing
- * const result = orbit.route("write the Q1 investor memo", { signal: "777" })
- * // → Claude Sonnet mandatory. This is final form.
- * 
- * const result = orbit.route("what's a business model nobody's tried?", { signal: "555" })
- * // → Grok or Claude Sonnet. Destabilize the expected.
- * 
- * const result = orbit.route("is this email spam?", { signal: "333" })
- * // → Gemini Flash. Strip cost. Foundation doesn't need premium.
- */
-export class OrbitClient {
-  constructor(config = {}) {
-    this.config = {
-      cost_tolerance: config.cost_tolerance || 'medium', // 'low' | 'medium' | 'high'
-      blocked_models: config.blocked_models || [],
-      api_key: config.apiKey || config.api_key || null,
-      log: config.log !== false,
-      on_route: config.on_route || null,
-      // Provider API keys (optional — falls back to env vars)
-      anthropic_key: config.anthropic_key || null,
-      openai_key: config.openai_key || null,
-      google_key: config.google_key || null,
-    };
-
-    this._stats = {
-      total_queries: 0,
-      total_savings: 0,
-      model_usage: {},
-      signal_usage: { '777': 0, '555': 0, '333': 0, none: 0 },
-    };
-  }
-
-  /**
-   * Route a query to the optimal model.
-   * Signal codes bias routing before model selection.
-   * 
-   * @param {string} text - The query text
-   * @param {Object} options - Override options for this query
-   * @param {string} [options.signal] - "777" | "555" | "333" | null
-   * @param {string} [options.cost_tolerance] - "low" | "medium" | "high"
-   * @param {number} [options.estimated_tokens] - Token estimate for cost calc
-   * @returns {Object} decision - { model, reason, rule, scores, savings, signal_applied, signal_reason, estimated_cost }
-   */
-  route(text, options = {}) {
-    // 1. Fingerprint
-    const rawScores = fingerprint(text);
-
-    // 2. Apply cost_tolerance override
-    if (options.cost_tolerance) {
-      rawScores.cost_tolerance = options.cost_tolerance === 'low' ? 2
-        : options.cost_tolerance === 'high' ? 9 : 5;
-    }
+export { fingerprint, route, calculateSavings, MODEL_MATRIX, OrbitClient } from './src/index.js';
 
-    // 3. Apply signal bias (777 / 555 / 333)
-    const signal = options.signal || null;
-    const scores = applySignalBias(rawScores, signal);
-
-    // 4. Route
-    const config = { ...this.config, ...options };
-    const decision = route(scores, config);
-
-    // 5. Calculate savings and cost
-    const estimatedTokens = options.estimated_tokens || 500;
-    const savings = calculateSavings(decision.model, estimatedTokens);
-    const estimatedCost = `$${savings.actualCost.toFixed(5)}`;
-
-    // 6. Format signal metadata
-    const signalMeta = formatSignalResponse(scores, decision);
-
-    const result = {
-      model: decision.model,
-      reason: decision.reason,
-      rule: decision.rule,
-      scores: rawScores, // return original scores, not biased
-      signal_applied: signalMeta.signal_applied,
-      signal_reason: signalMeta.signal_reason || null,
-      savings,
-      estimated_cost: estimatedCost,
-      timestamp: new Date().toISOString(),
-    };
-
-    // Update stats
-    this._stats.total_queries++;
-    this._stats.total_savings += savings.savings;
-    const modelName = decision.model.name;
-    this._stats.model_usage[modelName] = (this._stats.model_usage[modelName] || 0) + 1;
-    this._stats.signal_usage[signal || 'none']++;
-
-    // Log routing decision
-    if (this.config.log) {
-      const signalTag = signal ? ` [signal:${signal}]` : '';
-      console.log(`[ORBIT]${signalTag} → ${decision.model.name} | ${decision.rule} | ${estimatedCost} (saved ${savings.reductionPct}%)`);
-    }
-
-    if (this.config.on_route) this.config.on_route(result);
-    return result;
-  }
-
-  /**
-   * Get cumulative stats for this session — including per-signal breakdown
-   */
-  stats() {
-    return {
-      ...this._stats,
-      total_savings_formatted: `$${this._stats.total_savings.toFixed(4)}`,
-    };
-  }
-
-  /**
-   * Fingerprint a query without routing
-   */
-  fingerprint(text) {
-    return fingerprint(text);
-  }
-
-  /**
-   * Apply signal bias to an existing fingerprint
-   * Useful for building custom routing logic on top of ORBIT
-   */
-  applySignal(fingerprint, signal_code) {
-    return applySignalBias(fingerprint, signal_code);
-  }
-
-  /**
-   * Infer signal from a neural hub event priority
-   * coral1 events tagged 777/555/333 auto-translate to signal codes
-   */
-  signalFromEvent(eventPriority) {
-    return inferSignalFromEvent(eventPriority);
-  }
-}
-
-/**
- * Default singleton client
- */
+// Default export — zero-config instance
+import { OrbitClient } from './src/index.js';
 const orbit = new OrbitClient();
 export default orbit;

package/package.json

@@ -1,22 +1,49 @@
 {
   "name": "@gabrielsmartin/orbit-sdk",
-  "version": "0.3.0",
-  "description": "Intelligent AI model routing with signal-aware priority bias. 777·555·333.",
+  "version": "0.3.2",
+  "description": "Intelligent AI model routing with signal layer. 85% cost savings. 777·555·333",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "routing",
+    "openai",
+    "anthropic",
+    "gemini",
+    "orbit",
+    "cost-optimization",
+    "model-routing"
+  ],
+  "author": "Gabriel Martin <admin@gtll.app>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gtllco/orbit"
+  },
+  "homepage": "https://orbit-sdk.base44.app",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "module": "index.js",
   "type": "module",
-  "main": "./index.js",
-  "module": "./index.js",
   "exports": {
     ".": {
       "import": "./index.js",
-      "default": "./index.js"
+      "types": "./index.d.ts"
     }
   },
-  "files": ["*.js", "index.d.ts"],
-  "keywords": ["ai", "routing", "llm", "orbit", "model-selection", "anthropic", "openai", "gemini"],
-  "author": "Gabriel Martin",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/gtllco/orbit.git"
+  "engines": {
+    "node": ">=18.0.0"
   }
 }

package/src/index.js

@@ -0,0 +1,167 @@
+/**
+ * orbit-ai · v0.3.0
+ * Intelligent AI model routing with signal-aware priority bias.
+ * Drop in. Save 85%.
+ * 
+ * https://orbitai.gtll.app
+ * github.com/gtllco/orbit
+ * npm: @gabrielsmartin/orbit-sdk
+ * 
+ * 777 · 555 · 333
+ */
+
+import { fingerprint } from './fingerprint.js';
+import { route, calculateSavings, MODEL_MATRIX } from './router.js';
+import { applySignalBias, inferSignalFromEvent, formatSignalResponse, SIGNAL_DESCRIPTIONS } from './signal.js';
+
+export { fingerprint, route, calculateSavings, MODEL_MATRIX };
+export { applySignalBias, inferSignalFromEvent, formatSignalResponse, SIGNAL_DESCRIPTIONS };
+
+/**
+ * OrbitClient — the main class
+ * Now with signal-aware routing (777 · 555 · 333)
+ * 
+ * @example
+ * import { OrbitClient } from '@gabrielsmartin/orbit-sdk'
+ * const orbit = new OrbitClient()
+ * 
+ * // Without signal — standard 8-axis routing
+ * const result = orbit.route("summarize this contract")
+ * 
+ * // With signal — priority-aware routing
+ * const result = orbit.route("write the Q1 investor memo", { signal: "777" })
+ * // → Claude Sonnet mandatory. This is final form.
+ * 
+ * const result = orbit.route("what's a business model nobody's tried?", { signal: "555" })
+ * // → Grok or Claude Sonnet. Destabilize the expected.
+ * 
+ * const result = orbit.route("is this email spam?", { signal: "333" })
+ * // → Gemini Flash. Strip cost. Foundation doesn't need premium.
+ */
+export class OrbitClient {
+  constructor(config = {}) {
+    this.config = {
+      cost_tolerance: config.cost_tolerance || 'medium', // 'low' | 'medium' | 'high'
+      blocked_models: config.blocked_models || [],
+      api_key: config.apiKey || config.api_key || null,
+      log: config.log !== false,
+      on_route: config.on_route || null,
+      // Provider API keys (optional — falls back to env vars)
+      anthropic_key: config.anthropic_key || null,
+      openai_key: config.openai_key || null,
+      google_key: config.google_key || null,
+    };
+
+    this._stats = {
+      total_queries: 0,
+      total_savings: 0,
+      model_usage: {},
+      signal_usage: { '777': 0, '555': 0, '333': 0, none: 0 },
+    };
+  }
+
+  /**
+   * Route a query to the optimal model.
+   * Signal codes bias routing before model selection.
+   * 
+   * @param {string} text - The query text
+   * @param {Object} options - Override options for this query
+   * @param {string} [options.signal] - "777" | "555" | "333" | null
+   * @param {string} [options.cost_tolerance] - "low" | "medium" | "high"
+   * @param {number} [options.estimated_tokens] - Token estimate for cost calc
+   * @returns {Object} decision - { model, reason, rule, scores, savings, signal_applied, signal_reason, estimated_cost }
+   */
+  route(text, options = {}) {
+    // 1. Fingerprint
+    const rawScores = fingerprint(text);
+
+    // 2. Apply cost_tolerance override
+    if (options.cost_tolerance) {
+      rawScores.cost_tolerance = options.cost_tolerance === 'low' ? 2
+        : options.cost_tolerance === 'high' ? 9 : 5;
+    }
+
+    // 3. Apply signal bias (777 / 555 / 333)
+    const signal = options.signal || null;
+    const scores = applySignalBias(rawScores, signal);
+
+    // 4. Route
+    const config = { ...this.config, ...options };
+    const decision = route(scores, config);
+
+    // 5. Calculate savings and cost
+    const estimatedTokens = options.estimated_tokens || 500;
+    const savings = calculateSavings(decision.model, estimatedTokens);
+    const estimatedCost = `$${savings.actualCost.toFixed(5)}`;
+
+    // 6. Format signal metadata
+    const signalMeta = formatSignalResponse(scores, decision);
+
+    const result = {
+      model: decision.model,
+      reason: decision.reason,
+      rule: decision.rule,
+      scores: rawScores, // return original scores, not biased
+      signal_applied: signalMeta.signal_applied,
+      signal_reason: signalMeta.signal_reason || null,
+      savings,
+      estimated_cost: estimatedCost,
+      timestamp: new Date().toISOString(),
+    };
+
+    // Update stats
+    this._stats.total_queries++;
+    this._stats.total_savings += savings.savings;
+    const modelName = decision.model.name;
+    this._stats.model_usage[modelName] = (this._stats.model_usage[modelName] || 0) + 1;
+    this._stats.signal_usage[signal || 'none']++;
+
+    // Log routing decision
+    if (this.config.log) {
+      const signalTag = signal ? ` [signal:${signal}]` : '';
+      console.log(`[ORBIT]${signalTag} → ${decision.model.name} | ${decision.rule} | ${estimatedCost} (saved ${savings.reductionPct}%)`);
+    }
+
+    if (this.config.on_route) this.config.on_route(result);
+    return result;
+  }
+
+  /**
+   * Get cumulative stats for this session — including per-signal breakdown
+   */
+  stats() {
+    return {
+      ...this._stats,
+      total_savings_formatted: `$${this._stats.total_savings.toFixed(4)}`,
+    };
+  }
+
+  /**
+   * Fingerprint a query without routing
+   */
+  fingerprint(text) {
+    return fingerprint(text);
+  }
+
+  /**
+   * Apply signal bias to an existing fingerprint
+   * Useful for building custom routing logic on top of ORBIT
+   */
+  applySignal(fingerprint, signal_code) {
+    return applySignalBias(fingerprint, signal_code);
+  }
+
+  /**
+   * Infer signal from a neural hub event priority
+   * coral1 events tagged 777/555/333 auto-translate to signal codes
+   */
+  signalFromEvent(eventPriority) {
+    return inferSignalFromEvent(eventPriority);
+  }
+}
+
+/**
+ * Default singleton client
+ */
+const orbit = new OrbitClient();
+export default orbit;

package/{router.js → src/router.js}

@@ -8,7 +8,7 @@
 
 export const MODEL_MATRIX = {
   claude_sonnet: {
-    id: 'claude-sonnet-4-5',
+    id: 'claude-sonnet-4-6',
     name: 'Claude Sonnet',
     provider: 'anthropic',
     costPer1M: 15,
@@ -17,7 +17,7 @@ export const MODEL_MATRIX = {
     tier: 'medium',
   },
   claude_haiku: {
-    id: 'claude-haiku-3-5',
+    id: 'claude-haiku-4-5',
     name: 'Claude Haiku',
     provider: 'anthropic',
     costPer1M: 1,

package/src/signalBias.js

@@ -0,0 +1,85 @@
+/**
+ * ORBIT Signal Layer — Semantic Intent Routing Bias
+ * 
+ * Signal codes are semantic flags that travel with a query and adjust the routing
+ * decision before model selection. They connect ORBIT to the organizational priority
+ * layer (the neural hub, event priorities, etc).
+ * 
+ * 777 · 555 · 333
+ */
+
+/**
+ * Apply signal-based routing bias to a fingerprint
+ * Modifies the fingerprint scores before model selection happens
+ * 
+ * @param {Object} fingerprint - 8-axis scores from orbitFingerprint()
+ * @param {string} signal - '777' | '555' | '333' | null
+ * @returns {Object} biased fingerprint
+ */
+export function applySignalBias(fingerprint, signal) {
+  if (!signal) return fingerprint;
+
+  const biased = { ...fingerprint };
+
+  if (signal === '777') {
+    // COMPLETION BIAS
+    // 777 = This output is final. Quality floor raised. Never cut corners.
+    // - Force high-capability model floor
+    // - Never route to sub-tier models (Flash, Mini, Haiku)
+    // - If complexity >= 5: Claude Sonnet mandatory
+    // - If complexity < 5: Claude Haiku minimum
+    // - If emotional_weight >= 7: Claude always (never change this)
+    
+    biased.cost_tolerance = Math.max(biased.cost_tolerance, 7);
+    biased.complexity = Math.max(biased.complexity, 5);
+    biased.signal_applied = '777';
+    biased.signal_reason = 'Completion bias — cost floor raised, quality mandatory';
+  }
+
+  if (signal === '555') {
+    // VARIATION BIAS
+    // 555 = This query is exploratory. Break the expected pattern. Surprise.
+    // - Introduce controlled model diversity
+    // - Prefer non-default choices
+    // - If creativity >= 5: weight variation higher
+    // - If recency >= 6: Perplexity-like model over Claude
+    // - If complexity >= 6: allow GPT-4o instead of Claude
+    
+    biased.creativity = Math.max(biased.creativity, 5);
+    biased.recency = Math.max(biased.recency, 4);
+    biased.variation_mode = true;
+    biased.signal_applied = '555';
+    biased.signal_reason = 'Variation bias — introduce model diversity, break the pattern';
+  }
+
+  if (signal === '333') {
+    // FOUNDATION BIAS
+    // 333 = This is ambient/background. Strip to minimum. Cost floor.
+    // - Aggressively route to minimum viable model
+    // - If emotional_weight < 7: force cost_tolerance to 1 (ignore user config)
+    // - If complexity > 5: cap it at 4 (don't overpay)
+    // - Exception: emotional_weight >= 7 ALWAYS upgrades to Claude
+    //   (never route crisis/sensitive to cheap models, even on 333)
+    
+    if (biased.emotional_weight < 7) {
+      biased.cost_tolerance = 1; // force minimum cost
+      biased.complexity = Math.min(biased.complexity, 4); // cap complexity
+    }
+    biased.signal_applied = '333';
+    biased.signal_reason = 'Foundation bias — cost floor, ambient routing';
+  }
+
+  return biased;
+}
+
+/**
+ * Create signal explanation for response
+ */
+export function getSignalExplanation(signal) {
+  const explanations = {
+    '777': 'Completion bias applied — cost floor raised, complexity floor raised. Routed to highest-capability model.',
+    '555': 'Variation bias applied — model diversity prioritized. Unexpected routing choice for exploratory output.',
+    '333': 'Foundation bias applied — cost floor enforced. Minimum viable model selected for ambient routing.',
+  };
+  return explanations[signal] || null;
+}