pi-smart-router 0.1.0

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

@@ -0,0 +1,474 @@
+/**
+ * Semantic cluster matcher — SP-101, GitHub #56.
+ *
+ * Embeds request prompt text via shared TextEmbedder, scores cosine similarity
+ * against precomputed cluster centroids, and returns best match with confidence
+ * from per-cluster min_similarity and min_margin thresholds.
+ *
+ * Centroids load from `config/routing-centroids.json` at startup when present;
+ * otherwise they are computed inline from reference prompts (SP-114).
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import {
+  loadRoutingClusters,
+  parseRoutingClustersYaml,
+} from '../../config/routing-clusters-loader.js';
+import { EMBEDDING_DIM, type TextEmbedder } from './embedding-provider.js';
+import type {
+  ClusterMatchTableEntry,
+  LoadedRoutingCluster,
+  RoutingCluster,
+  RoutingClusterCatalog,
+  RoutingRequest,
+  Tier,
+} from '../types/index.js';
+
+// ─── Precomputed centroid artifact (SP-114) ──────────────────────────────────
+
+export const DEFAULT_ROUTING_CENTROIDS_PATH = 'config/routing-centroids.json';
+
+export interface RoutingCentroidRecord {
+  readonly cluster_id: string;
+  readonly tier_bias: Tier;
+  readonly centroid: readonly number[];
+  readonly reference_count: number;
+}
+
+export interface RoutingCentroidsArtifact {
+  readonly version: number;
+  readonly embedding_dim: number;
+  readonly clusters: readonly RoutingCentroidRecord[];
+}
+
+export class RoutingCentroidsError extends Error {
+  override readonly name = 'RoutingCentroidsError';
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+  }
+}
+
+export function computeCentroid(embeddings: readonly Float32Array[]): Float32Array {
+  if (embeddings.length === 0) {
+    throw new RoutingCentroidsError('Cannot compute centroid from zero embeddings');
+  }
+
+  const dim = embeddings[0]!.length;
+  const centroid = new Float32Array(dim);
+
+  for (const embedding of embeddings) {
+    if (embedding.length !== dim) {
+      throw new RoutingCentroidsError(
+        `Embedding shape mismatch: expected ${dim}, got ${embedding.length}`,
+      );
+    }
+    for (let i = 0; i < dim; i++) {
+      centroid[i] = (centroid[i] ?? 0) + (embedding[i] ?? 0);
+    }
+  }
+
+  for (let i = 0; i < dim; i++) {
+    centroid[i] = (centroid[i] ?? 0) / embeddings.length;
+  }
+
+  return centroid;
+}
+
+function parseRoutingCentroidsArtifact(parsed: unknown): RoutingCentroidsArtifact {
+  if (typeof parsed !== 'object' || parsed === null) {
+    throw new RoutingCentroidsError('Invalid routing centroids artifact: expected object');
+  }
+
+  const record = parsed as Record<string, unknown>;
+  const version = record.version;
+  const embeddingDim = record.embedding_dim;
+  const clusters = record.clusters;
+
+  if (version !== 1) {
+    throw new RoutingCentroidsError(
+      `Unsupported routing centroids version: ${String(version)}`,
+    );
+  }
+  if (embeddingDim !== EMBEDDING_DIM) {
+    throw new RoutingCentroidsError(
+      `Invalid embedding_dim: expected ${EMBEDDING_DIM}, got ${String(embeddingDim)}`,
+    );
+  }
+  if (!Array.isArray(clusters) || clusters.length === 0) {
+    throw new RoutingCentroidsError('Invalid routing centroids artifact: clusters required');
+  }
+
+  const parsedClusters: RoutingCentroidRecord[] = [];
+  for (const entry of clusters) {
+    if (typeof entry !== 'object' || entry === null) {
+      throw new RoutingCentroidsError('Invalid cluster entry in routing centroids artifact');
+    }
+    const cluster = entry as Record<string, unknown>;
+    const clusterId = cluster.cluster_id;
+    const tierBias = cluster.tier_bias;
+    const centroid = cluster.centroid;
+    const referenceCount = cluster.reference_count;
+
+    if (typeof clusterId !== 'string' || clusterId.length === 0) {
+      throw new RoutingCentroidsError('Invalid cluster_id in routing centroids artifact');
+    }
+    if (
+      tierBias !== 'zero-tier' &&
+      tierBias !== 'economical-cloud' &&
+      tierBias !== 'frontier-cloud'
+    ) {
+      throw new RoutingCentroidsError(
+        `Invalid tier_bias for cluster '${clusterId}': ${String(tierBias)}`,
+      );
+    }
+    if (!Array.isArray(centroid) || centroid.length !== EMBEDDING_DIM) {
+      throw new RoutingCentroidsError(
+        `Invalid centroid for cluster '${clusterId}': expected ${EMBEDDING_DIM} dimensions`,
+      );
+    }
+    if (
+      !centroid.every((value) => typeof value === 'number' && Number.isFinite(value))
+    ) {
+      throw new RoutingCentroidsError(
+        `Invalid centroid values for cluster '${clusterId}': must be finite numbers`,
+      );
+    }
+    if (typeof referenceCount !== 'number' || !Number.isInteger(referenceCount) || referenceCount < 1) {
+      throw new RoutingCentroidsError(
+        `Invalid reference_count for cluster '${clusterId}'`,
+      );
+    }
+
+    parsedClusters.push({
+      cluster_id: clusterId,
+      tier_bias: tierBias,
+      centroid,
+      reference_count: referenceCount,
+    });
+  }
+
+  return {
+    version: 1,
+    embedding_dim: EMBEDDING_DIM,
+    clusters: parsedClusters,
+  };
+}
+
+export function loadRoutingCentroidsArtifact(
+  filePath: string = resolve(DEFAULT_ROUTING_CENTROIDS_PATH),
+): RoutingCentroidsArtifact {
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new RoutingCentroidsError(
+      `Failed to read routing centroids file: ${message}`,
+      { cause: err },
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new RoutingCentroidsError(`Failed to parse routing centroids JSON: ${message}`, {
+      cause: err,
+    });
+  }
+
+  return parseRoutingCentroidsArtifact(parsed);
+}
+
+export function validateCentroidClusterIds(
+  catalogClusters: readonly RoutingCluster[],
+  artifact: RoutingCentroidsArtifact,
+): void {
+  const catalogIds = new Set(catalogClusters.map((cluster) => cluster.id));
+  const artifactIds = new Set(artifact.clusters.map((cluster) => cluster.cluster_id));
+
+  for (const id of catalogIds) {
+    if (!artifactIds.has(id)) {
+      throw new RoutingCentroidsError(
+        `Routing centroids artifact missing cluster_id '${id}' from catalog`,
+      );
+    }
+  }
+
+  for (const id of artifactIds) {
+    if (!catalogIds.has(id)) {
+      throw new RoutingCentroidsError(
+        `Routing centroids artifact has unknown cluster_id '${id}'`,
+      );
+    }
+  }
+
+  const catalogById = new Map(catalogClusters.map((cluster) => [cluster.id, cluster]));
+  for (const record of artifact.clusters) {
+    const catalogCluster = catalogById.get(record.cluster_id)!;
+    if (catalogCluster.tier_bias !== record.tier_bias) {
+      throw new RoutingCentroidsError(
+        `tier_bias mismatch for cluster '${record.cluster_id}': catalog=${catalogCluster.tier_bias}, artifact=${record.tier_bias}`,
+      );
+    }
+    if (catalogCluster.reference_prompts.length !== record.reference_count) {
+      throw new RoutingCentroidsError(
+        `reference_count mismatch for cluster '${record.cluster_id}': catalog=${catalogCluster.reference_prompts.length}, artifact=${record.reference_count}`,
+      );
+    }
+  }
+}
+
+export function applyPrecomputedCentroids(
+  catalogClusters: readonly RoutingCluster[],
+  artifact: RoutingCentroidsArtifact,
+): readonly LoadedRoutingCluster[] {
+  validateCentroidClusterIds(catalogClusters, artifact);
+
+  const centroidById = new Map(
+    artifact.clusters.map((record) => [
+      record.cluster_id,
+      new Float32Array(record.centroid),
+    ]),
+  );
+
+  return catalogClusters.map((cluster) => ({
+    ...cluster,
+    centroid: centroidById.get(cluster.id)!,
+  }));
+}
+
+export async function buildRoutingCentroidsArtifact(
+  catalogClusters: readonly RoutingCluster[],
+  embedder: TextEmbedder,
+): Promise<RoutingCentroidsArtifact> {
+  const clusters: RoutingCentroidRecord[] = [];
+
+  for (const cluster of catalogClusters) {
+    const embeddings: Float32Array[] = [];
+    for (const prompt of cluster.reference_prompts) {
+      embeddings.push(await embedder.embed(prompt));
+    }
+
+    clusters.push({
+      cluster_id: cluster.id,
+      tier_bias: cluster.tier_bias,
+      centroid: Array.from(computeCentroid(embeddings)),
+      reference_count: cluster.reference_prompts.length,
+    });
+  }
+
+  return {
+    version: 1,
+    embedding_dim: EMBEDDING_DIM,
+    clusters,
+  };
+}
+
+export function serializeRoutingCentroidsArtifact(
+  artifact: RoutingCentroidsArtifact,
+): string {
+  return `${JSON.stringify(artifact, null, 2)}\n`;
+}
+
+export interface CreateClusterMatcherOptions {
+  readonly clustersFilePath?: string;
+  readonly centroidsFilePath?: string;
+  readonly embedder: TextEmbedder;
+}
+
+function isMissingCentroidsFileError(err: unknown): boolean {
+  return (
+    err instanceof RoutingCentroidsError &&
+    err.cause instanceof Error &&
+    'code' in err.cause &&
+    err.cause.code === 'ENOENT'
+  );
+}
+
+/**
+ * Load routing cluster catalog with precomputed centroids when the artifact exists.
+ * Falls back to inline centroid computation from reference prompts when missing.
+ */
+export async function loadClusterMatcherCatalog(
+  options: CreateClusterMatcherOptions,
+): Promise<RoutingClusterCatalog> {
+  const clustersFilePath =
+    options.clustersFilePath ?? resolve('config', 'routing-clusters.yaml');
+  const centroidsFilePath =
+    options.centroidsFilePath ?? resolve(DEFAULT_ROUTING_CENTROIDS_PATH);
+
+  const raw = readFileSync(clustersFilePath, 'utf8');
+  const catalogClusters = parseRoutingClustersYaml(raw);
+
+  try {
+    const artifact = loadRoutingCentroidsArtifact(centroidsFilePath);
+    return { clusters: applyPrecomputedCentroids(catalogClusters, artifact) };
+  } catch (err: unknown) {
+    if (isMissingCentroidsFileError(err)) {
+      return loadRoutingClusters({
+        filePath: clustersFilePath,
+        embedder: options.embedder,
+      });
+    }
+    throw err;
+  }
+}
+
+export async function createClusterMatcher(
+  options: CreateClusterMatcherOptions,
+): Promise<ClusterMatcher> {
+  const catalog = await loadClusterMatcherCatalog(options);
+  return new ClusterMatcher({ catalog, embedder: options.embedder });
+}
+
+// ─── Match result ────────────────────────────────────────────────────────────
+
+export type ClusterMatchConfidence = 'high' | 'low' | 'none';
+
+export interface ClusterMatchResult {
+  readonly clusterId: string;
+  readonly tierBias: Tier;
+  readonly similarity: number;
+  /** sim(best) - sim(second); 0 when only one cluster exists. */
+  readonly margin: number;
+  readonly confidence: ClusterMatchConfidence;
+  readonly elapsedMs: number;
+}
+
+// ─── Scoring helpers ─────────────────────────────────────────────────────────
+
+interface RankedCluster {
+  readonly cluster: LoadedRoutingCluster;
+  readonly similarity: number;
+}
+
+export function cosineSimilarity(a: Float32Array, b: Float32Array): number {
+  if (a.length !== b.length) {
+    throw new Error(
+      `Embedding shape mismatch: expected ${a.length}, got ${b.length}`,
+    );
+  }
+
+  let dot = 0;
+  let magA = 0;
+  let magB = 0;
+
+  for (let i = 0; i < a.length; i++) {
+    const av = a[i] ?? 0;
+    const bv = b[i] ?? 0;
+    dot += av * bv;
+    magA += av * av;
+    magB += bv * bv;
+  }
+
+  if (magA === 0 || magB === 0) {
+    return 0;
+  }
+
+  return dot / (Math.sqrt(magA) * Math.sqrt(magB));
+}
+
+function rankClusters(
+  embedding: Float32Array,
+  clusters: readonly LoadedRoutingCluster[],
+): readonly RankedCluster[] {
+  return clusters
+    .map((cluster) => ({
+      cluster,
+      similarity: cosineSimilarity(embedding, cluster.centroid),
+    }))
+    .sort((a, b) => b.similarity - a.similarity);
+}
+
+function computeConfidence(
+  similarity: number,
+  margin: number,
+  minSimilarity: number,
+  minMargin: number,
+): ClusterMatchConfidence {
+  if (similarity >= minSimilarity && margin >= minMargin) {
+    return 'high';
+  }
+  // Issue #56: low-confidence matches defer — report none for routing.
+  return 'none';
+}
+
+// ─── ClusterMatcher ──────────────────────────────────────────────────────────
+
+export interface ClusterMatcherConfig {
+  readonly catalog: RoutingClusterCatalog;
+  readonly embedder: TextEmbedder;
+}
+
+export class ClusterMatcher {
+  private readonly clusters: readonly LoadedRoutingCluster[];
+  private readonly embedder: TextEmbedder;
+
+  constructor(config: ClusterMatcherConfig) {
+    if (config.catalog.clusters.length === 0) {
+      throw new Error('ClusterMatcher requires at least one loaded cluster');
+    }
+    this.clusters = config.catalog.clusters;
+    this.embedder = config.embedder;
+  }
+
+  async match(request: RoutingRequest): Promise<ClusterMatchResult> {
+    const start = performance.now();
+
+    const embedding = await this.embedder.embed(request.prompt_text);
+    const ranked = rankClusters(embedding, this.clusters);
+    const best = ranked[0]!;
+    const runnerUp = ranked[1];
+    const margin = runnerUp
+      ? best.similarity - runnerUp.similarity
+      : 0;
+
+    const confidence = computeConfidence(
+      best.similarity,
+      margin,
+      best.cluster.min_similarity,
+      best.cluster.min_margin,
+    );
+
+    return {
+      clusterId: best.cluster.id,
+      tierBias: best.cluster.tier_bias,
+      similarity: best.similarity,
+      margin,
+      confidence,
+      elapsedMs: performance.now() - start,
+    };
+  }
+
+  /** Score all cluster centroids for explain / telemetry tables (SP-113). */
+  async matchTable(request: RoutingRequest): Promise<readonly ClusterMatchTableEntry[]> {
+    const embedding = await this.embedder.embed(request.prompt_text);
+    const ranked = rankClusters(embedding, this.clusters);
+    const best = ranked[0];
+
+    return ranked.map((entry, index) => {
+      const runnerUp = ranked[index + 1];
+      const margin = runnerUp ? entry.similarity - runnerUp.similarity : null;
+      const confidence = computeConfidence(
+        entry.similarity,
+        index === 0 ? (margin ?? 0) : 0,
+        entry.cluster.min_similarity,
+        entry.cluster.min_margin,
+      );
+
+      return {
+        cluster_id: entry.cluster.id,
+        tier_bias: entry.cluster.tier_bias,
+        similarity: entry.similarity,
+        margin: index === 0 ? margin : null,
+        confidence: confidence === 'high' ? 'high' : 'none',
+        selected: entry === best,
+      };
+    });
+  }
+}

package/src/domain/matching/embedding-provider.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared MiniLM ONNX text embedder — SP-100.
+ *
+ * Embeds prompt text via Xenova/all-MiniLM-L6-v2 (384-dim) for HyDRA requirement
+ * projection and semantic cluster matching. One ONNX session per instance; share
+ * across matchers via a single factory call and coordinated dispose().
+ */
+
+export const EMBEDDING_DIM = 384;
+
+export interface TextEmbedder {
+  embed(text: string): Promise<Float32Array>;
+  dispose(): Promise<void>;
+}
+
+// ─── ONNX runtime types ───────────────────────────────────────────────────────
+
+interface OnnxPipelineOutput {
+  readonly data: Float32Array;
+}
+
+type OnnxExtractorFn = (
+  text: string,
+  options: { readonly pooling: string; readonly normalize: boolean },
+) => Promise<OnnxPipelineOutput>;
+
+interface TransformersModule {
+  pipeline(
+    task: string,
+    model: string,
+    options: Record<string, unknown>,
+  ): Promise<OnnxExtractorFn>;
+}
+
+/**
+ * Creates a TextEmbedder backed by @huggingface/transformers ONNX runtime.
+ * Model: Xenova/all-MiniLM-L6-v2 (384-dim).
+ *
+ * The package is loaded dynamically — not required at compile time.
+ * Install: `npm i @huggingface/transformers`
+ */
+export async function createOnnxTextEmbedder(
+  artifactCachePath: string,
+): Promise<TextEmbedder> {
+  const moduleName = '@huggingface/transformers';
+  let mod: TransformersModule;
+  try {
+    mod = (await import(moduleName)) as TransformersModule;
+  } catch {
+    throw new Error(
+      `ONNX embedding requires ${moduleName}. Install: npm i ${moduleName}`,
+    );
+  }
+
+  const extractor: OnnxExtractorFn = await mod.pipeline(
+    'feature-extraction',
+    'Xenova/all-MiniLM-L6-v2',
+    { cache_dir: artifactCachePath },
+  );
+
+  return {
+    async embed(text: string): Promise<Float32Array> {
+      const output = await extractor(text, {
+        pooling: 'mean',
+        normalize: true,
+      });
+      if (output.data.length !== EMBEDDING_DIM) {
+        throw new Error(
+          `Embedding shape mismatch: expected ${EMBEDDING_DIM}, got ${output.data.length}`,
+        );
+      }
+      return output.data;
+    },
+
+    async dispose(): Promise<void> {
+      /* @huggingface/transformers pipelines have no explicit dispose */
+    },
+  };
+}

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

@@ -0,0 +1,53 @@
+/**
+ * HyDRA embedding input builder — SP-112, GitHub #60.
+ *
+ * Prefixes prompt text with session metadata so requirement vectors reflect
+ * turn context, not only the latest user string.
+ */
+
+import type { RoutingRequest } from '../types/index.js';
+import type { TriageResult } from '../triage/triage-engine.js';
+
+function resolveMessageCount(request: RoutingRequest): number {
+  return request.messages?.length ?? 0;
+}
+
+function resolveHasToolContext(request: RoutingRequest): boolean {
+  if (request.turn_type === 'tool_result') {
+    return true;
+  }
+
+  return request.messages?.some((message) => message.role === 'tool') ?? false;
+}
+
+function resolveEstimatedInputTokens(request: RoutingRequest): number {
+  return request.estimated_input_tokens ?? 0;
+}
+
+function resolveTurnType(request: RoutingRequest): string {
+  return request.turn_type ?? 'unknown';
+}
+
+/**
+ * Build HyDRA encoder input: metadata prefix + prompt text.
+ *
+ * Format: `[turns:N|tools:0|tokens:N|type:...] {prompt_text}`
+ *
+ * Metadata affects capability prediction only; tier selection uses the
+ * cluster/feature gate (SP-103) separately.
+ */
+export function buildHydraInput(
+  request: RoutingRequest,
+  triage?: TriageResult,
+): string {
+  void triage;
+
+  const flags = [
+    `turns:${resolveMessageCount(request)}`,
+    `tools:${resolveHasToolContext(request) ? 1 : 0}`,
+    `tokens:${resolveEstimatedInputTokens(request)}`,
+    `type:${resolveTurnType(request)}`,
+  ].join('|');
+
+  return `[${flags}] ${request.prompt_text}`;
+}