@danielsimonjr/memoryjs 1.0.0 → 1.2.0

package/dist/search/FuzzySearch.js

@@ -1,313 +0,0 @@
-/**
- * Fuzzy Search
- *
- * Search with typo tolerance using Levenshtein distance similarity.
- * Uses workerpool for parallel processing on large datasets.
- *
- * @module search/FuzzySearch
- */
-import { levenshteinDistance } from '../utils/index.js';
-import { SEARCH_LIMITS } from '../utils/constants.js';
-import { SearchFilterChain } from './SearchFilterChain.js';
-import workerpool from '@danielsimonjr/workerpool';
-import { fileURLToPath } from 'url';
-import { dirname, join, sep } from 'path';
-/**
- * Default fuzzy search similarity threshold (70% match required).
- * Lower values are more permissive (more typos tolerated).
- * Higher values are stricter (fewer typos tolerated).
- */
-export const DEFAULT_FUZZY_THRESHOLD = 0.7;
-/**
- * Phase 4 Sprint 3: Maximum cache size to prevent memory bloat.
- */
-const FUZZY_CACHE_MAX_SIZE = 100;
-/**
- * Phase 4 Sprint 3: Cache TTL in milliseconds (5 minutes).
- */
-const FUZZY_CACHE_TTL_MS = 5 * 60 * 1000;
-/**
- * Phase 7 Sprint 3: Minimum number of entities to activate worker pool.
- */
-const WORKER_MIN_ENTITIES = 500;
-/**
- * Phase 7 Sprint 3: Maximum threshold for worker pool activation.
- * Higher thresholds have fewer matches, so single-threaded is faster.
- */
-const WORKER_MAX_THRESHOLD = 0.8;
-/**
- * Performs fuzzy search with configurable similarity threshold.
- */
-export class FuzzySearch {
-    storage;
-    /**
-     * Phase 4 Sprint 3: Result cache for fuzzy search.
-     * Maps cache key -> cached entity names.
-     */
-    fuzzyResultCache = new Map();
-    /**
-     * Phase 8: Worker pool using workerpool library.
-     * Initialized lazily when needed.
-     */
-    workerPool = null;
-    /**
-     * Phase 7 Sprint 3: Path to the worker script.
-     */
-    workerPath;
-    /**
-     * Phase 8: Whether to use worker pool for parallel processing.
-     * Can be disabled for testing or when workers are not available.
-     */
-    useWorkerPool;
-    constructor(storage, options = {}) {
-        this.storage = storage;
-        this.useWorkerPool = options.useWorkerPool ?? true;
-        // Calculate worker path using ESM module resolution
-        const currentFileUrl = import.meta.url;
-        const currentDir = dirname(fileURLToPath(currentFileUrl));
-        // Check if we're running from src/ (during tests) or dist/ (production)
-        const isRunningFromSrc = currentDir.includes(`${sep}src${sep}`);
-        if (isRunningFromSrc) {
-            // During tests, worker is in dist/workers/ relative to project root
-            const projectRoot = join(currentDir, '..', '..');
-            this.workerPath = join(projectRoot, 'dist', 'workers', 'levenshteinWorker.js');
-        }
-        else {
-            // In production, worker is in dist/workers/ relative to current dist/search/
-            this.workerPath = join(currentDir, '..', 'workers', 'levenshteinWorker.js');
-        }
-    }
-    /**
-     * Phase 4 Sprint 3: Generate cache key for fuzzy search parameters.
-     */
-    generateCacheKey(query, threshold, tags, minImportance, maxImportance, offset, limit) {
-        return JSON.stringify({
-            q: query.toLowerCase(),
-            t: threshold,
-            tags: tags?.sort().join(',') ?? '',
-            min: minImportance,
-            max: maxImportance,
-            off: offset,
-            lim: limit,
-        });
-    }
-    /**
-     * Phase 4 Sprint 3: Clear the fuzzy search cache.
-     */
-    clearCache() {
-        this.fuzzyResultCache.clear();
-    }
-    /**
-     * Phase 4 Sprint 3: Invalidate stale cache entries.
-     */
-    cleanupCache() {
-        const now = Date.now();
-        const entries = Array.from(this.fuzzyResultCache.entries());
-        // Remove expired entries
-        for (const [key, entry] of entries) {
-            if (now - entry.timestamp > FUZZY_CACHE_TTL_MS) {
-                this.fuzzyResultCache.delete(key);
-            }
-        }
-        // If still over limit, remove oldest entries
-        if (this.fuzzyResultCache.size > FUZZY_CACHE_MAX_SIZE) {
-            const sortedEntries = entries
-                .filter(([k]) => this.fuzzyResultCache.has(k))
-                .sort((a, b) => a[1].timestamp - b[1].timestamp);
-            const toRemove = sortedEntries.slice(0, this.fuzzyResultCache.size - FUZZY_CACHE_MAX_SIZE);
-            for (const [key] of toRemove) {
-                this.fuzzyResultCache.delete(key);
-            }
-        }
-    }
-    /**
-     * Fuzzy search for entities with typo tolerance and pagination.
-     *
-     * Uses Levenshtein distance to calculate similarity between strings.
-     * Matches if similarity >= threshold (0.0 to 1.0).
-     *
-     * Phase 4 Sprint 3: Implements result caching for repeated queries.
-     *
-     * @param query - Search query
-     * @param threshold - Similarity threshold (0.0 to 1.0), default DEFAULT_FUZZY_THRESHOLD
-     * @param tags - Optional tags filter
-     * @param minImportance - Optional minimum importance
-     * @param maxImportance - Optional maximum importance
-     * @param offset - Number of results to skip (default: 0)
-     * @param limit - Maximum number of results (default: 50, max: 200)
-     * @returns Filtered knowledge graph with fuzzy matches and pagination applied
-     */
-    async fuzzySearch(query, threshold = DEFAULT_FUZZY_THRESHOLD, tags, minImportance, maxImportance, offset = 0, limit = SEARCH_LIMITS.DEFAULT) {
-        const graph = await this.storage.loadGraph();
-        const queryLower = query.toLowerCase();
-        // Phase 4 Sprint 3: Generate cache key and check cache
-        const cacheKey = this.generateCacheKey(query, threshold, tags, minImportance, maxImportance, offset, limit);
-        const cached = this.fuzzyResultCache.get(cacheKey);
-        // Check if cache is valid (entity count hasn't changed)
-        if (cached && cached.entityCount === graph.entities.length) {
-            const now = Date.now();
-            if (now - cached.timestamp < FUZZY_CACHE_TTL_MS) {
-                // Return cached results
-                const cachedNameSet = new Set(cached.entityNames);
-                const cachedEntities = graph.entities.filter(e => cachedNameSet.has(e.name));
-                const cachedEntityNames = new Set(cached.entityNames);
-                const cachedRelations = graph.relations.filter(r => cachedEntityNames.has(r.from) && cachedEntityNames.has(r.to));
-                return { entities: cachedEntities, relations: cachedRelations };
-            }
-        }
-        // Phase 7 Sprint 3: Use worker pool for large graphs with low thresholds
-        // Phase 8: Respect useWorkerPool flag for testing
-        const shouldUseWorkers = this.useWorkerPool &&
-            graph.entities.length >= WORKER_MIN_ENTITIES &&
-            threshold < WORKER_MAX_THRESHOLD;
-        let fuzzyMatched;
-        if (shouldUseWorkers) {
-            fuzzyMatched = await this.searchWithWorkers(query, threshold, graph.entities);
-        }
-        else {
-            // Perform single-threaded fuzzy search
-            fuzzyMatched = this.performFuzzyMatch(graph.entities, queryLower, threshold);
-        }
-        // Apply tag and importance filters using SearchFilterChain
-        const filters = { tags, minImportance, maxImportance };
-        const filteredEntities = SearchFilterChain.applyFilters(fuzzyMatched, filters);
-        // Apply pagination using SearchFilterChain
-        const pagination = SearchFilterChain.validatePagination(offset, limit);
-        const paginatedEntities = SearchFilterChain.paginate(filteredEntities, pagination);
-        // Phase 4 Sprint 3: Cache the results
-        this.fuzzyResultCache.set(cacheKey, {
-            entityNames: paginatedEntities.map(e => e.name),
-            entityCount: graph.entities.length,
-            timestamp: Date.now(),
-        });
-        // Cleanup old cache entries periodically
-        if (this.fuzzyResultCache.size > FUZZY_CACHE_MAX_SIZE / 2) {
-            this.cleanupCache();
-        }
-        const filteredEntityNames = new Set(paginatedEntities.map(e => e.name));
-        const filteredRelations = graph.relations.filter(r => filteredEntityNames.has(r.from) && filteredEntityNames.has(r.to));
-        return {
-            entities: paginatedEntities,
-            relations: filteredRelations,
-        };
-    }
-    /**
-     * Phase 4 Sprint 3: Perform the actual fuzzy matching logic.
-     * Extracted from fuzzySearch for cleaner code structure.
-     */
-    performFuzzyMatch(entities, queryLower, threshold) {
-        return entities.filter(e => {
-            const lowercased = this.storage.getLowercased(e.name);
-            // Check name match (use pre-computed lowercase)
-            const nameLower = lowercased?.name ?? e.name.toLowerCase();
-            if (this.isFuzzyMatchLower(nameLower, queryLower, threshold))
-                return true;
-            // Check type match (use pre-computed lowercase)
-            const typeLower = lowercased?.entityType ?? e.entityType.toLowerCase();
-            if (this.isFuzzyMatchLower(typeLower, queryLower, threshold))
-                return true;
-            // Check observations (use pre-computed lowercase array)
-            const obsLower = lowercased?.observations ?? e.observations.map(o => o.toLowerCase());
-            return obsLower.some(o => 
-            // For observations, split into words and check each word
-            o
-                .split(/\s+/)
-                .some(word => this.isFuzzyMatchLower(word, queryLower, threshold)) ||
-                // Also check if the observation contains the query
-                this.isFuzzyMatchLower(o, queryLower, threshold));
-        });
-    }
-    /**
-     * Check if two already-lowercase strings match with fuzzy logic.
-     *
-     * OPTIMIZED: Skips toLowerCase() calls when strings are already lowercase.
-     *
-     * @param s1 - First string (already lowercase)
-     * @param s2 - Second string (already lowercase)
-     * @param threshold - Similarity threshold (0.0 to 1.0)
-     * @returns True if strings match fuzzily
-     */
-    isFuzzyMatchLower(s1, s2, threshold = 0.7) {
-        // Exact match
-        if (s1 === s2)
-            return true;
-        // One contains the other
-        if (s1.includes(s2) || s2.includes(s1))
-            return true;
-        // Calculate similarity using Levenshtein distance
-        const distance = levenshteinDistance(s1, s2);
-        const maxLength = Math.max(s1.length, s2.length);
-        const similarity = 1 - distance / maxLength;
-        return similarity >= threshold;
-    }
-    /**
-     * Phase 8: Perform fuzzy search using workerpool for parallel processing.
-     *
-     * Splits entities into chunks and processes them in parallel using worker threads.
-     * Falls back to single-threaded search if worker execution fails.
-     *
-     * @param query - Search query
-     * @param threshold - Similarity threshold
-     * @param entities - Entities to search
-     * @returns Array of matched entities
-     */
-    async searchWithWorkers(query, threshold, entities) {
-        try {
-            // Initialize worker pool lazily using workerpool
-            if (!this.workerPool) {
-                // Enable ESM module support for Node.js 20+
-                // The 'type: module' option is needed for ESM workers but may not be in @types/node
-                const workerThreadOpts = { type: 'module' };
-                this.workerPool = workerpool.pool(this.workerPath, {
-                    maxWorkers: Math.max(1, workerpool.cpus - 1),
-                    workerType: 'thread',
-                    workerThreadOpts,
-                });
-            }
-            // Split entities into chunks based on CPU count
-            const numWorkers = Math.max(1, workerpool.cpus - 1);
-            const chunkSize = Math.ceil(entities.length / numWorkers);
-            const chunks = [];
-            for (let i = 0; i < entities.length; i += chunkSize) {
-                chunks.push(entities.slice(i, i + chunkSize));
-            }
-            // Prepare worker inputs with lowercased data
-            const workerInputs = chunks.map(chunk => ({
-                query,
-                threshold,
-                entities: chunk.map(e => ({
-                    name: e.name,
-                    nameLower: e.name.toLowerCase(),
-                    observations: e.observations.map(o => o.toLowerCase()),
-                })),
-            }));
-            // Execute all chunks in parallel using workerpool with timeout
-            const WORKER_TIMEOUT_MS = 30000; // 30 seconds
-            const results = await Promise.all(workerInputs.map(input => this.workerPool.exec('searchEntities', [input])
-                .timeout(WORKER_TIMEOUT_MS)));
-            // Flatten results and extract matched entity names
-            const matchedNames = new Set(results.flat().map(r => r.name));
-            // Return entities that matched
-            return entities.filter(e => matchedNames.has(e.name));
-        }
-        catch (error) {
-            // Worker execution failed - fall back to single-threaded mode
-            console.warn(`Worker pool execution failed, falling back to single-threaded fuzzy search: ${error instanceof Error ? error.message : String(error)}`);
-            // Use the existing single-threaded implementation
-            const queryLower = query.toLowerCase();
-            return this.performFuzzyMatch(entities, queryLower, threshold);
-        }
-    }
-    /**
-     * Phase 8: Shutdown the worker pool and clean up resources.
-     *
-     * Should be called when FuzzySearch is no longer needed.
-     */
-    async shutdown() {
-        if (this.workerPool) {
-            await this.workerPool.terminate();
-            this.workerPool = null;
-        }
-    }
-}
-//# sourceMappingURL=FuzzySearch.js.map

package/dist/search/FuzzySearch.js.map

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

package/dist/search/HybridScorer.d.ts

@@ -1,181 +0,0 @@
-/**
- * Hybrid Scorer
- *
- * Combines semantic, lexical, and symbolic search scores with
- * min-max normalization and configurable weights.
- *
- * Phase 12 Sprint 3: Search Algorithm Optimization
- *
- * @module search/HybridScorer
- */
-import type { Entity } from '../types/index.js';
-/**
- * Result from semantic search layer.
- */
-export interface SemanticLayerResult {
-    /** Entity name */
-    entityName: string;
-    /** Similarity score (typically 0-1 for cosine similarity) */
-    similarity: number;
-    /** The matched entity (if resolved) */
-    entity?: Entity;
-}
-/**
- * Result from lexical search layer (TF-IDF or BM25).
- */
-export interface LexicalSearchResult {
-    /** Entity name */
-    entityName: string;
-    /** Relevance score (unbounded, higher is better) */
-    score: number;
-    /** The matched entity (if resolved) */
-    entity?: Entity;
-}
-/**
- * Result from symbolic search layer.
- */
-export interface SymbolicSearchResult {
-    /** Entity name */
-    entityName: string;
-    /** Match score (typically 0-1) */
-    score: number;
-    /** The matched entity (if resolved) */
-    entity?: Entity;
-}
-/**
- * Combined result with scores from all layers.
- */
-export interface ScoredResult {
-    /** Entity name */
-    entityName: string;
-    /** The matched entity */
-    entity: Entity;
-    /** Individual layer scores (normalized 0-1) */
-    scores: {
-        semantic: number;
-        lexical: number;
-        symbolic: number;
-        combined: number;
-    };
-    /** Which layers contributed to this result */
-    matchedLayers: ('semantic' | 'lexical' | 'symbolic')[];
-    /** Original raw scores before normalization */
-    rawScores: {
-        semantic?: number;
-        lexical?: number;
-        symbolic?: number;
-    };
-}
-/**
- * Configurable weights for hybrid scoring.
- */
-export interface HybridWeights {
-    /** Weight for semantic layer (default: 0.4) */
-    semantic: number;
-    /** Weight for lexical layer (default: 0.4) */
-    lexical: number;
-    /** Weight for symbolic layer (default: 0.2) */
-    symbolic: number;
-}
-/**
- * Default weights for hybrid search.
- */
-export declare const DEFAULT_SCORER_WEIGHTS: HybridWeights;
-/**
- * Options for the HybridScorer.
- */
-export interface HybridScorerOptions {
-    /** Weights for each layer */
-    weights?: Partial<HybridWeights>;
-    /** Minimum score to include in results (default: 0) */
-    minScore?: number;
-    /** Whether to normalize weights to sum to 1 (default: true) */
-    normalizeWeights?: boolean;
-}
-/**
- * HybridScorer combines multiple search signals using min-max normalization.
- *
- * Features:
- * 1. Min-max normalization brings all scores to 0-1 range
- * 2. Configurable weights for each layer
- * 3. Handles missing layers gracefully (redistributes weights)
- * 4. Tracks which layers contributed to each result
- *
- * @example
- * ```typescript
- * const scorer = new HybridScorer({
- *   weights: { semantic: 0.5, lexical: 0.3, symbolic: 0.2 }
- * });
- *
- * const results = scorer.combine(
- *   semanticResults,
- *   lexicalResults,
- *   symbolicResults,
- *   entityMap
- * );
- * ```
- */
-export declare class HybridScorer {
-    private weights;
-    private minScore;
-    private normalizeWeights;
-    constructor(options?: HybridScorerOptions);
-    /**
-     * Get current weights configuration.
-     */
-    getWeights(): HybridWeights;
-    /**
-     * Update weights configuration.
-     */
-    setWeights(weights: Partial<HybridWeights>): void;
-    /**
-     * Perform min-max normalization on scores.
-     *
-     * Formula: normalized = (x - min) / (max - min)
-     *
-     * @param scores - Map of entity name to raw score
-     * @returns Map of entity name to normalized score (0-1)
-     */
-    minMaxNormalize(scores: Map<string, number>): Map<string, number>;
-    /**
-     * Combine results from all three search layers.
-     *
-     * @param semanticResults - Results from semantic search
-     * @param lexicalResults - Results from lexical search
-     * @param symbolicResults - Results from symbolic search
-     * @param entityMap - Map of entity names to Entity objects
-     * @returns Array of combined results sorted by score
-     */
-    combine(semanticResults: SemanticLayerResult[], lexicalResults: LexicalSearchResult[], symbolicResults: SymbolicSearchResult[], entityMap: Map<string, Entity>): ScoredResult[];
-    /**
-     * Get weights normalized to sum to 1, redistributing for missing layers.
-     *
-     * @param hasSemantic - Whether semantic results are available
-     * @param hasLexical - Whether lexical results are available
-     * @param hasSymbolic - Whether symbolic results are available
-     * @returns Normalized weights
-     */
-    getNormalizedWeights(hasSemantic: boolean, hasLexical: boolean, hasSymbolic: boolean): HybridWeights;
-    /**
-     * Combine scores from maps directly (alternative interface).
-     *
-     * @param semanticScores - Map of entity name to semantic score
-     * @param lexicalScores - Map of entity name to lexical score
-     * @param symbolicScores - Map of entity name to symbolic score
-     * @param entityMap - Map of entity names to Entity objects
-     * @returns Array of combined results sorted by score
-     */
-    combineFromMaps(semanticScores: Map<string, number>, lexicalScores: Map<string, number>, symbolicScores: Map<string, number>, entityMap: Map<string, Entity>): ScoredResult[];
-    /**
-     * Calculate combined score for a single entity.
-     *
-     * Useful for scoring individual results without full normalization.
-     *
-     * @param semanticScore - Normalized semantic score (0-1)
-     * @param lexicalScore - Normalized lexical score (0-1)
-     * @param symbolicScore - Normalized symbolic score (0-1)
-     * @returns Combined weighted score
-     */
-    calculateScore(semanticScore: number, lexicalScore: number, symbolicScore: number): number;
-}
-//# sourceMappingURL=HybridScorer.d.ts.map

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

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