semantic-router-ts 1.0.0

package/dist/index.mjs

@@ -0,0 +1,426 @@
+// 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;
+  }
+};
+export {
+  BaseEncoder,
+  LocalEncoder,
+  LocalIndex,
+  OpenAIEncoder,
+  SemanticRouter
+};

package/package.json

@@ -0,0 +1,70 @@
+{
+    "name": "semantic-router-ts",
+    "version": "1.0.0",
+    "description": "Superfast semantic routing for LLMs and AI agents - TypeScript port of aurelio-labs/semantic-router",
+    "main": "dist/index.js",
+    "module": "dist/index.mjs",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+        "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "lint": "eslint src --ext .ts",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "semantic",
+        "router",
+        "llm",
+        "ai",
+        "embeddings",
+        "vector",
+        "similarity",
+        "agents",
+        "intent",
+        "classification"
+    ],
+    "author": "Nilesh",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/nilesh/semantic-router-ts"
+    },
+    "devDependencies": {
+        "@types/node": "^22.0.0",
+        "@typescript-eslint/eslint-plugin": "^8.0.0",
+        "@typescript-eslint/parser": "^8.0.0",
+        "eslint": "^9.0.0",
+        "tsup": "^8.0.0",
+        "typescript": "^5.7.0",
+        "vitest": "^2.0.0"
+    },
+    "peerDependencies": {
+        "@xenova/transformers": "^2.0.0",
+        "openai": "^4.0.0"
+    },
+    "peerDependenciesMeta": {
+        "@xenova/transformers": {
+            "optional": true
+        },
+        "openai": {
+            "optional": true
+        }
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}