adaptive-memory-multi-model-router 1.9.4 → 2.0.0

package/assets/social-preview.svg

@@ -0,0 +1,64 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 640" width="1280" height="640">
+  <defs>
+    <linearGradient id="spBg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#0f172a"/>
+      <stop offset="100%" style="stop-color:#1e1b4b"/>
+    </linearGradient>
+    <linearGradient id="spAccent" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#6366f1"/>
+      <stop offset="100%" style="stop-color:#06b6d4"/>
+    </linearGradient>
+    <filter id="spGlow">
+      <feGaussianBlur stdDeviation="6" result="blur"/>
+      <feMerge>
+        <feMergeNode in="blur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+  </defs>
+  
+  <!-- Background -->
+  <rect width="1280" height="640" fill="url(#spBg)"/>
+  
+  <!-- Grid Pattern -->
+  <pattern id="spGrid" width="60" height="60" patternUnits="userSpaceOnUse">
+    <path d="M 60 0 L 0 0 0 60" fill="none" stroke="rgba(99,102,241,0.08)" stroke-width="1"/>
+  </pattern>
+  <rect width="1280" height="640" fill="url(#spGrid)"/>
+  
+  <!-- Central Logo -->
+  <g transform="translate(640, 280)">
+    <!-- Outer Rings -->
+    <circle cx="0" cy="0" r="180" fill="none" stroke="url(#spAccent)" stroke-width="2" opacity="0.2"/>
+    <circle cx="0" cy="0" r="150" fill="none" stroke="url(#spAccent)" stroke-width="1" opacity="0.15" stroke-dasharray="10 5"/>
+    
+    <!-- Main Circle -->
+    <circle cx="0" cy="0" r="80" fill="url(#spAccent)" opacity="0.1"/>
+    <circle cx="0" cy="0" r="60" fill="url(#spAccent)" filter="url(#spGlow)"/>
+    
+    <!-- Orbiting Dots -->
+    <circle cx="0" cy="-120" r="15" fill="#6366f1"/>
+    <circle cx="104" cy="60" r="12" fill="#10b981"/>
+    <circle cx="-104" cy="60" r="12" fill="#f59e0b"/>
+    
+    <!-- Connection Lines -->
+    <line x1="0" y1="0" x2="0" y2="-120" stroke="url(#spAccent)" stroke-width="3" opacity="0.6"/>
+    <line x1="0" y1="0" x2="104" y2="60" stroke="url(#spAccent)" stroke-width="3" opacity="0.6"/>
+    <line x1="0" y1="0" x2="-104" y2="60" stroke="url(#spAccent)" stroke-width="3" opacity="0.6"/>
+    
+    <!-- Text -->
+    <text x="0" y="20" font-family="system-ui, -apple-system, sans-serif" font-size="48" font-weight="bold" fill="white" text-anchor="middle">A3M</text>
+  </g>
+  
+  <!-- Title -->
+  <text x="640" y="520" font-family="system-ui, -apple-system, sans-serif" font-size="56" font-weight="bold" fill="white" text-anchor="middle">A3M Router</text>
+  
+  <!-- Subtitle -->
+  <text x="640" y="580" font-family="system-ui, -apple-system, sans-serif" font-size="28" fill="#94a3b8" text-anchor="middle">Adaptive Memory Multi-Model Router</text>
+  
+  <!-- NPM Badge -->
+  <g transform="translate(640, 620)">
+    <rect x="-120" y="-15" width="240" height="30" rx="15" fill="rgba(255,255,255,0.1)"/>
+    <text x="0" y="5" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#cbd5e1" text-anchor="middle">872+ Weekly Downloads on NPM</text>
+  </g>
+</svg>

package/demo/demo-script.md

@@ -0,0 +1,53 @@
+# A3M Router Demo Script for GIF/Video
+
+## Scene 1: Installation (5 seconds)
+```bash
+npm install adaptive-memory-multi-model-router
+```
+Show: Fast installation, dependency count (just nanoid)
+
+## Scene 2: CLI Providers Command (8 seconds)
+```bash
+npx a3m-router providers
+```
+Show: Table of 9 configured providers with checkmarks
+Highlight: Groq, Cerebras, Mistral, CommandCode, OpenCode
+
+## Scene 3: Route Query (10 seconds)
+```bash
+npx a3m-router route "Write Python to sort an array"
+```
+Show: Routing result
+- Primary: groq/llama-3.3-70b
+- Fallbacks: mistral/medium, cerebras/llama
+- Est. Cost: $0.0004
+- Reason: code detected
+
+## Scene 4: Compare Providers (12 seconds)
+```bash
+npx a3m-router compare "What is 2+2?"
+```
+Show: Side-by-side comparison
+- Groq: "4" 450ms $0.0001
+- Cerebras: "4" 380ms $0.0001
+- Mistral: "4" 520ms $0.0002
+
+## Scene 5: Benchmark All (15 seconds)
+```bash
+npx a3m-router benchmark
+```
+Show: Ranking table
+- Fastest: Cerebras 380ms
+- Cheapest: CommandCode FREE
+- Best Quality: Mistral 96%
+
+## Scene 6: Code Example (10 seconds)
+```javascript
+const { createA3MRouter } = require('adaptive-memory-multi-model-router');
+const router = createA3MRouter();
+const result = await router.route("Explain quantum physics");
+console.log(result.primary_model); // "mistral/mistral-large"
+```
+
+## Total Duration: ~60 seconds
+## Tools: terminalizer, asciinema, or simple screen recording

package/dist/analytics/costAnalytics.d.ts

@@ -0,0 +1,77 @@
+/**
+ * A3M Router - Cost Analytics
+ *
+ * Advanced cost tracking and analytics:
+ * - Record every request with full metadata
+ * - Real-time savings vs single premium provider
+ * - Monthly/yearly projections
+ * - Breakdown by provider and query type
+ * - Export to JSON or CSV
+ * - In-memory storage with auto-rotation
+ */
+export interface CostRecord {
+    timestamp: Date;
+    provider: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    cost: number;
+    latency: number;
+    queryType: 'simple' | 'code' | 'summary' | 'complex';
+    cached: boolean;
+}
+export interface CostSummary {
+    totalCost: number;
+    totalRequests: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    avgLatency: number;
+    cacheHitRate: number;
+    period: {
+        start: Date;
+        end: Date;
+    };
+}
+export interface ProviderStats {
+    totalCost: number;
+    totalRequests: number;
+    avgLatency: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    models: Record<string, {
+        cost: number;
+        requests: number;
+    }>;
+}
+export interface QueryTypeStats {
+    totalCost: number;
+    totalRequests: number;
+    avgLatency: number;
+    cachedCount: number;
+    cacheHitRate: number;
+}
+export interface SavingsReport {
+    totalSaved: number;
+    percentageSaved: number;
+    byQueryType: Record<string, {
+        saved: number;
+        percentage: number;
+    }>;
+    projectedMonthlySavings: number;
+    projectedYearlySavings: number;
+}
+export declare class CostAnalytics {
+    private records;
+    private maxRecords;
+    constructor(maxRecords?: number);
+    record(data: Omit<CostRecord, 'timestamp'>): void;
+    getSummary(period?: 'hour' | 'day' | 'week' | 'month'): CostSummary;
+    getByProvider(): Record<string, ProviderStats>;
+    getByQueryType(): Record<string, QueryTypeStats>;
+    getSavings(baselineProvider?: string): SavingsReport;
+    export(format?: 'json' | 'csv'): string;
+    reset(): void;
+    private filterByPeriod;
+    private getDaysCovered;
+}
+export declare function createCostAnalytics(maxRecords?: number): CostAnalytics;

package/dist/analytics/costAnalytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"costAnalytics.d.ts","sourceRoot":"","sources":["../../src/analytics/costAnalytics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IACrD,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE;QAAE,KAAK,EAAE,IAAI,CAAC;QAAC,GAAG,EAAE,IAAI,CAAA;KAAE,CAAC;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnE,uBAAuB,EAAE,MAAM,CAAC;IAChC,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAuBD,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,UAAU,CAAS;gBAEf,UAAU,GAAE,MAAc;IAMtC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,GAAG,IAAI;IAYjD,UAAU,CAAC,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,OAAe,GAAG,WAAW;IA6B1E,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC;IAkC9C,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC;IA2BhD,UAAU,CAAC,gBAAgB,GAAE,MAAiB,GAAG,aAAa;IAiD9D,MAAM,CAAC,MAAM,GAAE,MAAM,GAAG,KAAc,GAAG,MAAM;IAa/C,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,cAAc;CAMvB;AAmBD,wBAAgB,mBAAmB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,aAAa,CAEtE"}

package/dist/analytics/costAnalytics.js

@@ -0,0 +1,219 @@
+"use strict";
+/**
+ * A3M Router - Cost Analytics
+ *
+ * Advanced cost tracking and analytics:
+ * - Record every request with full metadata
+ * - Real-time savings vs single premium provider
+ * - Monthly/yearly projections
+ * - Breakdown by provider and query type
+ * - Export to JSON or CSV
+ * - In-memory storage with auto-rotation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CostAnalytics = void 0;
+exports.createCostAnalytics = createCostAnalytics;
+// Model costs per 1M tokens (USD) for baseline comparison
+const BASELINE_COSTS = {
+    'gpt-4o': { input: 2.50, output: 10.00 },
+    'gpt-4-turbo': { input: 10.00, output: 30.00 },
+    'claude-3.5-sonnet': { input: 3.00, output: 15.00 },
+    'claude-3-opus': { input: 15.00, output: 75.00 },
+    'claude-3-haiku': { input: 0.25, output: 1.25 },
+    'gpt-3.5-turbo': { input: 0.50, output: 1.50 },
+    'gemini-1.5-pro': { input: 1.25, output: 5.00 },
+    'gemini-1.5-flash': { input: 0.075, output: 0.30 },
+    'groq/llama-3.3-70b': { input: 0.59, output: 0.79 },
+    'groq/llama-3.1-8b': { input: 0.05, output: 0.08 },
+    'cerebras/llama-3.3-70b': { input: 0.10, output: 0.10 },
+    'mistral-large': { input: 2.00, output: 6.00 },
+    'mistral-small': { input: 0.20, output: 0.60 },
+};
+// ---------------------------------------------------------------------------
+// CostAnalytics
+// ---------------------------------------------------------------------------
+class CostAnalytics {
+    records = [];
+    maxRecords;
+    constructor(maxRecords = 10000) {
+        this.maxRecords = maxRecords;
+    }
+    // ---- Record ----
+    record(data) {
+        const entry = { ...data, timestamp: new Date() };
+        this.records.push(entry);
+        // Auto-rotate
+        if (this.records.length > this.maxRecords) {
+            this.records = this.records.slice(-this.maxRecords);
+        }
+    }
+    // ---- Summary ----
+    getSummary(period = 'day') {
+        const filtered = this.filterByPeriod(period);
+        if (filtered.length === 0) {
+            const now = new Date();
+            return {
+                totalCost: 0, totalRequests: 0, totalInputTokens: 0, totalOutputTokens: 0,
+                avgLatency: 0, cacheHitRate: 0,
+                period: { start: now, end: now },
+            };
+        }
+        const totalCost = sum(filtered, (r) => r.cost);
+        const cached = filtered.filter((r) => r.cached).length;
+        const start = filtered[0].timestamp;
+        const end = filtered[filtered.length - 1].timestamp;
+        return {
+            totalCost: round(totalCost),
+            totalRequests: filtered.length,
+            totalInputTokens: sum(filtered, (r) => r.inputTokens),
+            totalOutputTokens: sum(filtered, (r) => r.outputTokens),
+            avgLatency: round(sum(filtered, (r) => r.latency) / filtered.length),
+            cacheHitRate: round(cached / filtered.length),
+            period: { start, end },
+        };
+    }
+    // ---- By provider ----
+    getByProvider() {
+        const result = {};
+        for (const r of this.records) {
+            if (!result[r.provider]) {
+                result[r.provider] = {
+                    totalCost: 0, totalRequests: 0, avgLatency: 0,
+                    totalInputTokens: 0, totalOutputTokens: 0, models: {},
+                };
+            }
+            const p = result[r.provider];
+            p.totalCost += r.cost;
+            p.totalRequests++;
+            p.avgLatency += r.latency;
+            p.totalInputTokens += r.inputTokens;
+            p.totalOutputTokens += r.outputTokens;
+            if (!p.models[r.model]) {
+                p.models[r.model] = { cost: 0, requests: 0 };
+            }
+            p.models[r.model].cost += r.cost;
+            p.models[r.model].requests++;
+        }
+        for (const p of Object.values(result)) {
+            if (p.totalRequests > 0) {
+                p.avgLatency = round(p.avgLatency / p.totalRequests);
+            }
+            p.totalCost = round(p.totalCost);
+        }
+        return result;
+    }
+    // ---- By query type ----
+    getByQueryType() {
+        const result = {};
+        for (const r of this.records) {
+            if (!result[r.queryType]) {
+                result[r.queryType] = {
+                    totalCost: 0, totalRequests: 0, avgLatency: 0, cachedCount: 0, cacheHitRate: 0,
+                };
+            }
+            const q = result[r.queryType];
+            q.totalCost += r.cost;
+            q.totalRequests++;
+            q.avgLatency += r.latency;
+            if (r.cached)
+                q.cachedCount++;
+        }
+        for (const q of Object.values(result)) {
+            if (q.totalRequests > 0) {
+                q.avgLatency = round(q.avgLatency / q.totalRequests);
+                q.cacheHitRate = round(q.cachedCount / q.totalRequests);
+            }
+            q.totalCost = round(q.totalCost);
+        }
+        return result;
+    }
+    // ---- Savings ----
+    getSavings(baselineProvider = 'gpt-4o') {
+        const baseline = BASELINE_COSTS[baselineProvider] || { input: 2.50, output: 10.00 };
+        let totalActual = 0;
+        let totalBaseline = 0;
+        const byQueryType = {};
+        for (const r of this.records) {
+            const actualCost = r.cost;
+            const baselineCost = (r.inputTokens / 1_000_000) * baseline.input +
+                (r.outputTokens / 1_000_000) * baseline.output;
+            totalActual += actualCost;
+            totalBaseline += baselineCost;
+            if (!byQueryType[r.queryType]) {
+                byQueryType[r.queryType] = { actual: 0, baseline: 0 };
+            }
+            byQueryType[r.queryType].actual += actualCost;
+            byQueryType[r.queryType].baseline += baselineCost;
+        }
+        const totalSaved = totalBaseline - totalActual;
+        const percentageSaved = totalBaseline > 0 ? (totalSaved / totalBaseline) * 100 : 0;
+        // Project based on days of data we have
+        const daysCovered = this.getDaysCovered();
+        const dailySavings = daysCovered > 0 ? totalSaved / daysCovered : 0;
+        const queryTypeSavings = {};
+        for (const [qt, data] of Object.entries(byQueryType)) {
+            const saved = data.baseline - data.actual;
+            queryTypeSavings[qt] = {
+                saved: round(saved),
+                percentage: data.baseline > 0 ? round((saved / data.baseline) * 100) : 0,
+            };
+        }
+        return {
+            totalSaved: round(totalSaved),
+            percentageSaved: round(percentageSaved),
+            byQueryType: queryTypeSavings,
+            projectedMonthlySavings: round(dailySavings * 30),
+            projectedYearlySavings: round(dailySavings * 365),
+        };
+    }
+    // ---- Export ----
+    export(format = 'json') {
+        if (format === 'csv') {
+            const header = 'timestamp,provider,model,inputTokens,outputTokens,cost,latency,queryType,cached';
+            const rows = this.records.map((r) => `${r.timestamp.toISOString()},${r.provider},${r.model},${r.inputTokens},${r.outputTokens},${r.cost},${r.latency},${r.queryType},${r.cached}`);
+            return [header, ...rows].join('\n');
+        }
+        return JSON.stringify(this.records, null, 2);
+    }
+    // ---- Reset ----
+    reset() {
+        this.records = [];
+    }
+    // ---- Internals ----
+    filterByPeriod(period) {
+        const now = Date.now();
+        const ms = {
+            hour: 3600_000,
+            day: 86400_000,
+            week: 604800_000,
+            month: 2592000_000,
+        };
+        const cutoff = now - (ms[period] || ms.day);
+        return this.records.filter((r) => r.timestamp.getTime() >= cutoff);
+    }
+    getDaysCovered() {
+        if (this.records.length < 2)
+            return 1;
+        const first = this.records[0].timestamp.getTime();
+        const last = this.records[this.records.length - 1].timestamp.getTime();
+        return Math.max(1, (last - first) / 86400_000);
+    }
+}
+exports.CostAnalytics = CostAnalytics;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function sum(arr, fn) {
+    return arr.reduce((acc, r) => acc + fn(r), 0);
+}
+function round(n, decimals = 4) {
+    const factor = Math.pow(10, decimals);
+    return Math.round(n * factor) / factor;
+}
+// ---------------------------------------------------------------------------
+// Convenience factory
+// ---------------------------------------------------------------------------
+function createCostAnalytics(maxRecords) {
+    return new CostAnalytics(maxRecords);
+}
+//# sourceMappingURL=costAnalytics.js.map

package/dist/analytics/costAnalytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"costAnalytics.js","sourceRoot":"","sources":["../../src/analytics/costAnalytics.ts"],"names":[],"mappings":"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"}

package/dist/cache/semanticCache.d.ts

@@ -0,0 +1,62 @@
+/**
+ * A3M Router - Semantic Cache
+ *
+ * Stores previous query->response pairs and returns cached responses
+ * for semantically similar queries using character n-gram Jaccard similarity.
+ *
+ * No external embedding API needed. Trigram overlap catches paraphrases like:
+ *   "What is Python?"    ≈ "Tell me about Python" ≈ "Explain Python"
+ *   "Write a sort fn"    ≈ "Create a sorting fn"  ≈ "How to sort an array"
+ */
+export interface CachedResponse {
+    query: string;
+    response: string;
+    metadata?: any;
+    cachedAt: number;
+    hitCount: number;
+}
+export interface SemanticCacheOptions {
+    maxSize?: number;
+    similarityThreshold?: number;
+    ttl?: number;
+}
+export interface SemanticCacheStats {
+    hits: number;
+    misses: number;
+    hitRate: number;
+    size: number;
+}
+export declare class SemanticCache {
+    private entries;
+    private maxSize;
+    private similarityThreshold;
+    private ttl;
+    private hits;
+    private misses;
+    constructor(options?: SemanticCacheOptions);
+    /**
+     * Get cached response for a semantically similar query.
+     * Returns the best match above the similarity threshold, or null.
+     */
+    get(query: string): Promise<CachedResponse | null>;
+    /**
+     * Store a query->response pair in the cache.
+     */
+    set(query: string, response: string, metadata?: any): Promise<void>;
+    /**
+     * Clear all cache entries.
+     */
+    clear(): void;
+    /**
+     * Get cache statistics.
+     */
+    getStats(): SemanticCacheStats;
+    /**
+     * Purge expired entries.
+     */
+    private evictExpired;
+    /**
+     * Evict the oldest (by cachedAt) entry.
+     */
+    private evictOldest;
+}

package/dist/cache/semanticCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semanticCache.d.ts","sourceRoot":"","sources":["../../src/cache/semanticCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,GAAG,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAOD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AA+CD,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;gBAEP,OAAO,CAAC,EAAE,oBAAoB;IAM1C;;;OAGG;IACG,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAkCxD;;OAEG;IACG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAoCzE;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,QAAQ,IAAI,kBAAkB;IAU9B;;OAEG;IACH,OAAO,CAAC,YAAY;IAKpB;;OAEG;IACH,OAAO,CAAC,WAAW;CAYpB"}

package/dist/cache/semanticCache.js

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * A3M Router - Semantic Cache
+ *
+ * Stores previous query->response pairs and returns cached responses
+ * for semantically similar queries using character n-gram Jaccard similarity.
+ *
+ * No external embedding API needed. Trigram overlap catches paraphrases like:
+ *   "What is Python?"    ≈ "Tell me about Python" ≈ "Explain Python"
+ *   "Write a sort fn"    ≈ "Create a sorting fn"  ≈ "How to sort an array"
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SemanticCache = void 0;
+// ============================================================
+// N-gram utilities
+// ============================================================
+/**
+ * Normalize text: lowercase, collapse whitespace, strip punctuation edges.
+ */
+function normalize(text) {
+    return text
+        .toLowerCase()
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/**
+ * Extract character trigrams from text.
+ * Pads with spaces so short words still produce trigrams.
+ */
+function extractTrigrams(text) {
+    const normalized = " " + normalize(text) + " ";
+    const trigrams = new Set();
+    for (let i = 0; i <= normalized.length - 3; i++) {
+        trigrams.add(normalized.substring(i, i + 3));
+    }
+    return trigrams;
+}
+/**
+ * Compute Jaccard similarity between two sets.
+ * |A ∩ B| / |A ∪ B|
+ */
+function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1.0;
+    let intersection = 0;
+    for (const item of a) {
+        if (b.has(item))
+            intersection++;
+    }
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+// ============================================================
+// Semantic Cache
+// ============================================================
+class SemanticCache {
+    entries = [];
+    maxSize;
+    similarityThreshold;
+    ttl;
+    hits = 0;
+    misses = 0;
+    constructor(options) {
+        this.maxSize = options?.maxSize ?? 1000;
+        this.similarityThreshold = options?.similarityThreshold ?? 0.92;
+        this.ttl = options?.ttl ?? 3600000; // 1 hour
+    }
+    /**
+     * Get cached response for a semantically similar query.
+     * Returns the best match above the similarity threshold, or null.
+     */
+    async get(query) {
+        const now = Date.now();
+        const queryTrigrams = extractTrigrams(query);
+        let bestEntry = null;
+        let bestScore = 0;
+        for (const entry of this.entries) {
+            // Skip expired
+            if (now > entry.expiresAt)
+                continue;
+            const score = jaccard(queryTrigrams, entry.trigrams);
+            if (score > bestScore) {
+                bestScore = score;
+                bestEntry = entry;
+            }
+        }
+        if (bestEntry && bestScore >= this.similarityThreshold) {
+            this.hits++;
+            bestEntry.hitCount++;
+            return {
+                query: bestEntry.query,
+                response: bestEntry.response,
+                metadata: bestEntry.metadata,
+                cachedAt: bestEntry.cachedAt,
+                hitCount: bestEntry.hitCount,
+            };
+        }
+        this.misses++;
+        return null;
+    }
+    /**
+     * Store a query->response pair in the cache.
+     */
+    async set(query, response, metadata) {
+        const now = Date.now();
+        // Evict expired entries first
+        this.evictExpired();
+        // Evict oldest if at capacity
+        if (this.entries.length >= this.maxSize) {
+            this.evictOldest();
+        }
+        // Check if an exact-match entry already exists and update it
+        const normalized = normalize(query);
+        const existing = this.entries.find((e) => normalize(e.query) === normalized && now <= e.expiresAt);
+        if (existing) {
+            existing.response = response;
+            existing.metadata = metadata;
+            existing.cachedAt = now;
+            existing.expiresAt = now + this.ttl;
+            existing.trigrams = extractTrigrams(query);
+            return;
+        }
+        this.entries.push({
+            query,
+            response,
+            metadata,
+            cachedAt: now,
+            expiresAt: now + this.ttl,
+            hitCount: 0,
+            trigrams: extractTrigrams(query),
+        });
+    }
+    /**
+     * Clear all cache entries.
+     */
+    clear() {
+        this.entries = [];
+    }
+    /**
+     * Get cache statistics.
+     */
+    getStats() {
+        const total = this.hits + this.misses;
+        return {
+            hits: this.hits,
+            misses: this.misses,
+            hitRate: total > 0 ? this.hits / total : 0,
+            size: this.entries.length,
+        };
+    }
+    /**
+     * Purge expired entries.
+     */
+    evictExpired() {
+        const now = Date.now();
+        this.entries = this.entries.filter((e) => now <= e.expiresAt);
+    }
+    /**
+     * Evict the oldest (by cachedAt) entry.
+     */
+    evictOldest() {
+        if (this.entries.length === 0)
+            return;
+        let oldestIdx = 0;
+        let oldestTime = Infinity;
+        for (let i = 0; i < this.entries.length; i++) {
+            if (this.entries[i].cachedAt < oldestTime) {
+                oldestTime = this.entries[i].cachedAt;
+                oldestIdx = i;
+            }
+        }
+        this.entries.splice(oldestIdx, 1);
+    }
+}
+exports.SemanticCache = SemanticCache;
+//# sourceMappingURL=semanticCache.js.map