semantic-router-ts 1.0.0

package/dist/index.js

@@ -0,0 +1,467 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BaseEncoder: () => BaseEncoder,
+  LocalEncoder: () => LocalEncoder,
+  LocalIndex: () => LocalIndex,
+  OpenAIEncoder: () => OpenAIEncoder,
+  SemanticRouter: () => SemanticRouter
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/encoders/base.ts
+var BaseEncoder = class {
+  initialized = false;
+  /**
+   * Encode multiple texts in batch.
+   * Default implementation calls encode() for each, but subclasses
+   * can override for more efficient batch processing.
+   */
+  async encodeBatch(texts) {
+    return Promise.all(texts.map((text) => this.encode(text)));
+  }
+  /**
+   * Normalize an embedding vector to unit length.
+   */
+  normalize(embedding) {
+    const norm = Math.sqrt(embedding.reduce((sum, val) => sum + val * val, 0));
+    if (norm === 0) return embedding;
+    return embedding.map((val) => val / norm);
+  }
+};
+
+// src/encoders/local.ts
+var pipeline = null;
+var loadPromise = null;
+async function loadTransformers() {
+  if (pipeline) return;
+  if (loadPromise) {
+    await loadPromise;
+    return;
+  }
+  loadPromise = (async () => {
+    try {
+      const transformers = await import("@xenova/transformers");
+      pipeline = transformers.pipeline;
+    } catch {
+      throw new Error(
+        "LocalEncoder requires @xenova/transformers. Install it with: npm install @xenova/transformers"
+      );
+    }
+  })();
+  await loadPromise;
+}
+var LocalEncoder = class _LocalEncoder extends BaseEncoder {
+  name = "LocalEncoder";
+  dimensions;
+  model;
+  embedder = null;
+  initPromise = null;
+  shouldNormalize;
+  // Model -> dimensions mapping
+  static MODEL_DIMENSIONS = {
+    "Xenova/all-MiniLM-L6-v2": 384,
+    "Xenova/all-mpnet-base-v2": 768,
+    "Xenova/bge-small-en-v1.5": 384,
+    "Xenova/bge-base-en-v1.5": 768
+  };
+  constructor(config = {}) {
+    super();
+    this.model = config.model || "Xenova/all-MiniLM-L6-v2";
+    this.dimensions = _LocalEncoder.MODEL_DIMENSIONS[this.model] || 384;
+    this.shouldNormalize = config.normalize ?? true;
+  }
+  async ensureInitialized() {
+    if (this.initialized && this.embedder) return;
+    if (this.initPromise) {
+      await this.initPromise;
+      return;
+    }
+    this.initPromise = this.initialize();
+    await this.initPromise;
+  }
+  async initialize() {
+    await loadTransformers();
+    console.log(`[LocalEncoder] Loading model: ${this.model}...`);
+    const start = Date.now();
+    this.embedder = await pipeline("feature-extraction", this.model);
+    this.initialized = true;
+    console.log(`[LocalEncoder] Model loaded in ${Date.now() - start}ms`);
+  }
+  async encode(text) {
+    await this.ensureInitialized();
+    const result = await this.embedder(text, {
+      pooling: "mean",
+      normalize: this.shouldNormalize
+    });
+    return Array.from(result.data);
+  }
+  async encodeBatch(texts) {
+    await this.ensureInitialized();
+    const results = await Promise.all(
+      texts.map(async (text) => {
+        const result = await this.embedder(text, {
+          pooling: "mean",
+          normalize: this.shouldNormalize
+        });
+        return Array.from(result.data);
+      })
+    );
+    return results;
+  }
+};
+
+// src/encoders/openai.ts
+var OpenAIClass = null;
+async function loadOpenAI() {
+  if (OpenAIClass) return;
+  try {
+    const openaiModule = await import("openai");
+    OpenAIClass = openaiModule.default || openaiModule.OpenAI;
+  } catch {
+    throw new Error(
+      "OpenAIEncoder requires openai package. Install it with: npm install openai"
+    );
+  }
+}
+var OpenAIEncoder = class _OpenAIEncoder extends BaseEncoder {
+  name = "OpenAIEncoder";
+  dimensions;
+  model;
+  apiKey;
+  client = null;
+  // Model -> default dimensions mapping
+  static MODEL_DIMENSIONS = {
+    "text-embedding-3-small": 1536,
+    "text-embedding-3-large": 3072,
+    "text-embedding-ada-002": 1536
+  };
+  constructor(config = {}) {
+    super();
+    this.model = config.model || "text-embedding-3-small";
+    this.dimensions = config.dimensions || _OpenAIEncoder.MODEL_DIMENSIONS[this.model] || 1536;
+    this.apiKey = config.apiKey || process.env.OPENAI_API_KEY || "";
+    if (!this.apiKey) {
+      console.warn("[OpenAIEncoder] No API key provided. Set OPENAI_API_KEY env var or pass apiKey config.");
+    }
+  }
+  async ensureClient() {
+    if (this.client) return;
+    await loadOpenAI();
+    this.client = new OpenAIClass({ apiKey: this.apiKey });
+    this.initialized = true;
+  }
+  async encode(text) {
+    const results = await this.encodeBatch([text]);
+    return results[0];
+  }
+  async encodeBatch(texts) {
+    await this.ensureClient();
+    const response = await this.client.embeddings.create({
+      model: this.model,
+      input: texts,
+      ...this.model.includes("3-") && { dimensions: this.dimensions }
+    });
+    const sorted = response.data.sort((a, b) => a.index - b.index);
+    return sorted.map((item) => item.embedding);
+  }
+};
+
+// src/index/local.ts
+var LocalIndex = class {
+  vectors = [];
+  ready = false;
+  async add(embeddings, routes, utterances) {
+    if (embeddings.length !== routes.length || routes.length !== utterances.length) {
+      throw new Error("Embeddings, routes, and utterances must have same length");
+    }
+    for (let i = 0; i < embeddings.length; i++) {
+      this.vectors.push({
+        route: routes[i],
+        utterance: utterances[i],
+        embedding: embeddings[i]
+      });
+    }
+    this.ready = true;
+  }
+  async query(embedding, topK) {
+    if (this.vectors.length === 0) {
+      return [];
+    }
+    const scored = this.vectors.map((vector) => ({
+      route: vector.route,
+      utterance: vector.utterance,
+      score: this.cosineSimilarity(embedding, vector.embedding)
+    }));
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, topK);
+  }
+  async clear() {
+    this.vectors = [];
+    this.ready = false;
+  }
+  isReady() {
+    return this.ready;
+  }
+  /**
+   * Get number of stored vectors
+   */
+  get size() {
+    return this.vectors.length;
+  }
+  /**
+   * Cosine similarity between two vectors
+   */
+  cosineSimilarity(a, b) {
+    if (a.length !== b.length) return 0;
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+      dotProduct += a[i] * b[i];
+      normA += a[i] * a[i];
+      normB += b[i] * b[i];
+    }
+    if (normA === 0 || normB === 0) return 0;
+    return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+  }
+};
+
+// src/router.ts
+var SemanticRouter = class {
+  routes = [];
+  encoder;
+  index;
+  llm;
+  // Configuration
+  topK;
+  aggregation;
+  threshold;
+  // State
+  initialized = false;
+  initPromise = null;
+  constructor(config = {}) {
+    this.routes = config.routes || [];
+    this.encoder = config.encoder || new LocalEncoder();
+    this.index = new LocalIndex();
+    this.llm = config.llm;
+    this.topK = config.topK ?? 5;
+    this.aggregation = config.aggregation ?? "mean";
+    this.threshold = config.threshold ?? 0.4;
+  }
+  /**
+   * Initialize the router by encoding all routes.
+   * Safe to call multiple times.
+   */
+  async initialize() {
+    if (this.initialized) return;
+    if (this.initPromise) {
+      await this.initPromise;
+      return;
+    }
+    this.initPromise = this.doInitialize();
+    await this.initPromise;
+  }
+  async doInitialize() {
+    if (this.routes.length === 0) {
+      console.warn("[SemanticRouter] No routes configured");
+      this.initialized = true;
+      return;
+    }
+    console.log(`[SemanticRouter] Encoding ${this.routes.length} routes...`);
+    const start = Date.now();
+    const allUtterances = [];
+    const allRouteNames = [];
+    for (const route of this.routes) {
+      for (const utterance of route.utterances) {
+        allUtterances.push(utterance);
+        allRouteNames.push(route.name);
+      }
+    }
+    const embeddings = await this.encoder.encodeBatch(allUtterances);
+    await this.index.add(embeddings, allRouteNames, allUtterances);
+    this.initialized = true;
+    console.log(
+      `[SemanticRouter] Initialized in ${Date.now() - start}ms (${allUtterances.length} utterances from ${this.routes.length} routes)`
+    );
+  }
+  /**
+   * Route a query to the best matching route.
+   */
+  async route(query) {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+    const queryEmbedding = await this.encoder.encode(query);
+    const matches = await this.index.query(queryEmbedding, this.topK);
+    if (matches.length === 0) {
+      return this.noMatch();
+    }
+    const routeScores = this.aggregateScores(matches);
+    routeScores.sort((a, b) => b.score - a.score);
+    const topMatch = routeScores[0];
+    if (topMatch.score < this.threshold) {
+      if (this.llm) {
+        return await this.llmFallback(query, routeScores);
+      }
+      return this.noMatch(routeScores);
+    }
+    const matchedRoute = this.routes.find((r) => r.name === topMatch.name);
+    return {
+      route: matchedRoute || null,
+      name: topMatch.name,
+      confidence: topMatch.score,
+      scores: routeScores
+    };
+  }
+  /**
+   * Shorthand to get just the route name
+   */
+  async classify(query) {
+    const result = await this.route(query);
+    return result.name;
+  }
+  /**
+   * Add a route dynamically
+   */
+  async addRoute(route) {
+    this.routes = this.routes.filter((r) => r.name !== route.name);
+    this.routes.push(route);
+    const embeddings = await this.encoder.encodeBatch(route.utterances);
+    const routeNames = route.utterances.map(() => route.name);
+    await this.index.add(embeddings, routeNames, route.utterances);
+    console.log(`[SemanticRouter] Added route: ${route.name} (${route.utterances.length} utterances)`);
+  }
+  /**
+   * Aggregate scores from multiple matches by route
+   */
+  aggregateScores(matches) {
+    const scoresByRoute = /* @__PURE__ */ new Map();
+    for (const match of matches) {
+      const scores = scoresByRoute.get(match.route) || [];
+      scores.push(match.score);
+      scoresByRoute.set(match.route, scores);
+    }
+    const aggregated = [];
+    for (const [name, scores] of scoresByRoute) {
+      let score;
+      switch (this.aggregation) {
+        case "max":
+          score = Math.max(...scores);
+          break;
+        case "sum":
+          score = scores.reduce((a, b) => a + b, 0);
+          break;
+        case "mean":
+        default:
+          score = scores.reduce((a, b) => a + b, 0) / scores.length;
+          break;
+      }
+      aggregated.push({ name, score });
+    }
+    return aggregated;
+  }
+  /**
+   * Use LLM to classify when similarity is low
+   */
+  async llmFallback(query, scores) {
+    if (!this.llm) {
+      return this.noMatch(scores);
+    }
+    console.log("[SemanticRouter] Using LLM fallback for low-confidence match");
+    const routeDescriptions = this.routes.map((r) => `- ${r.name}: ${r.description || r.utterances[0]}`).join("\n");
+    const prompt = `Classify the user's intent into exactly ONE of these routes:
+
+${routeDescriptions}
+
+User query: "${query}"
+
+Respond with ONLY the route name, nothing else.`;
+    try {
+      const response = await this.llm.generate(prompt);
+      const routeName = response.trim().toLowerCase();
+      const matchedRoute = this.routes.find(
+        (r) => r.name.toLowerCase() === routeName
+      );
+      if (matchedRoute) {
+        console.log(`[SemanticRouter] LLM classified as: ${matchedRoute.name}`);
+        return {
+          route: matchedRoute,
+          name: matchedRoute.name,
+          confidence: 0.7,
+          // LLM confidence estimate
+          scores
+        };
+      }
+    } catch (error) {
+      console.warn("[SemanticRouter] LLM fallback failed:", error);
+    }
+    return this.noMatch(scores);
+  }
+  /**
+   * Return a no-match result
+   */
+  noMatch(scores) {
+    return {
+      route: null,
+      name: null,
+      confidence: 0,
+      scores
+    };
+  }
+  /**
+   * Get router statistics
+   */
+  getStats() {
+    return {
+      routeCount: this.routes.length,
+      routes: this.routes.map((r) => r.name),
+      encoder: this.encoder.name,
+      threshold: this.threshold,
+      initialized: this.initialized
+    };
+  }
+  /**
+   * Check if router is ready
+   */
+  isReady() {
+    return this.initialized;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BaseEncoder,
+  LocalEncoder,
+  LocalIndex,
+  OpenAIEncoder,
+  SemanticRouter
+});