@gabrielsmartin/orbit-sdk 0.2.0 → 0.2.1

package/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * orbit-ai · TypeScript definitions
+ * 777 · 555 · 333
+ */
+
+export interface QueryScores {
+  complexity: number;        // 0-10
+  creativity: number;        // 0-10
+  speed: number;             // 0-10
+  cost_tolerance: number;    // 0-10
+  emotional_weight: number;  // 0-10
+  recency: number;           // 0-10
+  context_load: number;      // 0-10
+  domain: 'general' | 'code' | 'creative' | 'current_events' | 'emotional' | 'legal' | 'medical' | 'research';
+}
+
+export interface ModelInfo {
+  id: string;
+  name: string;
+  provider: 'anthropic' | 'openai' | 'google' | 'xai' | 'meta';
+  costPer1M: number;
+  strengths: string[];
+  maxContext: number;
+  tier: 'very_low' | 'low' | 'medium' | 'high';
+}
+
+export interface SavingsInfo {
+  premiumCost: number;
+  actualCost: number;
+  savings: number;
+  reductionPct: number;
+}
+
+export interface RoutingDecision {
+  model: ModelInfo;
+  reason: string;
+  rule: string;
+  scores: QueryScores;
+  savings: SavingsInfo;
+  timestamp: string;
+}
+
+export interface OrbitConfig {
+  apiKey?: string;
+  cost_tolerance?: 'low' | 'medium' | 'high';
+  blocked_models?: string[];
+  log?: boolean;
+  on_route?: (decision: RoutingDecision) => void;
+  anthropic_key?: string;
+  openai_key?: string;
+  google_key?: string;
+}
+
+export interface RouteOptions {
+  cost_tolerance?: 'low' | 'medium' | 'high';
+  estimated_tokens?: number;
+  blocked_models?: string[];
+}
+
+export interface SessionStats {
+  total_queries: number;
+  total_savings: number;
+  total_savings_formatted: string;
+  model_usage: Record<string, number>;
+}
+
+export declare class OrbitClient {
+  constructor(config?: OrbitConfig);
+  route(text: string, options?: RouteOptions): RoutingDecision;
+  fingerprint(text: string): QueryScores;
+  stats(): SessionStats;
+}
+
+export declare function fingerprint(text: string): QueryScores;
+export declare function route(scores: QueryScores, config?: OrbitConfig): { model: ModelInfo; reason: string; rule: string };
+export declare function calculateSavings(model: ModelInfo, estimatedTokens?: number): SavingsInfo;
+export declare const MODEL_MATRIX: Record<string, ModelInfo>;
+
+declare const orbit: OrbitClient;
+export default orbit;

package/index.js

@@ -1,139 +1,14 @@
 /**
- * orbit-ai SDK v0.1.0
- * Drop-in replacement for OpenAI / Anthropic SDK calls
- * Routes every query to the optimal model via ORBIT SMM engine
- *
- * Usage:
- *   import { orbit } from 'orbit-ai'
- *   const res = await orbit.query("your query here")
- *
- * ORBIT Technologies · orbit-model-flow.base44.app
- * 777 · 333
+ * @gabrielsmartin/orbit-sdk
+ * Intelligent AI model routing — routes every query to the optimal model in <1ms
+ * 
+ * 777 · 555 · 333
+ * github.com/gtllco/orbit
  */
 
-const ORBIT_API = "https://orbit-model-flow.base44.app/api/functions/routeQuery";
+export { fingerprint, route, calculateSavings, MODEL_MATRIX, OrbitClient } from './src/index.js';
 
-class OrbitClient {
-  constructor(config = {}) {
-    this.apiKey = config.apiKey || process.env.ORBIT_API_KEY;
-    this.costTolerance = config.costTolerance || "low";
-    this.verbose = config.verbose || false;
-  }
-
-  /**
-   * Route a query to the optimal model
-   * @param {string} queryText - The query to route
-   * @param {object} options - Optional overrides
-   * @returns {OrbitResponse}
-   */
-  async query(queryText, options = {}) {
-    const fp = this._fingerprint(queryText);
-    const { model, reasoning } = options.model
-      ? { model: options.model, reasoning: "Manual override" }
-      : this._route(fp);
-
-    if (this.verbose) {
-      console.log(`[ORBIT] Fingerprint:`, fp);
-      console.log(`[ORBIT] Selected: ${model} — ${reasoning}`);
-    }
-
-    return {
-      model,
-      reasoning,
-      fingerprint: fp,
-      estimated_cost: this._estimateCost(model, queryText.length),
-      premium_cost: this._estimateCost("gpt4o", queryText.length),
-      get savings() { return Math.max(0, this.premium_cost - this.estimated_cost); },
-    };
-  }
-
-  /**
-   * Drop-in OpenAI compatibility
-   * orbit.openai.chat.completions.create({ model: "gpt-4o", messages })
-   * → routes to optimal model, returns same response shape
-   */
-  get openai() {
-    return {
-      chat: {
-        completions: {
-          create: async (params) => {
-            const queryText = params.messages?.map(m => m.content).join(" ") || "";
-            const routing = await this.query(queryText, { costTolerance: params._orbitCostTolerance });
-            // In production: actually call the selected model here
-            return { ...routing, choices: [], _orbit_routed: true };
-          }
-        }
-      }
-    };
-  }
-
-  /** 8-axis query fingerprinting */
-  _fingerprint(text) {
-    const t = text.toLowerCase();
-    const words = t.split(/\s+/).length;
-
-    const complexity = Math.min(10, Math.round(
-      (t.match(/\b(architect|distributed|implement|design|optimize|analyze|complex|system|algorithm|concurrent|scale)\b/g)?.length || 0) * 2 +
-      (words > 20 ? 3 : words > 10 ? 1.5 : 0) +
-      (t.match(/\b(why|how|explain|compare|tradeoff)\b/g)?.length || 0) * 1.5
-    ));
-    const creativity = Math.min(10, Math.round(
-      (t.match(/\b(write|create|generate|poem|story|haiku|imagine|creative|brainstorm)\b/g)?.length || 0) * 2.5
-    ));
-    const recency = Math.min(10, Math.round(
-      (t.match(/\b(latest|current|today|news|trending|recent|now|live)\b/g)?.length || 0) * 3
-    ));
-    const emotional_weight = Math.min(10, Math.round(
-      (t.match(/\b(anxious|depressed|sad|crisis|suicide|hurt|lonely|overwhelmed|mental health)\b/g)?.length || 0) * 4 +
-      (t.match(/\b(help|struggling|hard|difficult|pain)\b/g)?.length || 0) * 1.5
-    ));
-    const context_load = Math.min(10, Math.round(
-      (words > 100 ? 9 : words > 50 ? 7 : words > 20 ? 4 : 1) +
-      (t.match(/\b(document|paper|report|summarize)\b/g)?.length || 0) * 2
-    ));
-    const speed = Math.min(10, Math.round(
-      (t.match(/\b(quick|fast|brief|short|simple|just|tldr)\b/g)?.length || 0) * 2.5 +
-      (complexity < 3 ? 3 : 0)
-    ));
-
-    let domain = "general";
-    if (t.match(/\b(code|function|algorithm|javascript|python|api|sql|bug|deploy)\b/)) domain = "code";
-    else if (t.match(/\b(poem|story|haiku|creative|write|lyrics|fiction)\b/)) domain = "creative";
-    else if (t.match(/\b(research|study|paper|science|analysis|data|statistics)\b/)) domain = "research";
-    else if (t.match(/\b(legal|law|contract|liability|compliance)\b/)) domain = "legal";
-    else if (t.match(/\b(medical|health|diagnosis|symptoms|treatment|clinical)\b/)) domain = "medical";
-
-    const cost_tolerance = (complexity > 7 || domain === "legal" || domain === "medical")
-      ? "flexible" : this.costTolerance;
-
-    return { complexity, creativity, speed, recency, emotional_weight, context_load, domain, cost_tolerance };
-  }
-
-  /** SMM routing engine */
-  _route(fp) {
-    const { complexity, creativity, recency, emotional_weight, context_load, speed, domain, cost_tolerance } = fp;
-    if (emotional_weight > 6) return { model: "claude_sonnet", reasoning: "Emotional weight detected — Claude for ethics-first handling." };
-    if (domain === "legal" || domain === "medical") return { model: "claude_sonnet", reasoning: `Domain=${domain} — ethics-first.` };
-    if (context_load > 8) return { model: "claude_sonnet", reasoning: "High context load — Claude 200k window." };
-    if (complexity > 7 && domain === "code") return { model: "gpt4o", reasoning: "High complexity code — GPT-4o structured output." };
-    if (complexity > 8) return { model: "claude_sonnet", reasoning: "Extreme complexity — Claude Sonnet." };
-    if (recency > 7) return { model: "grok", reasoning: "High recency — Grok real-time web." };
-    if (recency > 5) return { model: "perplexity", reasoning: "Recency-sensitive — Perplexity cited search." };
-    if (creativity > 7) return { model: "claude_sonnet", reasoning: "High creativity — Claude Sonnet." };
-    if (speed > 7 && complexity < 5) return { model: "gemini_flash", reasoning: "Speed priority — Gemini Flash <200ms." };
-    if (cost_tolerance === "low" && complexity < 5) return { model: "gemini_flash", reasoning: "Low cost + simple — Gemini Flash $0.50/1M." };
-    if (complexity < 3 && creativity < 3) return { model: "gpt4o_mini", reasoning: "Trivial query — GPT-4o Mini." };
-    if (complexity < 5 && speed > 5) return { model: "claude_haiku", reasoning: "Moderate complexity + speed — Claude Haiku." };
-    return { model: "claude_sonnet", reasoning: "Multi-dimensional — Claude Sonnet default." };
-  }
-
-  _estimateCost(model, textLength) {
-    const COSTS = { claude_sonnet: 15, claude_haiku: 1, gemini_flash: 0.5, gpt4o: 30, gpt4o_mini: 0.3, grok: 10, perplexity: 5, llama3: 0.1 };
-    const tokens = Math.round(textLength / 4) + 150;
-    return (tokens / 1_000_000) * (COSTS[model] || 15);
-  }
-}
-
-export const orbit = new OrbitClient();
-export { OrbitClient };
+// Default export — zero-config instance
+import { OrbitClient } from './src/index.js';
+const orbit = new OrbitClient();
 export default orbit;

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@gabrielsmartin/orbit-sdk",
-  "version": "0.2.0",
-  "description": "Intelligent AI model routing. Drop-in replacement for OpenAI/Anthropic SDKs. Routes every query to the optimal model automatically.",
+  "version": "0.2.1",
+  "description": "Intelligent AI model routing with signal layer. 85% cost savings. 777\u00b7555\u00b7333",
   "main": "index.js",
   "types": "index.d.ts",
   "files": [
     "index.js",
     "index.d.ts",
-    "fingerprint.js",
-    "router.js",
+    "src/",
     "README.md"
   ],
   "scripts": {
@@ -25,7 +24,7 @@
     "cost-optimization",
     "model-routing"
   ],
-  "author": "Gabriel Martin <gabriel@gtll.app>",
+  "author": "Gabriel Martin <admin@gtll.app>",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -35,5 +34,16 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
+  },
+  "module": "index.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "types": "./index.d.ts"
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
   }
 }

package/src/fingerprint.js

@@ -0,0 +1,102 @@
+/**
+ * ORBIT · 8-Axis Query Fingerprinting Engine
+ * Scores every query across 8 dimensions in <1ms
+ * 
+ * interval(n) = base / 2^n — Recursive Beat Engine
+ * 777 · 555 · 333
+ */
+
+const COMPLEXITY_SIGNALS = [
+  'architect','distributed','implement','design','optimize','analyze',
+  'complex','system','algorithm','concurrent','scale','infrastructure',
+  'microservice','kubernetes','terraform','recursive','refactor'
+];
+
+const CREATIVITY_SIGNALS = [
+  'write','create','generate','poem','story','haiku','imagine',
+  'creative','brainstorm','ideas','invent','compose','design','narrative'
+];
+
+const RECENCY_SIGNALS = [
+  'latest','today','current','news','now','recent','trending',
+  '2024','2025','2026','live','breaking','update','this week'
+];
+
+const EMOTIONAL_SIGNALS = [
+  'feel','feeling','anxious','anxiety','depressed','depression','overwhelmed',
+  'scared','lonely','hurt','grief','trauma','crisis','suicid','help me',
+  'relationship','breakup','divorce','mental health','therapy','struggling'
+];
+
+const CODE_SIGNALS = [
+  'code','function','class','api','debug','error','syntax','compile',
+  'deploy','database','query','algorithm','javascript','python','typescript',
+  'react','node','sql','git','docker','bug','fix','implement'
+];
+
+/**
+ * Fingerprint a query across 8 axes
+ * @param {string} text - The query text
+ * @returns {Object} scores - 0-10 score for each axis
+ */
+export function fingerprint(text) {
+  const t = text.toLowerCase();
+  const words = t.split(/\s+/);
+  const wordCount = words.length;
+
+  // Complexity (0-10): reasoning depth required
+  const complexitySignals = COMPLEXITY_SIGNALS.filter(s => t.includes(s)).length;
+  const questionDepth = (t.match(/\b(why|how|explain|compare|tradeoff|pros|cons|difference|analyze)\b/g) || []).length;
+  const complexity = Math.min(10, Math.round(
+    complexitySignals * 2 +
+    questionDepth * 1.5 +
+    (wordCount > 30 ? 3 : wordCount > 15 ? 1.5 : 0)
+  ));
+
+  // Creativity (0-10): open-ended vs deterministic
+  const creativitySignals = CREATIVITY_SIGNALS.filter(s => t.includes(s)).length;
+  const creativity = Math.min(10, Math.round(creativitySignals * 2.5));
+
+  // Speed (0-10): latency sensitivity
+  const speedSignals = (t.match(/\b(quick|fast|brief|tldr|short|simple|summarize|quickly)\b/g) || []).length;
+  const speed = Math.min(10, Math.round(speedSignals * 3 + (wordCount < 8 ? 3 : 0)));
+
+  // Cost tolerance (0-10): inferred from query type (overridable)
+  // Default: medium. Will be set by user config.
+  const costTolerance = 5;
+
+  // Emotional weight (0-10): sensitivity of content
+  const emotionalSignals = EMOTIONAL_SIGNALS.filter(s => t.includes(s)).length;
+  const emotional_weight = Math.min(10, Math.round(emotionalSignals * 3));
+
+  // Recency (0-10): need for live/current data
+  const recencySignals = RECENCY_SIGNALS.filter(s => t.includes(s)).length;
+  const recency = Math.min(10, Math.round(recencySignals * 3.5));
+
+  // Context load (0-10): context window size needed
+  const context_load = Math.min(10, Math.round(
+    (wordCount > 100 ? 8 : wordCount > 50 ? 5 : wordCount > 20 ? 3 : 1)
+  ));
+
+  // Domain classification
+  const codeSignals = CODE_SIGNALS.filter(s => t.includes(s)).length;
+  let domain = 'general';
+  if (codeSignals >= 2) domain = 'code';
+  else if (creativity >= 6) domain = 'creative';
+  else if (recency >= 6) domain = 'current_events';
+  else if (emotional_weight >= 5) domain = 'emotional';
+  else if (t.match(/\b(legal|law|contract|lawsuit|rights|regulation)\b/)) domain = 'legal';
+  else if (t.match(/\b(medical|doctor|symptom|diagnosis|health|drug|medicine)\b/)) domain = 'medical';
+  else if (t.match(/\b(research|study|paper|academic|journal|cite|evidence)\b/)) domain = 'research';
+
+  return {
+    complexity,
+    creativity,
+    speed,
+    cost_tolerance: costTolerance,
+    emotional_weight,
+    recency,
+    context_load,
+    domain,
+  };
+}

package/src/index.js

@@ -0,0 +1,136 @@
+/**
+ * orbit-ai · v0.2.0
+ * Intelligent AI model routing with signal layer. Drop in. Save 85%.
+ * 
+ * https://orbit-model-flow.base44.app
+ * github.com/gabrielsmartin/orbit
+ * 
+ * 777 · 555 · 333
+ */
+
+import { fingerprint } from './fingerprint.js';
+import { route, calculateSavings, MODEL_MATRIX } from './router.js';
+
+export { fingerprint, route, calculateSavings, MODEL_MATRIX };
+
+/**
+ * OrbitClient — the main class
+ * 
+ * @example
+ * import { OrbitClient } from 'orbit-ai'
+ * const orbit = new OrbitClient({ apiKey: 'your-orbit-key' })
+ * const result = await orbit.query("explain quantum entanglement simply")
+ * 
+ * // With signal
+ * const result = await orbit.query("final investor memo", { signal: "777" })
+ */
+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, // log routing decisions by default
+      on_route: config.on_route || null, // callback: (decision) => void
+      // 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, null: 0 },
+    };
+  }
+
+  /**
+   * Route a query to the optimal model with optional signal bias
+   * Returns the routing decision — you call the model yourself with your keys
+   * 
+   * @param {string} text - The query text
+   * @param {Object} options - Override options for this query
+   * @param {string} options.signal - Optional semantic intent flag ('777' | '555' | '333')
+   * @returns {Object} decision - { model, reason, rule, scores, signal_applied, signal_reason, savings }
+   */
+  route(text, options = {}) {
+    const scores = fingerprint(text);
+    const signal = options.signal || null;
+
+    // Allow per-query cost_tolerance override
+    if (options.cost_tolerance) {
+      scores.cost_tolerance = options.cost_tolerance === 'low' ? 2
+        : options.cost_tolerance === 'high' ? 9 : 5;
+    }
+
+    const config = { ...this.config, ...options };
+    const decision = route(scores, signal, config);
+    const savings = calculateSavings(decision.model, options.estimated_tokens || 500);
+
+    const result = {
+      model: decision.model,
+      reason: decision.reason,
+      rule: decision.rule,
+      signal_applied: decision.signal_applied,
+      signal_reason: decision.signal_reason,
+      scores,
+      savings,
+      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 || 'null']++;
+
+    // Log routing decision
+    if (this.config.log) {
+      const signalStr = signal ? ` [signal: ${signal}]` : '';
+      console.log(`[ORBIT] → ${decision.model.name} | ${decision.rule}${signalStr} | saved $${savings.savings.toFixed(5)} (${savings.reductionPct}% reduction)`);
+    }
+
+    // Fire callback
+    if (this.config.on_route) {
+      this.config.on_route(result);
+    }
+
+    return result;
+  }
+
+  /**
+   * Get cumulative stats for this session
+   */
+  stats() {
+    return {
+      ...this._stats,
+      total_savings_formatted: `$${this._stats.total_savings.toFixed(4)}`,
+    };
+  }
+
+  /**
+   * Fingerprint a query without routing
+   * Useful for debugging or building custom routing logic on top
+   */
+  fingerprint(text) {
+    return fingerprint(text);
+  }
+}
+
+/**
+ * Default singleton client — zero config, ready to use
+ * 
+ * @example
+ * import orbit from 'orbit-ai'
+ * const decision = orbit.route("write a haiku about recursion")
+ * // → { model: { name: 'Claude Sonnet', ... }, reason: '...', savings: { ... } }
+ * 
+ * // With signal
+ * const decision = orbit.route("final investor memo", { signal: "777" })
+ * // → { model: { name: 'Claude Sonnet', ... }, signal_applied: '777', signal_reason: '...', ... }
+ */
+const orbit = new OrbitClient();
+export default orbit;

package/src/router.js

@@ -0,0 +1,221 @@
+/**
+ * ORBIT · Selective Model Matching (SMM) Router
+ * Routes queries to optimal models based on 8-axis fingerprints + signal codes
+ * 
+ * Proprietary routing logic — open SDK, closed engine weights
+ * 777 · 555 · 333
+ */
+
+export const MODEL_MATRIX = {
+  claude_sonnet: {
+    id: 'claude-sonnet-4-5',
+    name: 'Claude Sonnet',
+    provider: 'anthropic',
+    costPer1M: 15,
+    strengths: ['nuance', 'long_context', 'ethics', 'reasoning'],
+    maxContext: 200000,
+    tier: 'medium',
+  },
+  claude_haiku: {
+    id: 'claude-haiku-3-5',
+    name: 'Claude Haiku',
+    provider: 'anthropic',
+    costPer1M: 1,
+    strengths: ['speed', 'efficiency', 'summaries'],
+    maxContext: 200000,
+    tier: 'low',
+  },
+  gemini_flash: {
+    id: 'gemini-2.5-flash',
+    name: 'Gemini 2.5 Flash',
+    provider: 'google',
+    costPer1M: 0.5,
+    strengths: ['speed', 'multimodal', 'cost', 'volume'],
+    maxContext: 1000000,
+    tier: 'very_low',
+  },
+  gpt4o: {
+    id: 'gpt-4o',
+    name: 'GPT-4o',
+    provider: 'openai',
+    costPer1M: 30,
+    strengths: ['broad_knowledge', 'instruction_following', 'structured_output'],
+    maxContext: 128000,
+    tier: 'high',
+  },
+  gpt4o_mini: {
+    id: 'gpt-4o-mini',
+    name: 'GPT-4o Mini',
+    provider: 'openai',
+    costPer1M: 0.3,
+    strengths: ['classification', 'simple_tasks', 'cost'],
+    maxContext: 128000,
+    tier: 'very_low',
+  },
+  grok: {
+    id: 'grok-2',
+    name: 'Grok',
+    provider: 'xai',
+    costPer1M: 10,
+    strengths: ['realtime_web', 'trending', 'social_intelligence'],
+    maxContext: 131072,
+    tier: 'medium',
+  },
+};
+
+/**
+ * Core SMM routing logic — Signal-aware
+ * Returns the selected model + reasoning
+ * 
+ * @param {Object} scores - 8-axis fingerprint scores (post-signal-bias)
+ * @param {Object} config - User config (cost_tolerance override, blocked_models, etc.)
+ * @returns {Object} { model, reason, fallback }
+ */
+export function route(scores, config = {}) {
+  const {
+    complexity, creativity, speed, emotional_weight,
+    recency, context_load, domain, cost_tolerance,
+    signal_code, variation_mode
+  } = scores;
+
+  const blocked = config.blocked_models || [];
+  const preferLow = cost_tolerance <= 3;
+  const preferHigh = cost_tolerance >= 8;
+
+  // ── SIGNAL OVERRIDES (applied before all other rules) ──────────────────────
+
+  // 777 — Completion Bias: cost_tolerance and complexity already raised by applySignalBias.
+  // But explicitly block sub-tier models when signal=777.
+  if (signal_code === '777') {
+    // Minimum floor: Claude Haiku. Prefer Sonnet if complexity >= 5.
+    if (complexity >= 5 && !blocked.includes('claude_sonnet')) {
+      return {
+        model: MODEL_MATRIX.claude_sonnet,
+        reason: `Completion bias (777) — complexity ${complexity}/10 meets threshold. Claude Sonnet mandatory. This output is final form.`,
+        rule: 'signal_777_sonnet',
+      };
+    }
+    // complexity < 5 but still 777: Claude Haiku minimum, no Gemini Flash/GPT-4o Mini
+    if (!blocked.includes('claude_haiku')) {
+      return {
+        model: MODEL_MATRIX.claude_haiku,
+        reason: `Completion bias (777) — complexity ${complexity}/10 below Sonnet threshold but 777 enforces Claude Haiku minimum. No sub-tier models on completion events.`,
+        rule: 'signal_777_haiku',
+      };
+    }
+  }
+
+  // 555 — Variation Bias: variation_mode=true, creativity and recency already boosted.
+  // Prefer Grok when recency is elevated. Otherwise prefer creative non-default models.
+  if (signal_code === '555') {
+    if (recency >= 5 && !blocked.includes('grok')) {
+      return {
+        model: MODEL_MATRIX.grok,
+        reason: `Variation bias (555) — recency boosted to ${recency}/10. Grok for live web intelligence and unexpected angles. Destabilize the expected.`,
+        rule: 'signal_555_grok',
+      };
+    }
+    if (creativity >= 6 && !blocked.includes('claude_sonnet')) {
+      return {
+        model: MODEL_MATRIX.claude_sonnet,
+        reason: `Variation bias (555) — creativity at ${creativity}/10. Claude Sonnet for nuanced, surprising creative output.`,
+        rule: 'signal_555_claude',
+      };
+    }
+  }
+
+  // 333 — Foundation Bias: cost_tolerance dropped to 1 by applySignalBias (unless emotional override).
+  // Emotional safety net is handled by ethics rule below — it fires first.
+
+  // ── CORE ROUTING RULES ─────────────────────────────────────────────────────
+
+  // Rule 1: ETHICS FIRST — emotional/crisis queries always go to Claude (even on 333)
+  if (emotional_weight >= 6) {
+    return {
+      model: MODEL_MATRIX.claude_sonnet,
+      reason: `Emotional weight ${emotional_weight}/10 — routing to Claude for ethics-first handling. Never use a cheap model for sensitive content.${signal_code === '333' ? ' (333 foundation bias overridden by emotional safety rule)' : ''}`,
+      rule: 'ethics_first',
+    };
+  }
+
+  // Rule 2: Realtime / current events → Grok
+  if (recency >= 7 && !blocked.includes('grok') && signal_code !== '777') {
+    return {
+      model: MODEL_MATRIX.grok,
+      reason: `High recency score (${recency}/10) — Grok has live web access for current events and trending topics.`,
+      rule: 'recency_grok',
+    };
+  }
+
+  // Rule 3: Long context load → Claude Sonnet (200k window)
+  if (context_load >= 8 && !blocked.includes('claude_sonnet') && signal_code !== '333') {
+    return {
+      model: MODEL_MATRIX.claude_sonnet,
+      reason: `High context load (${context_load}/10) — Claude's 200k window is the only safe choice.`,
+      rule: 'context_claude',
+    };
+  }
+
+  // Rule 4: High complexity code/reasoning
+  if (complexity >= 7 && domain === 'code' && !blocked.includes('claude_sonnet')) {
+    return {
+      model: MODEL_MATRIX.claude_sonnet,
+      reason: `Complex code task (complexity ${complexity}/10) — Claude Sonnet for deep reasoning and long context.`,
+      rule: 'complex_code',
+    };
+  }
+
+  // Rule 5: High complexity general → GPT-4o (if cost tolerance allows and not 777/333)
+  if (complexity >= 7 && !preferLow && !blocked.includes('gpt4o') && signal_code !== '777' && signal_code !== '333') {
+    return {
+      model: MODEL_MATRIX.gpt4o,
+      reason: `High complexity (${complexity}/10) — GPT-4o for broad knowledge and structured output.`,
+      rule: 'complex_gpt4o',
+    };
+  }
+
+  // Rule 6: Creative writing → Claude Sonnet (unless 333 forcing minimum)
+  if (creativity >= 5 && !blocked.includes('claude_sonnet') && !preferLow) {
+    return {
+      model: MODEL_MATRIX.claude_sonnet,
+      reason: `High creativity score (${creativity}/10) — Claude Sonnet for nuanced creative writing.`,
+      rule: 'creative_claude',
+    };
+  }
+
+  // Rule 7: Cost sensitive OR simple queries OR 333 foundation → Gemini Flash
+  if ((preferLow || complexity <= 3) && !blocked.includes('gemini_flash')) {
+    return {
+      model: MODEL_MATRIX.gemini_flash,
+      reason: `${signal_code === '333' ? 'Foundation bias (333) — ' : ''}Low complexity (${complexity}/10) — Gemini 2.5 Flash delivers 95% quality at 2% of GPT-4o cost.`,
+      rule: 'cost_gemini',
+    };
+  }
+
+  // Rule 8: Medium complexity → Claude Haiku (fast + cheap + capable)
+  if (complexity <= 5 && !blocked.includes('claude_haiku')) {
+    return {
+      model: MODEL_MATRIX.claude_haiku,
+      reason: `Medium complexity (${complexity}/10) — Claude Haiku balances speed, cost, and quality.`,
+      rule: 'medium_haiku',
+    };
+  }
+
+  // Default: Claude Sonnet (safest general choice)
+  return {
+    model: MODEL_MATRIX.claude_sonnet,
+    reason: 'Default routing — Claude Sonnet for reliable, high-quality responses.',
+    rule: 'default',
+  };
+}
+
+/**
+ * Calculate savings vs always using GPT-4o (premium baseline)
+ */
+export function calculateSavings(selectedModel, estimatedTokens = 500) {
+  const premiumCost = (MODEL_MATRIX.gpt4o.costPer1M / 1_000_000) * estimatedTokens;
+  const actualCost = (selectedModel.costPer1M / 1_000_000) * estimatedTokens;
+  const savings = premiumCost - actualCost;
+  const reductionPct = Math.round((savings / premiumCost) * 100);
+  return { premiumCost, actualCost, savings, reductionPct };
+}

package/src/signal.js

@@ -0,0 +1,105 @@
+/**
+ * ORBIT · Signal Layer — Priority-Aware Routing Bias
+ * 
+ * Signal codes connect the routing layer to the agent network.
+ * A 777 event means something is landing — never cut corners.
+ * A 555 event means something is shifting — route to variation.
+ * A 333 event means ambient/background — route to minimum cost.
+ * 
+ * interval(n) = base / 2^n — Recursive Beat Engine
+ * 777 · 555 · 333
+ */
+
+/**
+ * Apply signal bias to a fingerprint before routing.
+ * Mutates a COPY of the fingerprint — never the original.
+ * 
+ * @param {Object} fingerprint - 8-axis fingerprint from fingerprint.js
+ * @param {string|null} signal_code - "777" | "555" | "333" | null
+ * @returns {Object} biased fingerprint + signal metadata
+ */
+export function applySignalBias(fingerprint, signal_code) {
+  // No signal = no change
+  if (!signal_code || !['777', '555', '333'].includes(signal_code)) {
+    return { ...fingerprint, signal_code: null, signal_applied: false };
+  }
+
+  const f = { ...fingerprint };
+
+  if (signal_code === '777') {
+    // Completion Bias — this output is final form. Never cut corners.
+    // Force quality floor: raise cost_tolerance and complexity minimums.
+    f.cost_tolerance = Math.max(f.cost_tolerance, 7);
+    f.complexity = Math.max(f.complexity, 6);
+    // Note: emotional_weight guard is handled in router — Claude always if emotional_weight >= 6 anyway
+    f.signal_code = '777';
+    f.signal_applied = true;
+    f.signal_reason = 'Completion bias — cost floor raised, complexity floor raised. Quality is non-negotiable on 777 events.';
+  }
+
+  if (signal_code === '555') {
+    // Variation Bias — something is shifting. Route to surprise.
+    // Boost creativity and recency to prefer Grok/Perplexity and non-default models.
+    f.creativity = Math.max(f.creativity, 6);
+    f.recency = Math.max(f.recency, 5);
+    f.variation_mode = true; // router reads this to prefer non-default choices
+    f.signal_code = '555';
+    f.signal_applied = true;
+    f.signal_reason = 'Variation bias — creativity and recency boosted. Routing to destabilize the expected.';
+  }
+
+  if (signal_code === '333') {
+    // Foundation Bias — ambient/background. Strip cost aggressively.
+    // Exception: emotional_weight >= 7 always upgrades (crisis never gets a cheap model).
+    if (f.emotional_weight < 7) {
+      f.cost_tolerance = 1; // force minimum cost
+      f.complexity = Math.min(f.complexity, 4); // cap complexity perception
+      f.signal_code = '333';
+      f.signal_applied = true;
+      f.signal_reason = 'Foundation bias — cost floor dropped to minimum. Routing to cheapest capable model.';
+    } else {
+      // Emotional override — even on 333, safety first
+      f.signal_code = '333';
+      f.signal_applied = true;
+      f.signal_reason = 'Foundation bias requested, but emotional_weight >= 7 — safety override active. Routing to Claude.';
+    }
+  }
+
+  return f;
+}
+
+/**
+ * Infer signal code from neural hub event priority.
+ * When coral1 fires an AgentEvent, the priority field maps directly to signal codes.
+ * This is how the neural hub auto-injects signal into ORBIT routing.
+ * 
+ * @param {string} eventPriority - "777" | "555" | "333" | "444"
+ * @returns {string|null} signal_code
+ */
+export function inferSignalFromEvent(eventPriority) {
+  const map = { '777': '777', '555': '555', '333': '333' };
+  return map[eventPriority] || null;
+}
+
+/**
+ * Format signal metadata for API responses.
+ * 
+ * @param {Object} biasedFingerprint - fingerprint after applySignalBias
+ * @param {Object} routingDecision - result from route()
+ * @returns {Object} signal metadata for API response
+ */
+export function formatSignalResponse(biasedFingerprint, routingDecision) {
+  if (!biasedFingerprint.signal_applied) {
+    return { signal_applied: null };
+  }
+  return {
+    signal_applied: biasedFingerprint.signal_code,
+    signal_reason: biasedFingerprint.signal_reason,
+  };
+}
+
+export const SIGNAL_DESCRIPTIONS = {
+  '777': 'Completion · Return · Alignment — This output is final form. Quality is mandatory.',
+  '555': 'Transformation · Breakthrough — This query is exploratory. Route to variation and surprise.',
+  '333': 'Foundation · Breath · Ground — This is ambient. Route to minimum cost. Strip everything.',
+};

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;
+}