agentdb 1.0.0

package/dist/cache/query-cache.js

@@ -0,0 +1,224 @@
+"use strict";
+/**
+ * Query Cache with LRU eviction for ultra-fast repeated queries
+ *
+ * Provides 50-100x speedup for repeated vector searches by caching results.
+ * Uses LRU (Least Recently Used) eviction strategy with TTL (Time To Live).
+ *
+ * @example
+ * ```typescript
+ * const cache = new QueryCache({ maxSize: 1000, ttl: 300000 }); // 5 min TTL
+ *
+ * // First query: miss, executes full search
+ * const results1 = cache.get(key) ?? performSearch();
+ * cache.set(key, results1);
+ *
+ * // Second query: hit, returns cached results (sub-millisecond)
+ * const results2 = cache.get(key); // 50-100x faster
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryCache = void 0;
+class QueryCache {
+    constructor(config = {}) {
+        this.cache = new Map();
+        // Statistics
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            evictions: 0,
+            totalAccessTime: 0,
+            accessCount: 0
+        };
+        this.config = {
+            maxSize: config.maxSize ?? 1000,
+            ttl: config.ttl ?? 300000, // 5 minutes
+            enableStats: config.enableStats ?? true
+        };
+    }
+    /**
+     * Generate cache key from query parameters
+     */
+    static generateKey(embedding, k, metric, threshold) {
+        // Use first 8 dimensions for key (balance between uniqueness and performance)
+        const prefix = embedding.slice(0, 8).map(v => v.toFixed(4)).join(',');
+        return `${prefix}:${k}:${metric ?? 'cosine'}:${threshold ?? 0}`;
+    }
+    /**
+     * Get cached results if available and not expired
+     */
+    get(key) {
+        const startTime = performance.now();
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this.recordMiss(startTime);
+            return null;
+        }
+        // Check expiry
+        const now = Date.now();
+        if (now > entry.expiry) {
+            this.cache.delete(key);
+            this.recordMiss(startTime);
+            return null;
+        }
+        // Update access metadata
+        entry.lastAccessed = now;
+        entry.accessCount++;
+        this.recordHit(startTime);
+        return entry.results;
+    }
+    /**
+     * Store results in cache with LRU eviction
+     */
+    set(key, results) {
+        // Evict if at capacity
+        if (this.cache.size >= this.config.maxSize) {
+            this.evictLRU();
+        }
+        const now = Date.now();
+        this.cache.set(key, {
+            results,
+            expiry: now + this.config.ttl,
+            lastAccessed: now,
+            accessCount: 1
+        });
+    }
+    /**
+     * Evict least recently used entry
+     */
+    evictLRU() {
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.lastAccessed < oldestTime) {
+                oldestTime = entry.lastAccessed;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+            if (this.config.enableStats) {
+                this.stats.evictions++;
+            }
+        }
+    }
+    /**
+     * Clear all cached entries
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Clear expired entries
+     */
+    clearExpired() {
+        const now = Date.now();
+        const toDelete = [];
+        for (const [key, entry] of this.cache.entries()) {
+            if (now > entry.expiry) {
+                toDelete.push(key);
+            }
+        }
+        toDelete.forEach(key => this.cache.delete(key));
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        const total = this.stats.hits + this.stats.misses;
+        return {
+            hits: this.stats.hits,
+            misses: this.stats.misses,
+            hitRate: total > 0 ? this.stats.hits / total : 0,
+            size: this.cache.size,
+            evictions: this.stats.evictions,
+            avgAccessTime: this.stats.accessCount > 0
+                ? this.stats.totalAccessTime / this.stats.accessCount
+                : 0
+        };
+    }
+    /**
+     * Reset statistics
+     */
+    resetStats() {
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            evictions: 0,
+            totalAccessTime: 0,
+            accessCount: 0
+        };
+    }
+    recordHit(startTime) {
+        if (this.config.enableStats) {
+            this.stats.hits++;
+            this.stats.totalAccessTime += performance.now() - startTime;
+            this.stats.accessCount++;
+        }
+    }
+    recordMiss(startTime) {
+        if (this.config.enableStats) {
+            this.stats.misses++;
+            this.stats.totalAccessTime += performance.now() - startTime;
+            this.stats.accessCount++;
+        }
+    }
+    /**
+     * Get current cache size
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Check if cache has key
+     */
+    has(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return false;
+        // Check expiry
+        if (Date.now() > entry.expiry) {
+            this.cache.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Delete specific entry
+     */
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    /**
+     * Get all cache keys
+     */
+    keys() {
+        return Array.from(this.cache.keys());
+    }
+    /**
+     * Get cache configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update cache configuration
+     */
+    updateConfig(config) {
+        if (config.maxSize !== undefined) {
+            this.config.maxSize = config.maxSize;
+            // Evict excess entries if new size is smaller
+            while (this.cache.size > this.config.maxSize) {
+                this.evictLRU();
+            }
+        }
+        if (config.ttl !== undefined) {
+            this.config.ttl = config.ttl;
+        }
+        if (config.enableStats !== undefined) {
+            this.config.enableStats = config.enableStats;
+        }
+    }
+}
+exports.QueryCache = QueryCache;
+//# sourceMappingURL=query-cache.js.map

package/dist/cache/query-cache.js.map

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

package/dist/cache/query-cache.mjs

@@ -0,0 +1,219 @@
+/**
+ * Query Cache with LRU eviction for ultra-fast repeated queries
+ *
+ * Provides 50-100x speedup for repeated vector searches by caching results.
+ * Uses LRU (Least Recently Used) eviction strategy with TTL (Time To Live).
+ *
+ * @example
+ * ```typescript
+ * const cache = new QueryCache({ maxSize: 1000, ttl: 300000 }); // 5 min TTL
+ *
+ * // First query: miss, executes full search
+ * const results1 = cache.get(key) ?? performSearch();
+ * cache.set(key, results1);
+ *
+ * // Second query: hit, returns cached results (sub-millisecond)
+ * const results2 = cache.get(key); // 50-100x faster
+ * ```
+ */
+export class QueryCache {
+    constructor(config = {}) {
+        this.cache = new Map();
+        // Statistics
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            evictions: 0,
+            totalAccessTime: 0,
+            accessCount: 0
+        };
+        this.config = {
+            maxSize: config.maxSize ?? 1000,
+            ttl: config.ttl ?? 300000, // 5 minutes
+            enableStats: config.enableStats ?? true
+        };
+    }
+    /**
+     * Generate cache key from query parameters
+     */
+    static generateKey(embedding, k, metric, threshold) {
+        // Use first 8 dimensions for key (balance between uniqueness and performance)
+        const prefix = embedding.slice(0, 8).map(v => v.toFixed(4)).join(',');
+        return `${prefix}:${k}:${metric ?? 'cosine'}:${threshold ?? 0}`;
+    }
+    /**
+     * Get cached results if available and not expired
+     */
+    get(key) {
+        const startTime = performance.now();
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this.recordMiss(startTime);
+            return null;
+        }
+        // Check expiry
+        const now = Date.now();
+        if (now > entry.expiry) {
+            this.cache.delete(key);
+            this.recordMiss(startTime);
+            return null;
+        }
+        // Update access metadata
+        entry.lastAccessed = now;
+        entry.accessCount++;
+        this.recordHit(startTime);
+        return entry.results;
+    }
+    /**
+     * Store results in cache with LRU eviction
+     */
+    set(key, results) {
+        // Evict if at capacity
+        if (this.cache.size >= this.config.maxSize) {
+            this.evictLRU();
+        }
+        const now = Date.now();
+        this.cache.set(key, {
+            results,
+            expiry: now + this.config.ttl,
+            lastAccessed: now,
+            accessCount: 1
+        });
+    }
+    /**
+     * Evict least recently used entry
+     */
+    evictLRU() {
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.lastAccessed < oldestTime) {
+                oldestTime = entry.lastAccessed;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+            if (this.config.enableStats) {
+                this.stats.evictions++;
+            }
+        }
+    }
+    /**
+     * Clear all cached entries
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Clear expired entries
+     */
+    clearExpired() {
+        const now = Date.now();
+        const toDelete = [];
+        for (const [key, entry] of this.cache.entries()) {
+            if (now > entry.expiry) {
+                toDelete.push(key);
+            }
+        }
+        toDelete.forEach(key => this.cache.delete(key));
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        const total = this.stats.hits + this.stats.misses;
+        return {
+            hits: this.stats.hits,
+            misses: this.stats.misses,
+            hitRate: total > 0 ? this.stats.hits / total : 0,
+            size: this.cache.size,
+            evictions: this.stats.evictions,
+            avgAccessTime: this.stats.accessCount > 0
+                ? this.stats.totalAccessTime / this.stats.accessCount
+                : 0
+        };
+    }
+    /**
+     * Reset statistics
+     */
+    resetStats() {
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            evictions: 0,
+            totalAccessTime: 0,
+            accessCount: 0
+        };
+    }
+    recordHit(startTime) {
+        if (this.config.enableStats) {
+            this.stats.hits++;
+            this.stats.totalAccessTime += performance.now() - startTime;
+            this.stats.accessCount++;
+        }
+    }
+    recordMiss(startTime) {
+        if (this.config.enableStats) {
+            this.stats.misses++;
+            this.stats.totalAccessTime += performance.now() - startTime;
+            this.stats.accessCount++;
+        }
+    }
+    /**
+     * Get current cache size
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Check if cache has key
+     */
+    has(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return false;
+        // Check expiry
+        if (Date.now() > entry.expiry) {
+            this.cache.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Delete specific entry
+     */
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    /**
+     * Get all cache keys
+     */
+    keys() {
+        return Array.from(this.cache.keys());
+    }
+    /**
+     * Get cache configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update cache configuration
+     */
+    updateConfig(config) {
+        if (config.maxSize !== undefined) {
+            this.config.maxSize = config.maxSize;
+            // Evict excess entries if new size is smaller
+            while (this.cache.size > this.config.maxSize) {
+                this.evictLRU();
+            }
+        }
+        if (config.ttl !== undefined) {
+            this.config.ttl = config.ttl;
+        }
+        if (config.enableStats !== undefined) {
+            this.config.enableStats = config.enableStats;
+        }
+    }
+}

package/dist/cli/cache/query-cache.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Query Cache with LRU eviction for ultra-fast repeated queries
+ *
+ * Provides 50-100x speedup for repeated vector searches by caching results.
+ * Uses LRU (Least Recently Used) eviction strategy with TTL (Time To Live).
+ *
+ * @example
+ * ```typescript
+ * const cache = new QueryCache({ maxSize: 1000, ttl: 300000 }); // 5 min TTL
+ *
+ * // First query: miss, executes full search
+ * const results1 = cache.get(key) ?? performSearch();
+ * cache.set(key, results1);
+ *
+ * // Second query: hit, returns cached results (sub-millisecond)
+ * const results2 = cache.get(key); // 50-100x faster
+ * ```
+ */
+export interface QueryCacheConfig {
+    /** Maximum number of cached queries (default: 1000) */
+    maxSize: number;
+    /** Time-to-live in milliseconds (default: 300000 = 5 minutes) */
+    ttl: number;
+    /** Enable cache statistics tracking (default: true) */
+    enableStats: boolean;
+}
+export interface CacheEntry<T> {
+    results: T;
+    expiry: number;
+    lastAccessed: number;
+    accessCount: number;
+}
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    hitRate: number;
+    size: number;
+    evictions: number;
+    avgAccessTime: number;
+}
+export declare class QueryCache<T = any> {
+    private cache;
+    private config;
+    private stats;
+    constructor(config?: Partial<QueryCacheConfig>);
+    /**
+     * Generate cache key from query parameters
+     */
+    static generateKey(embedding: number[], k: number, metric?: string, threshold?: number): string;
+    /**
+     * Get cached results if available and not expired
+     */
+    get(key: string): T | null;
+    /**
+     * Store results in cache with LRU eviction
+     */
+    set(key: string, results: T): void;
+    /**
+     * Evict least recently used entry
+     */
+    private evictLRU;
+    /**
+     * Clear all cached entries
+     */
+    clear(): void;
+    /**
+     * Clear expired entries
+     */
+    clearExpired(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Reset statistics
+     */
+    resetStats(): void;
+    private recordHit;
+    private recordMiss;
+    /**
+     * Get current cache size
+     */
+    get size(): number;
+    /**
+     * Check if cache has key
+     */
+    has(key: string): boolean;
+    /**
+     * Delete specific entry
+     */
+    delete(key: string): boolean;
+    /**
+     * Get all cache keys
+     */
+    keys(): string[];
+    /**
+     * Get cache configuration
+     */
+    getConfig(): Required<QueryCacheConfig>;
+    /**
+     * Update cache configuration
+     */
+    updateConfig(config: Partial<QueryCacheConfig>): void;
+}