semantic-router-ts 1.0.0

package/dist/index.d.ts

@@ -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 };