@agentic-qe/v3 3.0.0-alpha.10

package/dist/shared/llm/cache.js

@@ -0,0 +1,368 @@
+/**
+ * Agentic QE v3 - LRU Cache for LLM Responses
+ * ADR-011: LLM Provider System for Quality Engineering
+ *
+ * Provides efficient caching of LLM responses to reduce costs and latency
+ * for repeated queries. Uses LRU (Least Recently Used) eviction policy.
+ */
+/**
+ * Default cache configuration
+ */
+export const DEFAULT_CACHE_CONFIG = {
+    maxSize: 1000,
+    defaultTtlMs: 3600000, // 1 hour
+    enableLRU: true,
+    cacheGenerations: true,
+    cacheEmbeddings: true,
+    cacheCompletions: true,
+};
+/**
+ * LRU Cache implementation for LLM responses
+ */
+export class LLMCache {
+    cache = new Map();
+    accessOrder = [];
+    config;
+    hits = 0;
+    misses = 0;
+    evictions = 0;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CACHE_CONFIG, ...config };
+    }
+    /**
+     * Generate a cache key from request parameters
+     */
+    static generateKey(type, input, options) {
+        const parts = [
+            type,
+            options?.model ?? 'default',
+            String(options?.temperature ?? 0.7),
+            String(options?.maxTokens ?? 0),
+            options?.systemPrompt ?? '',
+            input,
+        ];
+        // Simple hash function
+        const str = parts.join('|');
+        let hash = 0;
+        for (let i = 0; i < str.length; i++) {
+            const char = str.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash = hash & hash;
+        }
+        return `${type}:${Math.abs(hash).toString(36)}`;
+    }
+    /**
+     * Get a cached value
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this.misses++;
+            return undefined;
+        }
+        // Check TTL expiration
+        if (entry.ttlMs > 0) {
+            const age = Date.now() - entry.createdAt.getTime();
+            if (age > entry.ttlMs) {
+                this.delete(key);
+                this.misses++;
+                return undefined;
+            }
+        }
+        // Update access tracking for LRU
+        this.hits++;
+        entry.lastAccessedAt = new Date();
+        entry.accessCount++;
+        if (this.config.enableLRU) {
+            this.updateAccessOrder(key);
+        }
+        return entry.value;
+    }
+    /**
+     * Store a value in the cache
+     */
+    set(key, value, ttlMs) {
+        // Evict if at capacity
+        if (this.cache.size >= this.config.maxSize && !this.cache.has(key)) {
+            this.evictLRU();
+        }
+        const entry = {
+            value,
+            createdAt: new Date(),
+            lastAccessedAt: new Date(),
+            accessCount: 1,
+            ttlMs: ttlMs ?? this.config.defaultTtlMs,
+            keyHash: key,
+        };
+        this.cache.set(key, entry);
+        if (this.config.enableLRU) {
+            this.updateAccessOrder(key);
+        }
+    }
+    /**
+     * Check if a key exists and is not expired
+     */
+    has(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return false;
+        }
+        // Check TTL
+        if (entry.ttlMs > 0) {
+            const age = Date.now() - entry.createdAt.getTime();
+            if (age > entry.ttlMs) {
+                this.delete(key);
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Delete a cached value
+     */
+    delete(key) {
+        const existed = this.cache.delete(key);
+        if (existed) {
+            const index = this.accessOrder.indexOf(key);
+            if (index !== -1) {
+                this.accessOrder.splice(index, 1);
+            }
+        }
+        return existed;
+    }
+    /**
+     * Clear all cached values
+     */
+    clear() {
+        this.cache.clear();
+        this.accessOrder = [];
+        this.hits = 0;
+        this.misses = 0;
+        this.evictions = 0;
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        const totalRequests = this.hits + this.misses;
+        const hitRate = totalRequests > 0 ? this.hits / totalRequests : 0;
+        // Estimate memory usage (rough approximation)
+        let memoryUsageBytes = 0;
+        for (const entry of this.cache.values()) {
+            memoryUsageBytes += this.estimateSize(entry.value);
+        }
+        return {
+            size: this.cache.size,
+            maxSize: this.config.maxSize,
+            hits: this.hits,
+            misses: this.misses,
+            hitRate,
+            evictions: this.evictions,
+            memoryUsageBytes,
+        };
+    }
+    /**
+     * Get all cached keys
+     */
+    keys() {
+        return Array.from(this.cache.keys());
+    }
+    /**
+     * Get entries for export/persistence
+     */
+    entries() {
+        return Array.from(this.cache.entries());
+    }
+    /**
+     * Import entries from persistence
+     */
+    import(entries) {
+        for (const [key, entry] of entries) {
+            // Reconstruct dates
+            entry.createdAt = new Date(entry.createdAt);
+            entry.lastAccessedAt = new Date(entry.lastAccessedAt);
+            this.cache.set(key, entry);
+            this.accessOrder.push(key);
+        }
+        // Evict if over capacity
+        while (this.cache.size > this.config.maxSize) {
+            this.evictLRU();
+        }
+    }
+    /**
+     * Prune expired entries
+     */
+    pruneExpired() {
+        const now = Date.now();
+        let pruned = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.ttlMs > 0) {
+                const age = now - entry.createdAt.getTime();
+                if (age > entry.ttlMs) {
+                    this.delete(key);
+                    pruned++;
+                }
+            }
+        }
+        return pruned;
+    }
+    /**
+     * Update the LRU access order
+     */
+    updateAccessOrder(key) {
+        const index = this.accessOrder.indexOf(key);
+        if (index !== -1) {
+            this.accessOrder.splice(index, 1);
+        }
+        this.accessOrder.push(key);
+    }
+    /**
+     * Evict the least recently used entry
+     */
+    evictLRU() {
+        if (this.accessOrder.length === 0) {
+            // Fallback: delete first entry
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey) {
+                this.cache.delete(firstKey);
+                this.evictions++;
+            }
+            return;
+        }
+        const lruKey = this.accessOrder.shift();
+        if (lruKey) {
+            this.cache.delete(lruKey);
+            this.evictions++;
+        }
+    }
+    /**
+     * Estimate the size of a cached value in bytes
+     */
+    estimateSize(value) {
+        if (value === null || value === undefined) {
+            return 0;
+        }
+        const json = JSON.stringify(value);
+        // 2 bytes per character (UTF-16)
+        return json.length * 2;
+    }
+}
+/**
+ * Specialized cache for LLM responses with request-specific key generation
+ */
+export class LLMResponseCache {
+    generationCache;
+    embeddingCache;
+    completionCache;
+    config;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CACHE_CONFIG, ...config };
+        this.generationCache = new LLMCache(config);
+        this.embeddingCache = new LLMCache(config);
+        this.completionCache = new LLMCache(config);
+    }
+    /**
+     * Get a cached generation response
+     */
+    getGeneration(input, options) {
+        if (!this.config.cacheGenerations) {
+            return undefined;
+        }
+        const key = LLMCache.generateKey('generation', input, options);
+        return this.generationCache.get(key);
+    }
+    /**
+     * Cache a generation response
+     */
+    setGeneration(input, response, options, ttlMs) {
+        if (!this.config.cacheGenerations) {
+            return;
+        }
+        const key = LLMCache.generateKey('generation', input, options);
+        this.generationCache.set(key, response, ttlMs);
+    }
+    /**
+     * Get a cached embedding response
+     */
+    getEmbedding(text, options) {
+        if (!this.config.cacheEmbeddings) {
+            return undefined;
+        }
+        const key = LLMCache.generateKey('embedding', text, options);
+        return this.embeddingCache.get(key);
+    }
+    /**
+     * Cache an embedding response
+     */
+    setEmbedding(text, response, options, ttlMs) {
+        if (!this.config.cacheEmbeddings) {
+            return;
+        }
+        const key = LLMCache.generateKey('embedding', text, options);
+        this.embeddingCache.set(key, response, ttlMs);
+    }
+    /**
+     * Get a cached completion response
+     */
+    getCompletion(prompt, options) {
+        if (!this.config.cacheCompletions) {
+            return undefined;
+        }
+        const key = LLMCache.generateKey('completion', prompt, options);
+        return this.completionCache.get(key);
+    }
+    /**
+     * Cache a completion response
+     */
+    setCompletion(prompt, response, options, ttlMs) {
+        if (!this.config.cacheCompletions) {
+            return;
+        }
+        const key = LLMCache.generateKey('completion', prompt, options);
+        this.completionCache.set(key, response, ttlMs);
+    }
+    /**
+     * Get combined cache statistics
+     */
+    getStats() {
+        const genStats = this.generationCache.getStats();
+        const embStats = this.embeddingCache.getStats();
+        const compStats = this.completionCache.getStats();
+        const totalHits = genStats.hits + embStats.hits + compStats.hits;
+        const totalMisses = genStats.misses + embStats.misses + compStats.misses;
+        const totalRequests = totalHits + totalMisses;
+        return {
+            generation: genStats,
+            embedding: embStats,
+            completion: compStats,
+            total: {
+                size: genStats.size + embStats.size + compStats.size,
+                maxSize: this.config.maxSize * 3,
+                hits: totalHits,
+                misses: totalMisses,
+                hitRate: totalRequests > 0 ? totalHits / totalRequests : 0,
+                evictions: genStats.evictions + embStats.evictions + compStats.evictions,
+                memoryUsageBytes: genStats.memoryUsageBytes +
+                    embStats.memoryUsageBytes +
+                    compStats.memoryUsageBytes,
+            },
+        };
+    }
+    /**
+     * Clear all caches
+     */
+    clear() {
+        this.generationCache.clear();
+        this.embeddingCache.clear();
+        this.completionCache.clear();
+    }
+    /**
+     * Prune expired entries from all caches
+     */
+    pruneExpired() {
+        return (this.generationCache.pruneExpired() +
+            this.embeddingCache.pruneExpired() +
+            this.completionCache.pruneExpired());
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/shared/llm/cache.js.map

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

package/dist/shared/llm/circuit-breaker.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Agentic QE v3 - Circuit Breaker
+ * ADR-011: Resilient LLM Provider System
+ *
+ * Implements the circuit breaker pattern to prevent cascading failures
+ * when LLM providers become unavailable or unreliable.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Failures exceeded threshold, requests rejected immediately
+ * - HALF-OPEN: Testing recovery, limited requests allowed
+ */
+import { CircuitBreakerConfig, CircuitBreakerState, CircuitBreakerStats, LLMProviderType } from './interfaces';
+/**
+ * Default circuit breaker configuration
+ */
+export declare const DEFAULT_CIRCUIT_BREAKER_CONFIG: CircuitBreakerConfig;
+/**
+ * Circuit breaker for protecting LLM provider calls
+ */
+export declare class CircuitBreaker {
+    private state;
+    private failures;
+    private successCount;
+    private totalRequests;
+    private totalSuccesses;
+    private totalFailures;
+    private rejectedCount;
+    private lastFailureTime?;
+    private lastSuccessTime?;
+    private openedAt?;
+    private halfOpenSuccesses;
+    private readonly config;
+    private readonly providerType;
+    constructor(providerType: LLMProviderType, config?: Partial<CircuitBreakerConfig>);
+    /**
+     * Get current circuit breaker state
+     */
+    getState(): CircuitBreakerState;
+    /**
+     * Check if requests are allowed through
+     */
+    canExecute(): boolean;
+    /**
+     * Execute a function with circuit breaker protection
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Record a successful request
+     */
+    recordSuccess(): void;
+    /**
+     * Record a failed request
+     */
+    recordFailure(error: Error): void;
+    /**
+     * Get circuit breaker statistics
+     */
+    getStats(): CircuitBreakerStats;
+    /**
+     * Manually reset the circuit breaker to closed state
+     */
+    reset(): void;
+    /**
+     * Force the circuit to open (for testing or manual intervention)
+     */
+    forceOpen(): void;
+    /**
+     * Force the circuit to half-open (for testing)
+     */
+    forceHalfOpen(): void;
+    /**
+     * Get recent failure messages
+     */
+    getRecentFailures(count?: number): string[];
+    /**
+     * Transition to a new state
+     */
+    private transitionTo;
+    /**
+     * Clean failures outside the time window
+     */
+    private cleanOldFailures;
+    /**
+     * Get time until next state transition
+     */
+    private getTimeUntilTransition;
+}
+/**
+ * Circuit breaker manager for multiple providers
+ */
+export declare class CircuitBreakerManager {
+    private breakers;
+    private readonly defaultConfig;
+    constructor(defaultConfig?: Partial<CircuitBreakerConfig>);
+    /**
+     * Get or create a circuit breaker for a provider
+     */
+    getBreaker(providerType: LLMProviderType, config?: Partial<CircuitBreakerConfig>): CircuitBreaker;
+    /**
+     * Get all circuit breaker statistics
+     */
+    getAllStats(): Record<LLMProviderType, CircuitBreakerStats>;
+    /**
+     * Get providers that are currently available (circuit not open)
+     */
+    getAvailableProviders(): LLMProviderType[];
+    /**
+     * Reset all circuit breakers
+     */
+    resetAll(): void;
+    /**
+     * Reset a specific provider's circuit breaker
+     */
+    reset(providerType: LLMProviderType): void;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/shared/llm/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../../src/shared/llm/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EAEhB,MAAM,cAAc,CAAC;AAEtB;;GAEG;AACH,eAAO,MAAM,8BAA8B,EAAE,oBAM5C,CAAC;AAUF;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,cAAc,CAAa;IACnC,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,eAAe,CAAC,CAAO;IAC/B,OAAO,CAAC,eAAe,CAAC,CAAO;IAC/B,OAAO,CAAC,QAAQ,CAAC,CAAO;IACxB,OAAO,CAAC,iBAAiB,CAAa;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkB;gBAG7C,YAAY,EAAE,eAAe,EAC7B,MAAM,GAAE,OAAO,CAAC,oBAAoB,CAAM;IAM5C;;OAEG;IACH,QAAQ,IAAI,mBAAmB;IAW/B;;OAEG;IACH,UAAU,IAAI,OAAO;IAerB;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA4BlD;;OAEG;IACH,aAAa,IAAI,IAAI;IAerB;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAwCjC;;OAEG;IACH,QAAQ,IAAI,mBAAmB;IAa/B;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb;;OAEG;IACH,SAAS,IAAI,IAAI;IAIjB;;OAEG;IACH,aAAa,IAAI,IAAI;IAIrB;;OAEG;IACH,iBAAiB,CAAC,KAAK,GAAE,MAAU,GAAG,MAAM,EAAE;IAM9C;;OAEG;IACH,OAAO,CAAC,YAAY;IAyBpB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAOxB;;OAEG;IACH,OAAO,CAAC,sBAAsB;CAQ/B;AAED;;GAEG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAmD;IACnE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAuB;gBAEzC,aAAa,GAAE,OAAO,CAAC,oBAAoB,CAAM;IAI7D;;OAEG;IACH,UAAU,CACR,YAAY,EAAE,eAAe,EAC7B,MAAM,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,GACrC,cAAc;IAcjB;;OAEG;IACH,WAAW,IAAI,MAAM,CAAC,eAAe,EAAE,mBAAmB,CAAC;IAU3D;;OAEG;IACH,qBAAqB,IAAI,eAAe,EAAE;IAY1C;;OAEG;IACH,QAAQ,IAAI,IAAI;IAMhB;;OAEG;IACH,KAAK,CAAC,YAAY,EAAE,eAAe,GAAG,IAAI;CAM3C"}