semantic-router-ts 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nilesh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# @anthropic/semantic-router
+
+Superfast semantic routing for LLMs and AI agents. TypeScript port of [aurelio-labs/semantic-router](https://github.com/aurelio-labs/semantic-router).
+
+[![npm version](https://badge.fury.io/js/%40anthropic%2Fsemantic-router.svg)](https://www.npmjs.com/package/@anthropic/semantic-router)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🚀 **Fast** - Uses semantic embeddings for sub-100ms routing decisions
+- 🔌 **Pluggable Encoders** - OpenAI, local Transformers.js, or bring your own
+- 🎯 **Accurate** - Semantic similarity beats keyword matching
+- 📦 **Zero Dependencies** - Core package has no deps; encoders are optional
+- 🔒 **Type Safe** - Full TypeScript support with strict types
+- 🌐 **Offline Support** - LocalEncoder works without API calls
+
+## Installation
+
+```bash
+npm install @anthropic/semantic-router
+
+# For local/offline embeddings (recommended)
+npm install @xenova/transformers
+
+# For OpenAI embeddings
+npm install openai
+```
+
+## Quick Start
+
+```typescript
+import { SemanticRouter, Route, LocalEncoder } from '@anthropic/semantic-router';
+
+// Define your routes
+const routes: Route[] = [
+  {
+    name: 'greeting',
+    utterances: ['hello', 'hi there', 'hey', 'good morning'],
+  },
+  {
+    name: 'farewell', 
+    utterances: ['goodbye', 'bye', 'see you later', 'take care'],
+  },
+  {
+    name: 'help',
+    utterances: ['I need help', 'can you assist me', 'support please'],
+  },
+];
+
+// Create router with local encoder (no API calls)
+const router = new SemanticRouter({
+  routes,
+  encoder: new LocalEncoder(),
+  threshold: 0.4, // Minimum confidence to match
+});
+
+// Initialize (pre-encodes all routes)
+await router.initialize();
+
+// Route queries
+const result = await router.route('hey, how are you doing?');
+console.log(result.name);       // 'greeting'
+console.log(result.confidence); // 0.85
+
+// No match below threshold
+const noMatch = await router.route('what is the weather?');
+console.log(noMatch.name);      // null
+```
+
+## Encoders
+
+### LocalEncoder (Recommended)
+
+Uses [Transformers.js](https://huggingface.co/docs/transformers.js) for fully offline embeddings:
+
+```typescript
+import { LocalEncoder } from '@anthropic/semantic-router';
+
+const encoder = new LocalEncoder({
+  model: 'Xenova/all-MiniLM-L6-v2', // Default, 384 dimensions
+  normalize: true,
+});
+```
+
+Supported models:
+- `Xenova/all-MiniLM-L6-v2` (384d, fast)
+- `Xenova/all-mpnet-base-v2` (768d, more accurate)
+- `Xenova/bge-small-en-v1.5` (384d)
+- `Xenova/bge-base-en-v1.5` (768d)
+
+### OpenAIEncoder
+
+Uses OpenAI's embedding API:
+
+```typescript
+import { OpenAIEncoder } from '@anthropic/semantic-router';
+
+const encoder = new OpenAIEncoder({
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'text-embedding-3-small', // Default
+  dimensions: 1536,
+});
+```
+
+## Configuration
+
+```typescript
+const router = new SemanticRouter({
+  routes: [...],
+  encoder: new LocalEncoder(),
+  
+  // How many similar utterances to consider
+  topK: 5,
+  
+  // How to aggregate scores ('mean' | 'max' | 'sum')
+  aggregation: 'mean',
+  
+  // Minimum confidence threshold (0-1)
+  threshold: 0.4,
+  
+  // Optional LLM for low-confidence fallback
+  llm: myLLMImplementation,
+});
+```
+
+## Dynamic Routes
+
+Add routes at runtime:
+
+```typescript
+await router.addRoute({
+  name: 'billing',
+  utterances: ['payment issue', 'invoice problem', 'billing question'],
+  description: 'Billing and payment related queries',
+});
+```
+
+## LLM Fallback
+
+For ambiguous queries, provide an LLM to classify:
+
+```typescript
+const router = new SemanticRouter({
+  routes,
+  encoder: new LocalEncoder(),
+  threshold: 0.4,
+  llm: {
+    name: 'claude',
+    generate: async (prompt) => {
+      // Your LLM call here
+      return await callClaude(prompt);
+    },
+  },
+});
+```
+
+## API Reference
+
+### SemanticRouter
+
+| Method | Description |
+|--------|-------------|
+| `initialize()` | Pre-encode all routes (call once) |
+| `route(query)` | Route a query, returns `RouteMatch` |
+| `classify(query)` | Shorthand, returns route name or null |
+| `addRoute(route)` | Add a route dynamically |
+| `getStats()` | Get router statistics |
+| `isReady()` | Check if initialized |
+
+### RouteMatch
+
+```typescript
+interface RouteMatch {
+  route: Route | null;    // Full route object
+  name: string | null;    // Route name
+  confidence: number;     // 0-1 score
+  scores?: RouteScore[];  // All route scores
+}
+```
+
+## Acknowledgments
+
+This is a TypeScript port of the excellent [semantic-router](https://github.com/aurelio-labs/semantic-router) by Aurelio Labs.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,272 @@
+/**
+ * Route - A semantic route definition
+ *
+ * Routes define decision paths that the router can choose based on
+ * semantic similarity to user queries.
+ */
+interface Route {
+    /** Unique identifier for this route */
+    name: string;
+    /** Example utterances that should trigger this route */
+    utterances: string[];
+    /** Optional description for documentation */
+    description?: string;
+    /** Optional metadata to attach to route matches */
+    metadata?: Record<string, unknown>;
+    /** Optional function schema for tool calling */
+    functionSchema?: FunctionSchema;
+}
+interface FunctionSchema {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+}
+/**
+ * RouteMatch - Result of routing a query
+ */
+interface RouteMatch {
+    /** The matched route, or null if no match */
+    route: Route | null;
+    /** Name of the matched route */
+    name: string | null;
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** All scored routes for debugging */
+    scores?: RouteScore[];
+}
+interface RouteScore {
+    name: string;
+    score: number;
+}
+/**
+ * RouterConfig - Configuration for SemanticRouter
+ */
+interface RouterConfig {
+    /** Routes to register */
+    routes?: Route[];
+    /** Encoder to use for embeddings */
+    encoder?: Encoder;
+    /** Number of top matches to consider */
+    topK?: number;
+    /** Score aggregation method */
+    aggregation?: 'mean' | 'max' | 'sum';
+    /** Minimum score to consider a match */
+    threshold?: number;
+}
+/**
+ * Encoder - Interface for embedding providers
+ */
+interface Encoder {
+    /** Encode a single text */
+    encode(text: string): Promise<number[]>;
+    /** Encode multiple texts (batch) */
+    encodeBatch(texts: string[]): Promise<number[][]>;
+    /** Encoder name for logging */
+    readonly name: string;
+    /** Embedding dimensions */
+    readonly dimensions: number;
+}
+/**
+ * Index - Interface for vector storage
+ */
+interface Index {
+    /** Add embeddings with route names */
+    add(embeddings: number[][], routes: string[], utterances: string[]): Promise<void>;
+    /** Query for similar embeddings */
+    query(embedding: number[], topK: number): Promise<IndexMatch[]>;
+    /** Clear all stored data */
+    clear(): Promise<void>;
+    /** Check if index is ready */
+    isReady(): boolean;
+}
+interface IndexMatch {
+    route: string;
+    utterance: string;
+    score: number;
+}
+/**
+ * LLM - Interface for LLM fallback
+ */
+interface LLM {
+    /** Generate a response */
+    generate(prompt: string): Promise<string>;
+    /** LLM name for logging */
+    readonly name: string;
+}
+
+/**
+ * SemanticRouter - Fast decision-making layer for LLMs
+ *
+ * Port of Python semantic_router.routers.semantic
+ *
+ * Uses semantic vector space to route queries to the best matching route
+ * based on similarity to pre-encoded utterances.
+ */
+
+interface SemanticRouterConfig extends RouterConfig {
+    /** Optional LLM for fallback classification */
+    llm?: LLM;
+}
+declare class SemanticRouter {
+    private routes;
+    private encoder;
+    private index;
+    private llm?;
+    private topK;
+    private aggregation;
+    private threshold;
+    private initialized;
+    private initPromise;
+    constructor(config?: SemanticRouterConfig);
+    /**
+     * Initialize the router by encoding all routes.
+     * Safe to call multiple times.
+     */
+    initialize(): Promise<void>;
+    private doInitialize;
+    /**
+     * Route a query to the best matching route.
+     */
+    route(query: string): Promise<RouteMatch>;
+    /**
+     * Shorthand to get just the route name
+     */
+    classify(query: string): Promise<string | null>;
+    /**
+     * Add a route dynamically
+     */
+    addRoute(route: Route): Promise<void>;
+    /**
+     * Aggregate scores from multiple matches by route
+     */
+    private aggregateScores;
+    /**
+     * Use LLM to classify when similarity is low
+     */
+    private llmFallback;
+    /**
+     * Return a no-match result
+     */
+    private noMatch;
+    /**
+     * Get router statistics
+     */
+    getStats(): {
+        routeCount: number;
+        routes: string[];
+        encoder: string;
+        threshold: number;
+        initialized: boolean;
+    };
+    /**
+     * Check if router is ready
+     */
+    isReady(): boolean;
+}
+
+/**
+ * BaseEncoder - Abstract base class for all encoders
+ *
+ * Port of Python semantic_router.encoders.base
+ */
+
+declare abstract class BaseEncoder implements Encoder {
+    abstract readonly name: string;
+    abstract readonly dimensions: number;
+    protected initialized: boolean;
+    /**
+     * Encode a single text into an embedding vector.
+     */
+    abstract encode(text: string): Promise<number[]>;
+    /**
+     * Encode multiple texts in batch.
+     * Default implementation calls encode() for each, but subclasses
+     * can override for more efficient batch processing.
+     */
+    encodeBatch(texts: string[]): Promise<number[][]>;
+    /**
+     * Normalize an embedding vector to unit length.
+     */
+    protected normalize(embedding: number[]): number[];
+}
+
+/**
+ * LocalEncoder - Offline embedding using Transformers.js
+ *
+ * Uses Xenova/all-MiniLM-L6-v2 by default (384 dimensions).
+ * Runs entirely locally with no API calls.
+ */
+
+interface LocalEncoderConfig {
+    /** Model to use (default: Xenova/all-MiniLM-L6-v2) */
+    model?: string;
+    /** Whether to normalize embeddings (default: true) */
+    normalize?: boolean;
+}
+declare class LocalEncoder extends BaseEncoder {
+    readonly name = "LocalEncoder";
+    readonly dimensions: number;
+    private model;
+    private embedder;
+    private initPromise;
+    private shouldNormalize;
+    private static readonly MODEL_DIMENSIONS;
+    constructor(config?: LocalEncoderConfig);
+    private ensureInitialized;
+    private initialize;
+    encode(text: string): Promise<number[]>;
+    encodeBatch(texts: string[]): Promise<number[][]>;
+}
+
+/**
+ * OpenAIEncoder - Embedding using OpenAI API
+ *
+ * Uses text-embedding-3-small by default (1536 dimensions).
+ */
+
+interface OpenAIEncoderConfig {
+    /** OpenAI API key */
+    apiKey?: string;
+    /** Model to use (default: text-embedding-3-small) */
+    model?: string;
+    /** Embedding dimensions (for ada-3 models that support it) */
+    dimensions?: number;
+}
+declare class OpenAIEncoder extends BaseEncoder {
+    readonly name = "OpenAIEncoder";
+    readonly dimensions: number;
+    private model;
+    private apiKey;
+    private client;
+    private static readonly MODEL_DIMENSIONS;
+    constructor(config?: OpenAIEncoderConfig);
+    private ensureClient;
+    encode(text: string): Promise<number[]>;
+    encodeBatch(texts: string[]): Promise<number[][]>;
+}
+
+/**
+ * LocalIndex - In-memory vector storage
+ *
+ * Simple, fast index for development and small-scale use.
+ * Port of Python semantic_router.index.local
+ */
+
+declare class LocalIndex implements Index {
+    private vectors;
+    private ready;
+    add(embeddings: number[][], routes: string[], utterances: string[]): Promise<void>;
+    query(embedding: number[], topK: number): Promise<IndexMatch[]>;
+    clear(): Promise<void>;
+    isReady(): boolean;
+    /**
+     * Get number of stored vectors
+     */
+    get size(): number;
+    /**
+     * Cosine similarity between two vectors
+     */
+    private cosineSimilarity;
+}
+
+export { BaseEncoder, type Encoder, type FunctionSchema, type Index, type IndexMatch, type LLM, LocalEncoder, type LocalEncoderConfig, LocalIndex, OpenAIEncoder, type OpenAIEncoderConfig, type Route, type RouteMatch, type RouteScore, type RouterConfig, SemanticRouter, type SemanticRouterConfig };