@danielsimonjr/memoryjs 1.0.0

package/dist/search/EarlyTerminationManager.js

@@ -0,0 +1,280 @@
+/**
+ * Early Termination Manager
+ *
+ * Phase 12 Sprint 4: Manages early termination of hybrid search when
+ * results are adequate, executing layers in cost-order for efficiency.
+ *
+ * @module search/EarlyTerminationManager
+ */
+import { QueryCostEstimator } from './QueryCostEstimator.js';
+/**
+ * Default options for early termination.
+ */
+const DEFAULT_OPTIONS = {
+    adequacyThreshold: 0.7,
+    minResults: 3,
+    maxResults: 20,
+    semanticAvailable: true,
+    minDiversity: 0.3,
+    minRelevance: 0.4,
+};
+/**
+ * Early Termination Manager
+ *
+ * Executes search layers in cost-order (fastest first) and terminates
+ * early when results are adequate, saving computation time.
+ *
+ * @example
+ * ```typescript
+ * const manager = new EarlyTerminationManager(hybridSearch);
+ * const result = await manager.searchWithEarlyTermination(
+ *   graph,
+ *   'machine learning',
+ *   { adequacyThreshold: 0.8, minResults: 5 }
+ * );
+ *
+ * if (result.earlyTerminated) {
+ *   console.log(`Terminated after ${result.executedLayers.length} layers`);
+ * }
+ * ```
+ */
+export class EarlyTerminationManager {
+    hybridSearch;
+    costEstimator;
+    constructor(hybridSearch, costEstimator) {
+        this.hybridSearch = hybridSearch;
+        this.costEstimator = costEstimator ?? new QueryCostEstimator();
+    }
+    /**
+     * Execute search with early termination support.
+     *
+     * Executes layers in cost-order and terminates early when results
+     * meet the adequacy threshold.
+     *
+     * @param graph - Knowledge graph to search
+     * @param query - Search query
+     * @param options - Early termination options
+     * @returns Search results with termination details
+     */
+    async searchWithEarlyTermination(graph, query, options = {}) {
+        const startTime = Date.now();
+        const opts = { ...DEFAULT_OPTIONS, ...options };
+        const { semanticAvailable, maxResults } = opts;
+        // Get layers sorted by cost (fastest first)
+        const orderedLayers = this.costEstimator.getLayersByCost(query, graph.entities.length, semanticAvailable);
+        const allResults = [];
+        const executedLayers = [];
+        let earlyTerminated = false;
+        // Execute layers in cost order
+        for (const { layer } of orderedLayers) {
+            executedLayers.push(layer);
+            // Execute single layer search
+            const layerResults = await this.executeLayerSearch(graph, query, layer, maxResults);
+            // Merge results (deduplicate by entity name)
+            for (const result of layerResults) {
+                const existing = allResults.find(r => r.entity.name === result.entity.name);
+                if (existing) {
+                    // Update scores if this layer has higher score
+                    if (result.scores.combined > existing.scores.combined) {
+                        Object.assign(existing, result);
+                    }
+                    // Add to matched layers
+                    if (!existing.matchedLayers.includes(layer)) {
+                        existing.matchedLayers.push(layer);
+                    }
+                }
+                else {
+                    // Ensure matchedLayers includes current layer
+                    if (!result.matchedLayers.includes(layer)) {
+                        result.matchedLayers = [...result.matchedLayers, layer];
+                    }
+                    allResults.push(result);
+                }
+            }
+            // Check adequacy
+            const adequacy = this.checkAdequacy(allResults, opts, executedLayers);
+            if (adequacy.adequate) {
+                earlyTerminated = executedLayers.length < orderedLayers.length;
+                break;
+            }
+        }
+        // Final sort by combined score
+        const sortedResults = allResults
+            .sort((a, b) => b.scores.combined - a.scores.combined)
+            .slice(0, maxResults);
+        const finalAdequacy = this.checkAdequacy(sortedResults, opts, executedLayers);
+        return {
+            results: sortedResults,
+            executedLayers,
+            adequacy: finalAdequacy,
+            earlyTerminated,
+            executionTimeMs: Date.now() - startTime,
+        };
+    }
+    /**
+     * Execute a single layer search.
+     * @private
+     */
+    async executeLayerSearch(graph, query, layer, limit) {
+        // Configure weights to emphasize the current layer
+        const weights = this.getLayerWeights(layer);
+        try {
+            return await this.hybridSearch.search(graph, query, {
+                ...weights,
+                limit: limit * 2, // Over-fetch for better merging
+            });
+        }
+        catch {
+            // Layer failed, return empty results
+            return [];
+        }
+    }
+    /**
+     * Get weight configuration for a specific layer.
+     * @private
+     */
+    getLayerWeights(layer) {
+        switch (layer) {
+            case 'semantic':
+                return { semanticWeight: 1.0, lexicalWeight: 0.0, symbolicWeight: 0.0 };
+            case 'lexical':
+                return { semanticWeight: 0.0, lexicalWeight: 1.0, symbolicWeight: 0.0 };
+            case 'symbolic':
+                return { semanticWeight: 0.0, lexicalWeight: 0.0, symbolicWeight: 1.0 };
+        }
+    }
+    /**
+     * Check if results are adequate based on configured thresholds.
+     *
+     * @param results - Current search results
+     * @param options - Adequacy options
+     * @param executedLayers - Layers that have been executed
+     * @returns Adequacy check result
+     */
+    checkAdequacy(results, options, executedLayers) {
+        const opts = { ...DEFAULT_OPTIONS, ...options };
+        const { adequacyThreshold, minResults, minDiversity, minRelevance, analysis, } = opts;
+        const reasons = [];
+        let score = 0;
+        // Weight components
+        const weights = {
+            quantity: 0.35,
+            diversity: 0.25,
+            relevance: 0.25,
+            coverage: 0.15,
+        };
+        // 1. Quantity score (do we have enough results?)
+        const quantityScore = Math.min(results.length / minResults, 1);
+        score += quantityScore * weights.quantity;
+        if (quantityScore < 1) {
+            reasons.push(`Insufficient results: ${results.length}/${minResults}`);
+        }
+        else {
+            reasons.push(`Sufficient results: ${results.length}`);
+        }
+        // 2. Diversity score (variety of entity types and layers)
+        const diversityScore = this.calculateDiversityScore(results);
+        score += Math.min(diversityScore / minDiversity, 1) * weights.diversity;
+        if (diversityScore < minDiversity) {
+            reasons.push(`Low diversity: ${diversityScore.toFixed(2)}/${minDiversity}`);
+        }
+        else {
+            reasons.push(`Good diversity: ${diversityScore.toFixed(2)}`);
+        }
+        // 3. Relevance score (average combined score)
+        const avgRelevance = results.length > 0
+            ? results.reduce((sum, r) => sum + r.scores.combined, 0) / results.length
+            : 0;
+        const relevanceScore = Math.min(avgRelevance / minRelevance, 1);
+        score += relevanceScore * weights.relevance;
+        if (avgRelevance < minRelevance) {
+            reasons.push(`Low relevance: ${avgRelevance.toFixed(2)}/${minRelevance}`);
+        }
+        else {
+            reasons.push(`Good relevance: ${avgRelevance.toFixed(2)}`);
+        }
+        // 4. Coverage score (how many layers contributed)
+        const contributingLayers = this.getContributingLayers(results);
+        const coverageScore = contributingLayers.length / executedLayers.length;
+        score += coverageScore * weights.coverage;
+        if (coverageScore < 0.5) {
+            reasons.push(`Low layer coverage: ${contributingLayers.length}/${executedLayers.length}`);
+        }
+        else {
+            reasons.push(`Good layer coverage: ${contributingLayers.length}/${executedLayers.length}`);
+        }
+        // Bonus for matching required info types (if analysis provided)
+        if (analysis && analysis.requiredInfoTypes.length > 0) {
+            const entityTypes = new Set(results.map(r => r.entity.entityType.toLowerCase()));
+            const matchedTypes = analysis.requiredInfoTypes.filter(t => entityTypes.has(t) ||
+                (t === 'person' && entityTypes.has('person')) ||
+                (t === 'entity' && entityTypes.size > 0));
+            const typeMatchScore = matchedTypes.length / analysis.requiredInfoTypes.length;
+            score += typeMatchScore * 0.1; // Bonus weight
+            reasons.push(`Info type coverage: ${matchedTypes.length}/${analysis.requiredInfoTypes.length}`);
+        }
+        // Normalize score
+        score = Math.min(score, 1);
+        return {
+            adequate: score >= adequacyThreshold,
+            score,
+            reasons,
+            contributingLayers,
+        };
+    }
+    /**
+     * Calculate diversity score from results.
+     * @private
+     */
+    calculateDiversityScore(results) {
+        if (results.length === 0)
+            return 0;
+        // Type diversity
+        const entityTypes = new Set(results.map(r => r.entity.entityType));
+        const typeDiversity = Math.min(entityTypes.size / 3, 1);
+        // Layer diversity
+        const layerCounts = { semantic: 0, lexical: 0, symbolic: 0 };
+        for (const result of results) {
+            for (const layer of result.matchedLayers) {
+                layerCounts[layer]++;
+            }
+        }
+        const activeLayers = Object.values(layerCounts).filter(c => c > 0).length;
+        const layerDiversity = activeLayers / 3;
+        // Combined diversity
+        return (typeDiversity + layerDiversity) / 2;
+    }
+    /**
+     * Get layers that contributed to results.
+     * @private
+     */
+    getContributingLayers(results) {
+        const layers = new Set();
+        for (const result of results) {
+            for (const layer of result.matchedLayers) {
+                layers.add(layer);
+            }
+        }
+        return Array.from(layers);
+    }
+    /**
+     * Calculate adequacy score for a set of results.
+     *
+     * Standalone method for checking result adequacy without full search.
+     *
+     * @param results - Results to evaluate
+     * @param options - Adequacy options
+     * @returns Adequacy score (0-1)
+     */
+    calculateAdequacyScore(results, options = {}) {
+        const allLayers = ['semantic', 'lexical', 'symbolic'];
+        return this.checkAdequacy(results, options, allLayers).score;
+    }
+    /**
+     * Get the cost estimator for external use.
+     */
+    getCostEstimator() {
+        return this.costEstimator;
+    }
+}
+//# sourceMappingURL=EarlyTerminationManager.js.map

package/dist/search/EarlyTerminationManager.js.map

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

package/dist/search/EmbeddingCache.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Embedding Cache
+ *
+ * Phase 12 Sprint 5: LRU cache for embedding vectors with hit/miss tracking,
+ * auto-invalidation on text hash changes, and TTL support.
+ *
+ * @module search/EmbeddingCache
+ */
+/**
+ * Statistics for the embedding cache.
+ */
+export interface EmbeddingCacheStats {
+    /** Number of entries in the cache */
+    size: number;
+    /** Estimated memory usage in bytes */
+    memoryBytes: number;
+    /** Cache hit rate (0-1) */
+    hitRate: number;
+    /** Total cache hits */
+    hits: number;
+    /** Total cache misses */
+    misses: number;
+}
+/**
+ * Options for EmbeddingCache.
+ */
+export interface EmbeddingCacheOptions {
+    /** Maximum number of entries in the cache (default: 1000) */
+    maxSize?: number;
+    /** Time-to-live in milliseconds (default: 3600000 = 1 hour) */
+    ttlMs?: number;
+    /** Dimensions of embedding vectors for memory estimation (default: 384) */
+    dimensions?: number;
+}
+/**
+ * Default cache options.
+ */
+export declare const DEFAULT_EMBEDDING_CACHE_OPTIONS: Required<EmbeddingCacheOptions>;
+/**
+ * LRU cache for embedding vectors with hit/miss tracking.
+ *
+ * Features:
+ * - LRU eviction when max size is reached
+ * - Text hash-based invalidation (detects stale entries)
+ * - TTL support for automatic expiration
+ * - Hit/miss statistics tracking
+ *
+ * @example
+ * ```typescript
+ * const cache = new EmbeddingCache({ maxSize: 500, ttlMs: 60000 });
+ *
+ * // Cache an embedding
+ * cache.set('entity1', 'Original text content', [0.1, 0.2, ...]);
+ *
+ * // Retrieve from cache
+ * const result = cache.get('entity1', 'Original text content');
+ * if (result) {
+ *   console.log('Cache hit!', result);
+ * }
+ *
+ * // Check stats
+ * console.log(cache.getStats()); // { size, memoryBytes, hitRate, hits, misses }
+ * ```
+ */
+export declare class EmbeddingCache {
+    private cache;
+    private options;
+    private hits;
+    private misses;
+    /**
+     * Create a new embedding cache.
+     *
+     * @param options - Cache configuration options
+     */
+    constructor(options?: EmbeddingCacheOptions);
+    /**
+     * Hash a text string for cache invalidation.
+     *
+     * @param text - Text to hash
+     * @returns MD5 hash of the text
+     */
+    private hashText;
+    /**
+     * Check if an entry is expired based on TTL.
+     *
+     * @param entry - Cache entry to check
+     * @returns True if expired
+     */
+    private isExpired;
+    /**
+     * Evict the least recently used entry.
+     */
+    private evictLRU;
+    /**
+     * Get an embedding from the cache.
+     *
+     * Returns null if:
+     * - Key not found
+     * - Entry is expired (TTL)
+     * - Text hash doesn't match (content changed)
+     *
+     * @param key - Cache key (typically entity name)
+     * @param text - Current text content (for hash validation)
+     * @returns Embedding vector if found and valid, null otherwise
+     */
+    get(key: string, text: string): number[] | null;
+    /**
+     * Set an embedding in the cache.
+     *
+     * Automatically evicts LRU entries if max size is reached.
+     *
+     * @param key - Cache key (typically entity name)
+     * @param text - Text content (used for hash-based invalidation)
+     * @param vector - Embedding vector to cache
+     */
+    set(key: string, text: string, vector: number[]): void;
+    /**
+     * Check if a key exists in the cache (without affecting hit/miss stats).
+     *
+     * @param key - Cache key to check
+     * @returns True if key exists (may be expired or stale)
+     */
+    has(key: string): boolean;
+    /**
+     * Delete an entry from the cache.
+     *
+     * @param key - Cache key to delete
+     * @returns True if entry was deleted
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all entries from the cache.
+     */
+    clear(): void;
+    /**
+     * Get cache statistics.
+     *
+     * @returns Cache statistics including size, memory usage, and hit rate
+     */
+    getStats(): EmbeddingCacheStats;
+    /**
+     * Reset hit/miss statistics (useful for benchmarks).
+     */
+    resetStats(): void;
+    /**
+     * Remove expired entries from the cache.
+     *
+     * Called automatically during get operations, but can be
+     * manually triggered for maintenance.
+     *
+     * @returns Number of entries removed
+     */
+    pruneExpired(): number;
+    /**
+     * Get the current cache size.
+     *
+     * @returns Number of entries in the cache
+     */
+    size(): number;
+    /**
+     * Get all cached keys.
+     *
+     * @returns Array of cache keys
+     */
+    keys(): string[];
+    /**
+     * Update options dynamically.
+     *
+     * Note: Reducing maxSize will not immediately evict entries.
+     *
+     * @param options - New options to apply
+     */
+    updateOptions(options: Partial<EmbeddingCacheOptions>): void;
+}
+//# sourceMappingURL=EmbeddingCache.d.ts.map

package/dist/search/EmbeddingCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmbeddingCache.d.ts","sourceRoot":"","sources":["../../src/search/EmbeddingCache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkBH;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,eAAO,MAAM,+BAA+B,EAAE,QAAQ,CAAC,qBAAqB,CAI3E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,MAAM,CAAa;IAE3B;;;;OAIG;gBACS,OAAO,CAAC,EAAE,qBAAqB;IAK3C;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;IAIhB;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAIjB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAgBhB;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IA8B/C;;;;;;;;OAQG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI;IAetD;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;;;OAIG;IACH,QAAQ,IAAI,mBAAmB;IAmB/B;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;;;;;;OAOG;IACH,YAAY,IAAI,MAAM;IAWtB;;;;OAIG;IACH,IAAI,IAAI,MAAM;IAId;;;;OAIG;IACH,IAAI,IAAI,MAAM,EAAE;IAIhB;;;;;;OAMG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,qBAAqB,CAAC,GAAG,IAAI;CAG7D"}