pi-smart-router 0.1.0

package/src/domain/matching/hydra-matcher.ts

@@ -0,0 +1,454 @@
+/**
+ * HyDRA embedding matcher — T048, FR-005.
+ *
+ * Embeds prompt text via ONNX (Xenova/all-MiniLM-L6-v2 384-dim),
+ * projects to requirement dimensions [reasoning, code_gen, tool_use],
+ * and scores fleet candidates with a shortfall gate.
+ *
+ * Shortfall gate (data-model §Validation): candidate excluded when
+ * any capability dimension shortfall > 0 (quality parity).
+ *
+ * Budget: 80–120 ms (configurable, default 100 ms).
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { z } from 'zod';
+
+import { DEFAULT_OPERATOR_CONFIG } from '../../config/defaults.js';
+import { buildHydraInput } from './hydra-input.js';
+import {
+  createOnnxTextEmbedder,
+  EMBEDDING_DIM,
+  type TextEmbedder,
+} from './embedding-provider.js';
+import {
+  scoreMultiObjective,
+  type FrugalityWeights,
+} from '../scoring/multi-objective.js';
+import type {
+  CandidateScore,
+  ModelCapabilities,
+  ModelProfile,
+  RoutingRequest,
+} from '../types/index.js';
+
+// ─── Requirement vector ──────────────────────────────────────────────────────
+
+export interface RequirementVector {
+  readonly reasoning: number;
+  readonly code_gen: number;
+  readonly tool_use: number;
+}
+
+// ─── Embedding provider port ─────────────────────────────────────────────────
+
+export interface EmbeddingProvider {
+  extractRequirements(text: string): Promise<RequirementVector>;
+  dispose(): Promise<void>;
+}
+
+// ─── Match result ────────────────────────────────────────────────────────────
+
+export interface MatchResult {
+  readonly selected: CandidateScore | null;
+  readonly candidates: readonly CandidateScore[];
+  readonly requirements: RequirementVector;
+  readonly elapsedMs: number;
+  readonly budgetExceeded: boolean;
+}
+
+// ─── Configuration ───────────────────────────────────────────────────────────
+
+export interface HydraMatcherConfig {
+  readonly artifactCachePath: string;
+  readonly budgetMs?: number;
+  readonly frugality?: FrugalityWeights;
+  readonly projectionWeightsPath?: string;
+}
+
+const DEFAULT_BUDGET_MS = 100;
+const MIN_BUDGET_MS = 80;
+const MAX_BUDGET_MS = 120;
+
+export const DEFAULT_HYDRA_PROJECTION_WEIGHTS_PATH = resolve(
+  'config',
+  'hydra-projection-weights.json',
+);
+
+export const HYDRA_PROJECTION_OUTPUT_DIM = 3;
+
+export const HydraProjectionWeightsSchema = z.object({
+  version: z.literal(1),
+  embedding_dim: z.literal(EMBEDDING_DIM),
+  weights: z
+    .array(z.array(z.number().finite()).length(EMBEDDING_DIM))
+    .length(HYDRA_PROJECTION_OUTPUT_DIM),
+  bias: z.array(z.number().finite()).length(HYDRA_PROJECTION_OUTPUT_DIM),
+});
+
+export interface HydraProjectionWeights {
+  readonly version: 1;
+  readonly embedding_dim: typeof EMBEDDING_DIM;
+  readonly weights: readonly (readonly number[])[];
+  readonly bias: readonly number[];
+}
+
+export interface LoadHydraProjectionWeightsOptions {
+  readonly filePath?: string;
+}
+
+export class HydraProjectionWeightsLoaderError extends Error {
+  override readonly name = 'HydraProjectionWeightsLoaderError';
+
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+  }
+}
+
+function formatZodIssues(error: z.ZodError): string {
+  return error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('\n');
+}
+
+export function parseHydraProjectionWeightsJson(raw: string): HydraProjectionWeights {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new HydraProjectionWeightsLoaderError(`Failed to parse JSON: ${message}`, {
+      cause: err,
+    });
+  }
+
+  const result = HydraProjectionWeightsSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new HydraProjectionWeightsLoaderError(
+      `Invalid HyDRA projection weights artifact:\n${formatZodIssues(result.error)}`,
+      { cause: result.error },
+    );
+  }
+
+  return result.data;
+}
+
+/**
+ * Load HyDRA projection weights from disk. Returns null when the artifact is
+ * missing; throws only when the file exists but is invalid.
+ */
+export function loadHydraProjectionWeights(
+  options?: LoadHydraProjectionWeightsOptions,
+): HydraProjectionWeights | null {
+  const filePath = options?.filePath ?? DEFAULT_HYDRA_PROJECTION_WEIGHTS_PATH;
+
+  if (!existsSync(filePath)) {
+    return null;
+  }
+
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new HydraProjectionWeightsLoaderError(`Failed to read weights file: ${message}`, {
+      cause: err,
+    });
+  }
+
+  return parseHydraProjectionWeightsJson(raw);
+}
+
+/** Resolve projection weights — missing artifacts fall back to placeholder projection. */
+export function resolveHydraProjectionWeights(
+  options?: LoadHydraProjectionWeightsOptions,
+): HydraProjectionWeights | null {
+  try {
+    return loadHydraProjectionWeights(options);
+  } catch (err: unknown) {
+    console.warn('HyDRA projection weights artifact invalid; using placeholder projection', {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return null;
+  }
+}
+
+// ─── Scoring helpers ─────────────────────────────────────────────────────────
+
+function dimensionShortfall(requirement: number, capability: number): number {
+  return Math.max(0, requirement - capability);
+}
+
+interface ShortfallResult {
+  readonly perDimension: RequirementVector;
+  readonly max: number;
+  readonly total: number;
+}
+
+function computeShortfall(
+  requirement: RequirementVector,
+  capabilities: ModelCapabilities,
+): ShortfallResult {
+  const reasoning = dimensionShortfall(requirement.reasoning, capabilities.reasoning);
+  const codeGen = dimensionShortfall(requirement.code_gen, capabilities.code_gen);
+  const toolUse = dimensionShortfall(requirement.tool_use, capabilities.tool_use);
+
+  return {
+    perDimension: { reasoning, code_gen: codeGen, tool_use: toolUse },
+    max: Math.max(reasoning, codeGen, toolUse),
+    total: reasoning + codeGen + toolUse,
+  };
+}
+
+function cosineSimilarity(a: RequirementVector, b: ModelCapabilities): number {
+  const dot =
+    a.reasoning * b.reasoning + a.code_gen * b.code_gen + a.tool_use * b.tool_use;
+  const magA = Math.sqrt(
+    a.reasoning ** 2 + a.code_gen ** 2 + a.tool_use ** 2,
+  );
+  const magB = Math.sqrt(
+    b.reasoning ** 2 + b.code_gen ** 2 + b.tool_use ** 2,
+  );
+  if (magA === 0 || magB === 0) return 0;
+  return dot / (magA * magB);
+}
+
+// ─── Projection helpers (384-dim → 3 requirement dimensions) ─────────────────
+
+function sigmoid(x: number): number {
+  return 1 / (1 + Math.exp(-x));
+}
+
+function meanSlice(embedding: Float32Array, start: number, end: number): number {
+  let sum = 0;
+  for (let i = start; i < end; i++) {
+    sum += embedding[i] ?? 0;
+  }
+  return sum / (end - start);
+}
+
+function projectToRequirementsPlaceholder(embedding: Float32Array): RequirementVector {
+  const third = Math.floor(EMBEDDING_DIM / 3);
+
+  return {
+    reasoning: sigmoid(meanSlice(embedding, 0, third)),
+    code_gen: sigmoid(meanSlice(embedding, third, 2 * third)),
+    tool_use: sigmoid(meanSlice(embedding, 2 * third, EMBEDDING_DIM)),
+  };
+}
+
+function linearProjection(
+  embedding: Float32Array,
+  weights: HydraProjectionWeights,
+): readonly [number, number, number] {
+  const logits: number[] = [];
+
+  for (let dim = 0; dim < HYDRA_PROJECTION_OUTPUT_DIM; dim++) {
+    const row = weights.weights[dim]!;
+    let sum = weights.bias[dim] ?? 0;
+    for (let i = 0; i < EMBEDDING_DIM; i++) {
+      sum += (embedding[i] ?? 0) * (row[i] ?? 0);
+    }
+    logits.push(sum);
+  }
+
+  return [logits[0]!, logits[1]!, logits[2]!];
+}
+
+function projectToRequirementsLearned(
+  embedding: Float32Array,
+  weights: HydraProjectionWeights,
+): RequirementVector {
+  const [reasoningLogit, codeGenLogit, toolUseLogit] = linearProjection(embedding, weights);
+
+  return {
+    reasoning: sigmoid(reasoningLogit),
+    code_gen: sigmoid(codeGenLogit),
+    tool_use: sigmoid(toolUseLogit),
+  };
+}
+
+/**
+ * Project a 384-dim embedding to 3 requirement dimensions.
+ *
+ * Uses learned linear projection (sigmoid(embedding @ W + b)) when weights are
+ * provided; otherwise falls back to deterministic mean-pooled-thirds placeholder.
+ */
+export function projectToRequirements(
+  embedding: Float32Array,
+  weights?: HydraProjectionWeights | null,
+): RequirementVector {
+  if (embedding.length !== EMBEDDING_DIM) {
+    throw new Error(
+      `Embedding shape mismatch: expected ${EMBEDDING_DIM}, got ${embedding.length}`,
+    );
+  }
+
+  if (weights) {
+    return projectToRequirementsLearned(embedding, weights);
+  }
+
+  return projectToRequirementsPlaceholder(embedding);
+}
+
+// ─── HyDRA embedding adapter ─────────────────────────────────────────────────
+
+/**
+ * Adapts a shared TextEmbedder for HyDRA requirement extraction.
+ * dispose() delegates to the underlying embedder for shared lifecycle.
+ */
+export function wrapHydraEmbeddingProvider(
+  embedder: TextEmbedder,
+  projectionWeights?: HydraProjectionWeights | null,
+): EmbeddingProvider {
+  return {
+    async extractRequirements(text: string): Promise<RequirementVector> {
+      const embedding = await embedder.embed(text);
+      return projectToRequirements(embedding, projectionWeights);
+    },
+
+    async dispose(): Promise<void> {
+      await embedder.dispose();
+    },
+  };
+}
+
+// ─── HydraMatcher ────────────────────────────────────────────────────────────
+
+export class HydraMatcher {
+  private readonly provider: EmbeddingProvider;
+  private readonly budgetMs: number;
+  private readonly frugality: FrugalityWeights;
+  private readonly projectionWeights: HydraProjectionWeights | null;
+
+  constructor(provider: EmbeddingProvider, config: HydraMatcherConfig) {
+    const budget = config.budgetMs ?? DEFAULT_BUDGET_MS;
+    if (budget < MIN_BUDGET_MS || budget > MAX_BUDGET_MS) {
+      throw new Error(
+        `HyDRA budget must be ${MIN_BUDGET_MS}–${MAX_BUDGET_MS}ms, got ${budget}ms`,
+      );
+    }
+    this.provider = provider;
+    this.budgetMs = budget;
+    this.frugality = config.frugality ?? DEFAULT_OPERATOR_CONFIG.frugality;
+    this.projectionWeights = resolveHydraProjectionWeights(
+      config.projectionWeightsPath ? { filePath: config.projectionWeightsPath } : undefined,
+    );
+  }
+
+  /** Whether learned projection weights were loaded at init. */
+  usesLearnedProjection(): boolean {
+    return this.projectionWeights !== null;
+  }
+
+  async match(
+    request: RoutingRequest,
+    fleet: readonly ModelProfile[],
+  ): Promise<MatchResult> {
+    const start = performance.now();
+
+    const requirements = await this.provider.extractRequirements(
+      buildHydraInput(request),
+    );
+    this.validateRequirements(requirements);
+
+    const healthyFleet = fleet.filter((m) => m.healthy !== false);
+    const candidates: CandidateScore[] = [];
+
+    for (const model of healthyFleet) {
+      const elapsed = performance.now() - start;
+      if (elapsed > this.budgetMs) {
+        break;
+      }
+
+      const shortfall = computeShortfall(requirements, model.capabilities);
+      const hasShortfall = shortfall.max > 0;
+
+      const score = hasShortfall
+        ? 0
+        : cosineSimilarity(requirements, model.capabilities);
+
+      candidates.push({
+        model_id: model.id,
+        score,
+        shortfall: shortfall.max,
+        rejected_reason: hasShortfall ? 'shortfall_gate' : null,
+      });
+    }
+
+    const shortfallByModel = new Map(
+      candidates.map((c) => [c.model_id, c.shortfall]),
+    );
+    const multiObjective = scoreMultiObjective(
+      candidates,
+      healthyFleet,
+      this.frugality,
+    );
+
+    const toCandidateScore = (
+      scored: (typeof multiObjective.candidates)[number],
+    ): CandidateScore => ({
+      model_id: scored.model_id,
+      score: scored.composite_score,
+      shortfall: shortfallByModel.get(scored.model_id) ?? 0,
+      rejected_reason: scored.rejected_reason,
+    });
+
+    const rankedCandidates = multiObjective.candidates.map(toCandidateScore);
+    const selected = multiObjective.selected
+      ? toCandidateScore(multiObjective.selected)
+      : null;
+
+    const elapsedMs = performance.now() - start;
+
+    return {
+      selected,
+      candidates: rankedCandidates,
+      requirements,
+      elapsedMs,
+      budgetExceeded: elapsedMs > this.budgetMs,
+    };
+  }
+
+  async dispose(): Promise<void> {
+    await this.provider.dispose();
+  }
+
+  private validateRequirements(req: RequirementVector): void {
+    const dims: readonly (keyof RequirementVector)[] = [
+      'reasoning',
+      'code_gen',
+      'tool_use',
+    ];
+    for (const key of dims) {
+      const value = req[key];
+      if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(
+          `Invalid requirement dimension '${key}': ${String(value)}`,
+        );
+      }
+    }
+  }
+}
+
+// ─── ONNX embedding provider factory ─────────────────────────────────────────
+
+export interface CreateOnnxEmbeddingProviderOptions {
+  readonly projectionWeightsPath?: string;
+}
+
+/**
+ * Creates an EmbeddingProvider backed by the shared ONNX text embedder.
+ * For multi-matcher setups, create one TextEmbedder via createOnnxTextEmbedder
+ * and pass wrapHydraEmbeddingProvider(embedder) to HyDRA while sharing embed().
+ */
+export async function createOnnxEmbeddingProvider(
+  artifactCachePath: string,
+  options?: CreateOnnxEmbeddingProviderOptions,
+): Promise<EmbeddingProvider> {
+  const embedder = await createOnnxTextEmbedder(artifactCachePath);
+  const projectionWeights = resolveHydraProjectionWeights(
+    options?.projectionWeightsPath ? { filePath: options.projectionWeightsPath } : undefined,
+  );
+  return wrapHydraEmbeddingProvider(embedder, projectionWeights);
+}

package/src/domain/pinning/cache-economics.ts

@@ -0,0 +1,128 @@
+/**
+ * Cache-warmup economics — FR-008 rule #4, SC-006.
+ *
+ * Decides whether switching providers justifies the cache-warmup penalty.
+ * A provider switch invalidates upstream KV-cache, so the router must
+ * compare the warmup cost against projected savings from the candidate
+ * model before breaking a pin.
+ *
+ * When warmup cost exceeds projected savings the pin holds (User Story 4,
+ * scenario 4).
+ */
+
+import type { ModelProfile, SessionPin } from '../types/index.js';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface CacheEconomicsConfig {
+  /**
+   * Multiplier applied to estimated_input_tokens to approximate
+   * the token cost of re-prompting a cold provider cache.
+   * Default: 1.15 (15 % warmup overhead).
+   */
+  readonly warmupCostMultiplier?: number;
+
+  /**
+   * Minimum per-1M-token savings required to justify a provider switch.
+   * Prevents switching for negligible price differences.
+   * Default: 0.10 (USD).
+   */
+  readonly minSavingsThreshold?: number;
+
+  /**
+   * Number of remaining turns to amortize savings over.
+   * Higher values favor switching; lower values favor keeping the pin.
+   * Default: 5.
+   */
+  readonly projectedRemainingTurns?: number;
+}
+
+export interface CacheEconomicsResult {
+  readonly shouldSwitch: boolean;
+  readonly warmupCostUsd: number;
+  readonly projectedSavingsUsd: number;
+  readonly reason: string;
+}
+
+// ─── Defaults ─────────────────────────────────────────────────────────────────
+
+const DEFAULT_WARMUP_COST_MULTIPLIER = 1.15;
+const DEFAULT_MIN_SAVINGS_THRESHOLD = 0.10;
+const DEFAULT_PROJECTED_REMAINING_TURNS = 5;
+
+// ─── Evaluation ───────────────────────────────────────────────────────────────
+
+/**
+ * Evaluate whether switching from the currently-pinned model to a candidate
+ * on a different provider is justified by projected cost savings.
+ *
+ * Returns `shouldSwitch: false` when:
+ * - Candidate is on the same provider (no cache penalty).
+ *   Caller should handle same-provider switches without this check.
+ * - Warmup cost exceeds projected savings.
+ * - Savings fall below the minimum threshold.
+ *
+ * Returns `shouldSwitch: true` only when projected savings meaningfully
+ * exceed the cache-warmup penalty.
+ */
+export function evaluateCacheEconomics(
+  pin: SessionPin,
+  pinnedModel: ModelProfile,
+  candidate: ModelProfile,
+  estimatedInputTokens: number,
+  config?: CacheEconomicsConfig,
+): CacheEconomicsResult {
+  const warmupMultiplier =
+    config?.warmupCostMultiplier ?? DEFAULT_WARMUP_COST_MULTIPLIER;
+  const minSavings =
+    config?.minSavingsThreshold ?? DEFAULT_MIN_SAVINGS_THRESHOLD;
+  const remainingTurns =
+    config?.projectedRemainingTurns ?? DEFAULT_PROJECTED_REMAINING_TURNS;
+
+  if (pinnedModel.provider === candidate.provider) {
+    return {
+      shouldSwitch: false,
+      warmupCostUsd: 0,
+      projectedSavingsUsd: 0,
+      reason: 'same_provider_no_cache_penalty',
+    };
+  }
+
+  const tokenCountM = estimatedInputTokens / 1_000_000;
+
+  const warmupTokens = estimatedInputTokens * (warmupMultiplier - 1);
+  const warmupCostUsd =
+    (warmupTokens / 1_000_000) * candidate.pricing.fallback_cost_per_1m;
+
+  const perTurnSavings =
+    (pinnedModel.pricing.fallback_cost_per_1m -
+      candidate.pricing.fallback_cost_per_1m) *
+    tokenCountM;
+
+  const projectedSavingsUsd = perTurnSavings * remainingTurns;
+
+  if (projectedSavingsUsd < minSavings) {
+    return {
+      shouldSwitch: false,
+      warmupCostUsd,
+      projectedSavingsUsd,
+      reason: 'savings_below_threshold',
+    };
+  }
+
+  if (warmupCostUsd >= projectedSavingsUsd) {
+    return {
+      shouldSwitch: false,
+      warmupCostUsd,
+      projectedSavingsUsd,
+      reason: 'warmup_exceeds_savings',
+    };
+  }
+
+  return {
+    shouldSwitch: true,
+    warmupCostUsd,
+    projectedSavingsUsd,
+    reason: 'switch_justified',
+  };
+}