adaptive-memory-multi-model-router 2.6.0 → 2.7.0

package/dist/cache/semanticCache.js

@@ -1,140 +1,273 @@
 "use strict";
 /**
- * A3M Router - Semantic Cache
+ * A3M Router - Semantic Cache (Embedding-based)
  *
  * Stores previous query->response pairs and returns cached responses
- * for semantically similar queries using character n-gram Jaccard similarity.
+ * for semantically similar queries using cosine similarity on embeddings.
  *
- * 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"
+ * Supports embedders: nomic (via Ollama), openai, or local Ollama.
+ * Uses nomic-embed-text by default via local Ollama.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SemanticCache = void 0;
+class NomicEmbedder {
+    url;
+    constructor(url = 'http://127.0.0.1:11434/api/embeddings') {
+        this.url = url;
+    }
+    async embed(text) {
+        const response = await fetch(this.url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                model: 'nomic-embed-text',
+                prompt: text,
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`Nomic embedder error: ${response.status} ${response.statusText}`);
+        }
+        const data = await response.json();
+        return data.embedding;
+    }
+}
+class OpenAIEmbedder {
+    apiKey;
+    url;
+    constructor(apiKey, url = 'https://api.openai.com/v1/embeddings') {
+        this.apiKey = apiKey;
+        this.url = url;
+    }
+    async embed(text) {
+        const response = await fetch(this.url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify({
+                model: 'text-embedding-3-small',
+                input: text,
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`OpenAI embedder error: ${response.status} ${response.statusText}`);
+        }
+        const data = await response.json();
+        return data.data[0]?.embedding ?? [];
+    }
+}
+class LocalOllamaEmbedder {
+    baseUrl;
+    model;
+    constructor(baseUrl = 'http://127.0.0.1:11434/api/embeddings', model = 'nomic-embed-text') {
+        this.baseUrl = baseUrl;
+        this.model = model;
+    }
+    async embed(text) {
+        const response = await fetch(this.baseUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                model: this.model,
+                prompt: text,
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`Local Ollama embedder error: ${response.status} ${response.statusText}`);
+        }
+        const data = await response.json();
+        return data.embedding;
+    }
+}
 // ============================================================
-// N-gram utilities
+// Utilities
 // ============================================================
 /**
- * Normalize text: lowercase, collapse whitespace, strip punctuation edges.
+ * Compute cosine similarity between two vectors.
+ */
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length)
+        return 0;
+    if (a.length === 0)
+        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];
+    }
+    const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+    return denominator === 0 ? 0 : dotProduct / denominator;
+}
+/**
+ * Normalize text for hashing: lowercase, collapse whitespace.
  */
 function normalize(text) {
     return text
         .toLowerCase()
-        .replace(/\s+/g, " ")
+        .replace(/\s+/g, ' ')
         .trim();
 }
 /**
- * Extract character trigrams from text.
- * Pads with spaces so short words still produce trigrams.
+ * Simple hash for cache key (deterministic, fast).
  */
-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));
+function hashKey(text) {
+    let hash = 0;
+    const normalized = normalize(text);
+    for (let i = 0; i < normalized.length; i++) {
+        const char = normalized.charCodeAt(i);
+        hash = ((hash << 5) - hash) + char;
+        hash = hash & hash; // Convert to 32-bit integer
     }
-    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;
+    return hash.toString(36) + '_' + normalized.slice(0, 20);
 }
 // ============================================================
 // Semantic Cache
 // ============================================================
 class SemanticCache {
-    entries = [];
-    maxSize;
+    entries = new Map();
+    accessOrder = []; // track LRU order
+    embedder;
     similarityThreshold;
-    ttl;
+    ttlMs;
+    maxEntries;
     hits = 0;
     misses = 0;
-    constructor(options) {
-        this.maxSize = options?.maxSize ?? 1000;
-        this.similarityThreshold = options?.similarityThreshold ?? 0.92;
-        this.ttl = options?.ttl ?? 3600000; // 1 hour
+    constructor(config) {
+        this.similarityThreshold = config.similarityThreshold;
+        this.ttlMs = (config.ttlSeconds || 3600) * 1000;
+        this.maxEntries = config.maxEntries || 1000;
+        // Initialize embedder based on config
+        switch (config.embedder) {
+            case 'openai':
+                if (!config.embedderApiKey) {
+                    throw new Error('OpenAI embedder requires apiKey in config.embedderApiKey');
+                }
+                this.embedder = new OpenAIEmbedder(config.embedderApiKey, config.embedderUrl);
+                break;
+            case 'local':
+                this.embedder = new LocalOllamaEmbedder(config.embedderUrl || 'http://127.0.0.1:11434/api/embeddings', 'nomic-embed-text');
+                break;
+            case 'nomic':
+            default:
+                this.embedder = new NomicEmbedder(config.embedderUrl || 'http://127.0.0.1:11434/api/embeddings');
+                break;
+        }
     }
     /**
      * Get cached response for a semantically similar query.
-     * Returns the best match above the similarity threshold, or null.
+     * Returns the best match above the similarity threshold, or { hit: false }.
      */
     async get(query) {
         const now = Date.now();
-        const queryTrigrams = extractTrigrams(query);
+        // Generate embedding for the query
+        let queryEmbedding;
+        try {
+            queryEmbedding = await this.embedder.embed(query);
+        }
+        catch (error) {
+            console.warn('SemanticCache: Failed to generate embedding for query:', error);
+            this.misses++;
+            return { hit: false };
+        }
         let bestEntry = null;
-        let bestScore = 0;
-        for (const entry of this.entries) {
-            // Skip expired
-            if (now > entry.expiresAt)
+        let bestSimilarity = 0;
+        for (const entry of this.entries.values()) {
+            // Skip expired entries
+            if (now > entry.createdAt + entry.ttl)
                 continue;
-            const score = jaccard(queryTrigrams, entry.trigrams);
-            if (score > bestScore) {
-                bestScore = score;
+            const similarity = cosineSimilarity(queryEmbedding, entry.embedding);
+            if (similarity > bestSimilarity) {
+                bestSimilarity = similarity;
                 bestEntry = entry;
             }
         }
-        if (bestEntry && bestScore >= this.similarityThreshold) {
+        if (bestEntry && bestSimilarity >= this.similarityThreshold) {
             this.hits++;
             bestEntry.hitCount++;
+            bestEntry.lastAccessedAt = now;
+            this.updateAccessOrder(bestEntry.key);
             return {
-                query: bestEntry.query,
+                hit: true,
                 response: bestEntry.response,
-                metadata: bestEntry.metadata,
-                cachedAt: bestEntry.cachedAt,
-                hitCount: bestEntry.hitCount,
+                provider: bestEntry.provider,
+                model: bestEntry.model,
+                cost: bestEntry.cost,
+                similarity: bestSimilarity,
             };
         }
         this.misses++;
-        return null;
+        return { hit: false };
     }
     /**
      * Store a query->response pair in the cache.
      */
     async set(query, response, metadata) {
         const now = Date.now();
-        // Evict expired entries first
+        const key = hashKey(query);
+        // Generate embedding
+        let embedding;
+        try {
+            embedding = await this.embedder.embed(query);
+        }
+        catch (error) {
+            console.warn('SemanticCache: Failed to generate embedding for set:', error);
+            return;
+        }
+        // Evict expired entries
         this.evictExpired();
-        // Evict oldest if at capacity
-        if (this.entries.length >= this.maxSize) {
-            this.evictOldest();
+        // Evict oldest if at capacity (LRU)
+        if (this.entries.size >= this.maxEntries) {
+            this.evictLRU();
         }
-        // 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) {
+        // Check if entry already exists and update it
+        if (this.entries.has(key)) {
+            const existing = this.entries.get(key);
             existing.response = response;
-            existing.metadata = metadata;
-            existing.cachedAt = now;
-            existing.expiresAt = now + this.ttl;
-            existing.trigrams = extractTrigrams(query);
+            existing.embedding = embedding;
+            existing.provider = metadata.provider;
+            existing.model = metadata.model;
+            existing.cost = metadata.cost;
+            existing.createdAt = now;
+            existing.ttl = (metadata.ttl !== undefined ? metadata.ttl : this.ttlMs / 1000) * 1000;
+            existing.lastAccessedAt = now;
+            existing.hitCount = existing.hitCount; // preserve hit count
             return;
         }
-        this.entries.push({
-            query,
+        const entry = {
+            key,
+            embedding,
             response,
-            metadata,
-            cachedAt: now,
-            expiresAt: now + this.ttl,
+            provider: metadata.provider,
+            model: metadata.model,
+            cost: metadata.cost,
+            createdAt: now,
+            ttl: (metadata.ttl !== undefined ? metadata.ttl : this.ttlMs / 1000) * 1000,
             hitCount: 0,
-            trigrams: extractTrigrams(query),
-        });
+            lastAccessedAt: now,
+        };
+        this.entries.set(key, entry);
+        this.accessOrder.push(key);
+    }
+    /**
+     * Delete a specific query from the cache.
+     */
+    async delete(query) {
+        const key = hashKey(query);
+        if (this.entries.has(key)) {
+            this.entries.delete(key);
+            this.accessOrder = this.accessOrder.filter(k => k !== key);
+        }
     }
     /**
      * Clear all cache entries.
      */
     clear() {
-        this.entries = [];
+        this.entries.clear();
+        this.accessOrder = [];
     }
     /**
      * Get cache statistics.
@@ -142,35 +275,46 @@ class SemanticCache {
     getStats() {
         const total = this.hits + this.misses;
         return {
+            size: this.entries.size,
             hits: this.hits,
             misses: this.misses,
             hitRate: total > 0 ? this.hits / total : 0,
-            size: this.entries.length,
         };
     }
+    /**
+     * Update access order for LRU tracking.
+     */
+    updateAccessOrder(key) {
+        this.accessOrder = this.accessOrder.filter(k => k !== key);
+        this.accessOrder.push(key);
+    }
     /**
      * Purge expired entries.
      */
     evictExpired() {
         const now = Date.now();
-        this.entries = this.entries.filter((e) => now <= e.expiresAt);
+        for (const [key, entry] of this.entries.entries()) {
+            if (now > entry.createdAt + entry.ttl) {
+                this.entries.delete(key);
+                this.accessOrder = this.accessOrder.filter(k => k !== key);
+            }
+        }
     }
     /**
-     * Evict the oldest (by cachedAt) entry.
+     * Evict the least recently used entry.
      */
-    evictOldest() {
-        if (this.entries.length === 0)
+    evictLRU() {
+        if (this.accessOrder.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;
-            }
+        const lruKey = this.accessOrder.shift();
+        if (lruKey && this.entries.has(lruKey)) {
+            this.entries.delete(lruKey);
         }
-        this.entries.splice(oldestIdx, 1);
     }
 }
 exports.SemanticCache = SemanticCache;
+// ============================================================
+// Exports
+// ============================================================
+exports.default = SemanticCache;
 //# sourceMappingURL=semanticCache.js.map

package/dist/cache/semanticCache.js.map

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

package/dist/cost/budgetEnforcer.d.ts

@@ -0,0 +1,108 @@
+/**
+ * A3M Router - Budget Enforcer
+ *
+ * Hard budget enforcement for API key spend management:
+ * - Track spend per API key with monthly reset
+ * - Check budget before each request
+ * - Emit alerts at configurable thresholds (50%, 80%, 100%)
+ * - Support hard cap (reject requests) or soft cap (warn only)
+ * - In-memory storage (Redis backup can be added later)
+ */
+import { EventEmitter } from 'events';
+export interface BudgetConfig {
+    apiKey: string;
+    monthlyLimit: number;
+    alertThresholds?: number[];
+    hardCap?: boolean;
+}
+export interface SpendRecord {
+    apiKey: string;
+    spent: number;
+    budget: number;
+    remaining: number;
+    resetDate: Date;
+    alertEmitted: Set<number>;
+}
+export interface BudgetCheckResult {
+    allowed: boolean;
+    reason?: string;
+    remaining: number;
+}
+export declare class BudgetEnforcer extends EventEmitter {
+    private budgets;
+    private spend;
+    private static readonly DEFAULT_THRESHOLDS;
+    constructor();
+    /**
+     * Set budget for an API key
+     */
+    setBudget(apiKey: string, monthlyLimit: number, options?: {
+        alertThresholds?: number[];
+        hardCap?: boolean;
+    }): void;
+    /**
+     * Get current budget config for an API key
+     */
+    getBudgetConfig(apiKey: string): BudgetConfig | undefined;
+    /**
+     * Remove budget config (stops tracking)
+     */
+    removeBudget(apiKey: string): void;
+    /**
+     * Check if a request is allowed within budget
+     * @param apiKey - The API key making the request
+     * @param additionalCost - The cost of the request in cents
+     * @returns BudgetCheckResult with allowed status and remaining budget
+     */
+    checkBudget(apiKey: string, additionalCost: number): BudgetCheckResult;
+    /**
+     * Record spend for an API key
+     * @param apiKey - The API key that incurred the cost
+     * @param cost - The cost in cents
+     */
+    recordSpend(apiKey: string, cost: number): void;
+    /**
+     * Get current spend record for an API key
+     */
+    getSpend(apiKey: string): SpendRecord | undefined;
+    /**
+     * Get all spend records
+     */
+    getAllSpend(): SpendRecord[];
+    /**
+     * Reset budget for an API key (manual reset)
+     */
+    resetBudget(apiKey: string): void;
+    /**
+     * Reset all budgets
+     */
+    resetAll(): void;
+    /**
+     * Update monthly limit for an API key
+     */
+    updateLimit(apiKey: string, monthlyLimit: number): void;
+    /**
+     * Check if reset is needed and perform it
+     */
+    private checkAndReset;
+    /**
+     * Check if monthly reset is due
+     */
+    private isResetDue;
+    /**
+     * Get next monthly reset date
+     */
+    private getNextResetDate;
+    /**
+     * Get days until next reset
+     */
+    getDaysUntilReset(apiKey: string): number | undefined;
+}
+export declare function createBudgetEnforcer(): BudgetEnforcer;
+export declare class BudgetExceededError extends Error {
+    readonly apiKey: string;
+    readonly spent: number;
+    readonly budget: number;
+    readonly remaining: number;
+    constructor(apiKey: string, spent: number, budget: number);
+}