@thispointon/kondi-chat 0.1.2

package/src/router/intent-router.ts

@@ -0,0 +1,225 @@
+/**
+ * Intent Router — LLM-based classification, the primary routing strategy.
+ *
+ * Reads every model's description and capabilities from the registry and
+ * asks a cheap LLM: "given these model descriptions, which one best matches
+ * this task?" This is the smartest tier — it handles any model, any capability,
+ * and adapts automatically when models are added or removed.
+ *
+ * Priority chain:
+ *   1. NN Router  — fast approximation of Intent (when trained)
+ *   2. Intent Router — primary, reads model descriptions (this file)
+ *   3. Rule Router — minimal phase/task-kind fallback
+ */
+
+import type { LedgerPhase, TaskKind, ProviderId } from '../types.ts';
+import { callLLM } from '../providers/llm-caller.ts';
+import type { ModelRegistry, ModelEntry } from './registry.ts';
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+export interface IntentRouterConfig {
+  /** Provider for the classification LLM (should be cheap/fast) */
+  provider: ProviderId;
+  model?: string;
+  /**
+   * Phases to run intent routing on. Defaults to *all* phases — the intent
+   * router is the primary tier, so we want it owning every decision it can.
+   */
+  phases?: LedgerPhase[];
+}
+
+const DEFAULT_CONFIG: IntentRouterConfig = {
+  provider: 'anthropic',
+  model: 'claude-haiku-4-5-20251001',
+  // `undefined` = all phases eligible.
+};
+
+/** Optional per-call overrides that come from the active budget profile. */
+export interface IntentRouterCallOptions {
+  /** If set, only consider models from these providers. */
+  allowedProviders?: ProviderId[];
+  /**
+   * If set, only consider these specific model IDs. Derived from the
+   * profile's rolePinning values so the classifier sees exactly the
+   * models the profile uses, not every model from the allowed providers.
+   * Takes precedence over allowedProviders when both are set.
+   */
+  allowedModelIds?: string[];
+  /** Override the classifier LLM for this call (e.g. zai's glm-4.5-flash). */
+  classifier?: { provider: ProviderId; model: string };
+  /** Rich context about what happened in prior pipeline phases. */
+  phaseContext?: import('../router/index.ts').PhaseContext;
+  /** The profile's preferred model for this phase (soft hint, not hard pin). */
+  phasePreference?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Intent Router
+// ---------------------------------------------------------------------------
+
+export class IntentRouter {
+  private config: IntentRouterConfig;
+
+  constructor(config?: Partial<IntentRouterConfig>) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Classify a prompt against available models and return the best match.
+   * Returns null if classification fails.
+   */
+  async classify(
+    promptText: string,
+    phase: LedgerPhase,
+    taskKind: TaskKind | undefined,
+    registry: ModelRegistry,
+    opts?: IntentRouterCallOptions,
+  ): Promise<{ model: ModelEntry; intent: string } | null> {
+    // Phase filter: if the caller restricted phases in config, honor it.
+    // Default (no config) = all phases.
+    if (this.config.phases && !this.config.phases.includes(phase)) {
+      return null;
+    }
+
+    // Candidate scope: specific model IDs (from rolePinning) > provider
+    // filter > all enabled. When the profile declares rolePinning, the
+    // classifier sees exactly those 4–5 models, not every model from 3
+    // providers. Much less noise, much better picks.
+    let enabled = registry.getEnabled();
+    if (opts?.allowedModelIds && opts.allowedModelIds.length > 0) {
+      const allow = new Set(opts.allowedModelIds);
+      enabled = enabled.filter(m => allow.has(m.id));
+    } else if (opts?.allowedProviders && opts.allowedProviders.length > 0) {
+      const allow = new Set(opts.allowedProviders);
+      enabled = enabled.filter(m => allow.has(m.provider));
+    }
+    if (enabled.length <= 1) {
+      // Trivial case: if there's only one candidate (or zero), skip the LLM
+      // call and let whatever's there be the answer — or defer to the next
+      // router tier. Returning null triggers the fallback chain.
+      return enabled.length === 1
+        ? { model: enabled[0], intent: 'only-candidate' }
+        : null;
+    }
+
+    // Build route descriptions from registry
+    const routes = enabled.map(m => ({
+      name: m.id,
+      description: this.describeModel(m),
+    }));
+
+    const routesXml = routes
+      .map(r => `  <route name="${r.name}">${r.description}</route>`)
+      .join('\n');
+
+    // Build phase-context block so the classifier knows what happened
+    // in prior pipeline steps, not just the original user prompt.
+    let contextBlock = '';
+    if (opts?.phaseContext?.priorPhases && opts.phaseContext.priorPhases.length > 0) {
+      const lines = opts.phaseContext.priorPhases.map(p =>
+        `  - ${p.phase}: handled by ${p.model}${p.succeeded === false ? ' (FAILED)' : ''}${p.summary ? ` — ${p.summary}` : ''}`
+      );
+      contextBlock = `\n<prior_phases>\n${lines.join('\n')}\n</prior_phases>\n`;
+    }
+
+    let preferenceHint = '';
+    if (opts?.phasePreference) {
+      preferenceHint = `\nThe user's profile suggests "${opts.phasePreference}" for the ${phase} phase. Honor this preference unless another model is clearly better suited given the context above.\n`;
+    }
+
+    const phaseDescriptions: Record<string, string> = {
+      discuss: 'Conversational Q&A, explanations, open-ended discussion. Needs good general reasoning at reasonable cost.',
+      dispatch: 'Planning and task decomposition. Needs strong architectural reasoning — this call sets the direction for everything that follows. Worth paying more for quality here.',
+      execute: 'Code generation, file editing, tool calls. High-volume phase (3-10 calls per turn). Cost matters. Speed matters. Code quality needs to be good but planning was already done.',
+      reflect: 'Reviewing and critiquing code that was just written. Needs to catch bugs without hallucinating new ones. Should NOT be the same model that wrote the code if possible.',
+      compress: 'Summarizing old context to save tokens. Grunt work. Use the cheapest model available.',
+      state_update: 'Updating session state. Grunt work. Use the cheapest model available.',
+      verify: 'Local verification (no LLM needed).',
+      consult: 'Domain-expert consultation. Use whatever model the consultant specifies.',
+    };
+
+    const phaseDesc = phaseDescriptions[phase] || `Phase: ${phase}`;
+
+    const prompt = `You are a router that selects the best model for the current step of a multi-phase coding pipeline.
+
+<routes>
+${routesXml}
+</routes>
+
+<current_step>
+Phase: ${phase}
+Phase meaning: ${phaseDesc}
+${taskKind ? `Task kind: ${taskKind}` : ''}
+Original goal: ${(opts?.phaseContext?.currentGoal || promptText).slice(0, 800)}
+</current_step>
+${contextBlock}${preferenceHint}
+Given the available models, the current phase, and what happened in prior phases, which model should handle this step? Consider: capabilities, cost, and whether the model that wrote the code should be different from the one that reviews it.
+Respond with ONLY a JSON object: {"route": "model_id"}`;
+
+    // Classifier model: per-call override (from active profile) > config default.
+    const classifierProvider = opts?.classifier?.provider ?? this.config.provider;
+    const classifierModel = opts?.classifier?.model ?? this.config.model;
+
+    try {
+      const response = await callLLM({
+        provider: classifierProvider,
+        model: classifierModel,
+        systemPrompt: 'You select the best model for a task. Respond with only JSON.',
+        userMessage: prompt,
+        maxOutputTokens: 50,
+        temperature: 0,
+      });
+
+      const parsed = this.parseResponse(response.content);
+      if (!parsed) return null;
+
+      const model = registry.getById(parsed);
+      // Also re-check it's inside the allowed set — the LLM could hallucinate
+      // a model name that wasn't in the input list.
+      if (!model || !model.enabled) return null;
+      if (opts?.allowedProviders && opts.allowedProviders.length > 0) {
+        if (!opts.allowedProviders.includes(model.provider)) return null;
+      }
+
+      process.stderr.write(`  │  intent-router: ${model.id} (via ${response.model})\n`);
+      return { model, intent: parsed };
+    } catch {
+      return null;
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Helpers
+  // -------------------------------------------------------------------------
+
+  /** Generate a natural language description of a model from its registry entry. */
+  private describeModel(m: ModelEntry): string {
+    const costTier = m.inputCostPer1M < 1 ? 'cheap' : m.inputCostPer1M < 5 ? 'mid-tier' : 'expensive';
+    return (
+      `${m.name} — ${costTier} model (${m.provider}). ` +
+      `Good at: ${m.capabilities.join(', ')}. ` +
+      `Context: ${(m.contextWindow / 1000).toFixed(0)}K tokens. ` +
+      `Cost: $${m.inputCostPer1M}/M input, $${m.outputCostPer1M}/M output.`
+    );
+  }
+
+  /** Parse the LLM's route selection from its response. */
+  private parseResponse(content: string): string | null {
+    try {
+      // Try JSON parse
+      const match = content.match(/\{[^}]*"route"\s*:\s*"([^"]+)"[^}]*\}/);
+      if (match) return match[1];
+
+      // Try plain text
+      const cleaned = content.trim().replace(/^["']|["']$/g, '');
+      if (cleaned && !cleaned.includes(' ')) return cleaned;
+
+      return null;
+    } catch {
+      return null;
+    }
+  }
+}

package/src/router/nn-router.ts

@@ -0,0 +1,205 @@
+/**
+ * NN Router — lightweight neural network for model selection.
+ *
+ * Trained by src/router/train.py from data collected by the rule-based
+ * router. At inference time, predicts which model will succeed for a
+ * given (phase, task_kind, prompt_length, context_tokens, failures).
+ *
+ * Falls back to the rule router when:
+ *   - No trained model exists
+ *   - Confidence is below threshold
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { LedgerPhase, TaskKind } from '../types.ts';
+import type { ModelRegistry, ModelEntry } from './registry.ts';
+import type { EmbeddingService } from './embeddings.ts';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface NNModelData {
+  nn: {
+    weights: number[][][];
+    biases: number[][];
+    layerDims: number[];
+  };
+  featureInfo: {
+    phases: string[];
+    taskKinds: string[];
+    featureNames: string[];
+    inputDim: number;
+    embeddingDim: number;
+    hasEmbeddings: boolean;
+  };
+  modelNames: string[];
+  metrics: Record<string, unknown>;
+  sampleCount: number;
+}
+
+// ---------------------------------------------------------------------------
+// Inference (pure math, no dependencies)
+// ---------------------------------------------------------------------------
+
+function relu(x: number[]): number[] {
+  return x.map(v => Math.max(0, v));
+}
+
+function sigmoid(x: number[]): number[] {
+  return x.map(v => 1 / (1 + Math.exp(-Math.max(-500, Math.min(500, v)))));
+}
+
+function matmul(input: number[], weights: number[][], bias: number[]): number[] {
+  const output = new Array(weights[0].length).fill(0);
+  for (let j = 0; j < output.length; j++) {
+    let sum = bias[j];
+    for (let i = 0; i < input.length; i++) {
+      sum += input[i] * weights[i][j];
+    }
+    output[j] = sum;
+  }
+  return output;
+}
+
+function predict(input: number[], weights: number[][][], biases: number[][]): number[] {
+  let x = input;
+  for (let layer = 0; layer < weights.length; layer++) {
+    x = matmul(x, weights[layer], biases[layer]);
+    if (layer < weights.length - 1) {
+      x = relu(x);
+    } else {
+      x = sigmoid(x);
+    }
+  }
+  return x;
+}
+
+// ---------------------------------------------------------------------------
+// NN Router
+// ---------------------------------------------------------------------------
+
+export class NNRouter {
+  private modelData: NNModelData | null = null;
+  private modelPath: string;
+  private confidenceThreshold: number;
+
+  constructor(storageDir: string, confidenceThreshold = 0.6) {
+    this.modelPath = join(storageDir, 'router-model.json');
+    this.confidenceThreshold = confidenceThreshold;
+    this.load();
+  }
+
+  /** Is a trained model available? */
+  isAvailable(): boolean {
+    return this.modelData !== null;
+  }
+
+  /** Reload model from disk (after retraining). */
+  reload(): void {
+    this.load();
+  }
+
+  /**
+   * Predict the best model for a given context.
+   * Returns null if no model is loaded or confidence is too low.
+   *
+   * @param embedding Optional pre-computed embedding from EmbeddingService.
+   *   If the model was trained with embeddings and none is provided,
+   *   a zero vector is used (degrades to structured-only features).
+   */
+  predict(
+    phase: LedgerPhase,
+    taskKind: TaskKind | undefined,
+    promptLength: number,
+    contextTokens: number,
+    failures: number,
+    registry: ModelRegistry,
+    embedding?: number[],
+  ): { model: ModelEntry; confidence: number; probabilities: Record<string, number> } | null {
+    if (!this.modelData) return null;
+
+    const features = this.encodeFeatures(phase, taskKind, promptLength, contextTokens, failures, embedding);
+    const probs = predict(features, this.modelData.nn.weights, this.modelData.nn.biases);
+
+    // Build probability map
+    const probabilities: Record<string, number> = {};
+    let bestIdx = 0;
+    let bestProb = 0;
+
+    for (let i = 0; i < this.modelData.modelNames.length; i++) {
+      const name = this.modelData.modelNames[i];
+      probabilities[name] = probs[i];
+      if (probs[i] > bestProb) {
+        bestProb = probs[i];
+        bestIdx = i;
+      }
+    }
+
+    // Check confidence threshold
+    if (bestProb < this.confidenceThreshold) return null;
+
+    // Find the model in the registry
+    const modelId = this.modelData.modelNames[bestIdx];
+    const model = registry.getById(modelId);
+    if (!model || !model.enabled) return null;
+
+    return { model, confidence: bestProb, probabilities };
+  }
+
+  // -------------------------------------------------------------------------
+  // Feature encoding
+  // -------------------------------------------------------------------------
+
+  private encodeFeatures(
+    phase: LedgerPhase,
+    taskKind: TaskKind | undefined,
+    promptLength: number,
+    contextTokens: number,
+    failures: number,
+    embedding?: number[],
+  ): number[] {
+    if (!this.modelData) return [];
+
+    const info = this.modelData.featureInfo;
+
+    // Structured features
+    const phaseVec = info.phases.map(p => p === phase ? 1 : 0);
+    const kindVec = info.taskKinds.map(k => k === (taskKind || 'none') ? 1 : 0);
+    const promptNorm = Math.min(promptLength / 10_000, 1);
+    const contextNorm = Math.min(contextTokens / 100_000, 1);
+    const failureNorm = Math.min(failures / 5, 1);
+    const structured = [...phaseVec, ...kindVec, promptNorm, contextNorm, failureNorm];
+
+    // Prepend embedding if the model was trained with them
+    if (info.hasEmbeddings && info.embeddingDim > 0) {
+      const emb = embedding || new Array(info.embeddingDim).fill(0);
+      // Pad or truncate to expected dimension
+      const padded = emb.length >= info.embeddingDim
+        ? emb.slice(0, info.embeddingDim)
+        : [...emb, ...new Array(info.embeddingDim - emb.length).fill(0)];
+      return [...padded, ...structured];
+    }
+
+    return structured;
+  }
+
+  // -------------------------------------------------------------------------
+  // Persistence
+  // -------------------------------------------------------------------------
+
+  private load(): void {
+    if (!existsSync(this.modelPath)) {
+      this.modelData = null;
+      return;
+    }
+
+    try {
+      const raw = readFileSync(this.modelPath, 'utf-8');
+      this.modelData = JSON.parse(raw);
+    } catch {
+      this.modelData = null;
+    }
+  }
+}