adaptive-memory-multi-model-router 1.9.5 → 2.0.1

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

package/dist/cache/semanticCache.js.map

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

package/dist/cli.js

@@ -3,6 +3,7 @@
  * A3M Router CLI - Adaptive Memory Multi-Model Router
  * 
  * Commands:
+ *   npx a3m-router serve [--port 8787]     Start OpenAI-compatible proxy server
  *   npx a3m-router route <query>           Route query to best provider
  *   npx a3m-router batch <q1> <q2>..       Route multiple queries
  *   npx a3m-router providers               List all configured providers
@@ -24,6 +25,13 @@ const {
   getAvailableProviders, providerConfig, registerProvider, loadProviders,
 } = require('./index.js');
 
+let createProxyServer;
+try {
+  createProxyServer = require('./server/proxyServer.js').createProxyServer;
+} catch (e) {
+  // Server module not yet compiled
+}
+
 const args = process.argv.slice(2);
 const command = args[0];
 
@@ -394,11 +402,36 @@ async function main() {
       break;
     }
 
+    case 'serve': {
+      if (!createProxyServer) {
+        console.error('\n  Error: Server module not available.');
+        console.error('  Build first: npm run build');
+        console.error('  Or use directly: node -e "require(\'./server/proxyServer.js\').createProxyServer()"\n');
+        process.exit(1);
+      }
+
+      // Parse --port argument
+      var portArg = args.indexOf('--port');
+      var port = undefined;
+      if (portArg !== -1 && args[portArg + 1]) {
+        port = parseInt(args[portArg + 1], 10);
+        if (isNaN(port)) {
+          console.error('  Error: --port must be a number');
+          process.exit(1);
+        }
+      }
+
+      console.log('\n  Starting A3M Router Proxy Server...');
+      createProxyServer(port);
+      break;
+    }
+
     default:
       console.log('\n🔀 A3M Router — Adaptive Memory Multi-Model Router');
       console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
       console.log('');
       console.log('  Commands:');
+      console.log('    serve [--port 8787]    Start OpenAI-compatible proxy server');
       console.log('    route <query>          Route query to best provider');
       console.log('    batch <q1> <q2>..      Route multiple queries');
       console.log('    compare <query>        Compare providers side by side');
@@ -420,6 +453,8 @@ async function main() {
       console.log('  Env:    GROQ_API_KEY, CEREBRAS_API_KEY, MISTRAL_API_KEY, etc.');
       console.log('');
       console.log('  Examples:');
+      console.log('    npx a3m-router serve                        # Start proxy on :8787');
+      console.log('    npx a3m-router serve --port 3000            # Start proxy on :3000');
       console.log('    npx a3m-router route "Write a Python function to sort"');
       console.log('    npx a3m-router compare "What is 2+2?"');
       console.log('    npx a3m-router providers');