simile-search 0.3.2 → 0.4.1

package/dist/engine.js

@@ -1,10 +1,15 @@
-import { embed, embedBatch, vectorToBase64, base64ToVector } from "./embedder.js";
-import { cosine, fuzzyScore, keywordScore, calculateScoreStats } from "./similarity.js";
+import { embed, embedBatch, vectorToBase64, base64ToVector, } from "./embedder.js";
+import { cosine, fuzzyScore, keywordScore, calculateScoreStats, } from "./similarity.js";
 import { hybridScore, getDefaultWeights } from "./ranker.js";
 import { extractText, normalizeScore } from "./utils.js";
-const PACKAGE_VERSION = "0.3.2";
+import { VectorCache, createCacheKey } from "./cache.js";
+import { HNSWIndex } from "./ann.js";
+import { BackgroundUpdater } from "./updater.js";
+const PACKAGE_VERSION = "0.4.0";
 export class Simile {
     constructor(items, vectors, config = {}) {
+        this.cache = null;
+        this.annIndex = null;
         this.items = items;
         this.vectors = vectors;
         this.itemIndex = new Map(items.map((item, i) => [item.id, i]));
@@ -13,7 +18,40 @@ export class Simile {
             model: config.model ?? "Xenova/all-MiniLM-L6-v2",
             textPaths: config.textPaths ?? [],
             normalizeScores: config.normalizeScores ?? true,
+            cache: config.cache ?? true,
+            quantization: config.quantization ?? "float32",
+            useANN: config.useANN ?? false,
+            annThreshold: config.annThreshold ?? 1000,
         };
+        // Initialize Cache
+        if (this.config.cache) {
+            this.cache = new VectorCache(typeof this.config.cache === "object" ? this.config.cache : {});
+        }
+        // Initialize ANN Index if threshold reached or forced
+        if (this.config.useANN || this.items.length >= this.config.annThreshold) {
+            // Optimize HNSW for speed when not explicitly configured
+            const hnswConfig = typeof this.config.useANN === "object"
+                ? this.config.useANN
+                : {
+                    efSearch: 20, // Reduced from default 50 for faster search
+                    M: 16, // Keep default
+                    efConstruction: 200, // Keep default for build quality
+                };
+            this.buildANNIndex(hnswConfig);
+        }
+        // Initialize Updater
+        this.updater = new BackgroundUpdater(this);
+    }
+    buildANNIndex(config) {
+        if (this.vectors.length === 0)
+            return;
+        const dims = this.vectors[0].length;
+        const hnswConfig = config ||
+            (typeof this.config.useANN === "object" ? this.config.useANN : {});
+        this.annIndex = new HNSWIndex(dims, hnswConfig);
+        for (let i = 0; i < this.vectors.length; i++) {
+            this.annIndex.add(i, this.vectors[i]);
+        }
     }
     /**
      * Extract searchable text from an item using configured paths.
@@ -28,10 +66,57 @@ export class Simile {
     static async from(items, config = {}) {
         const model = config.model ?? "Xenova/all-MiniLM-L6-v2";
         const textPaths = config.textPaths ?? [];
-        // Extract text using paths if configured
+        // For initialization, we create a temporary cache to avoid duplicate embeddings
+        // even if caching is disabled in config, it's useful during bulk init
+        const tempCache = new VectorCache({ maxSize: items.length });
         const texts = items.map((item) => extractText(item, textPaths.length > 0 ? textPaths : undefined));
-        const vectors = await embedBatch(texts, model);
-        return new Simile(items, vectors, config);
+        const vectors = [];
+        const textsToEmbed = [];
+        const textToVectorIdx = new Map();
+        for (let i = 0; i < texts.length; i++) {
+            const text = texts[i];
+            const cacheKey = createCacheKey(text, model);
+            const cached = tempCache.get(cacheKey);
+            if (cached) {
+                vectors[i] = cached;
+            }
+            else {
+                textToVectorIdx.set(textsToEmbed.length, i);
+                textsToEmbed.push(text);
+            }
+        }
+        if (textsToEmbed.length > 0) {
+            const newVectors = await embedBatch(textsToEmbed, model);
+            for (let i = 0; i < newVectors.length; i++) {
+                const originalIdx = textToVectorIdx.get(i);
+                vectors[originalIdx] = newVectors[i];
+                tempCache.set(createCacheKey(textsToEmbed[i], model), newVectors[i]);
+            }
+        }
+        const engine = new Simile(items, vectors, config);
+        // Warm up the engine's cache with the vectors we just computed
+        if (engine.cache) {
+            for (let i = 0; i < texts.length; i++) {
+                engine.cache.set(createCacheKey(texts[i], model), vectors[i]);
+            }
+        }
+        return engine;
+    }
+    /**
+     * Internal helper for embedding text with caching.
+     */
+    async embedWithCache(text) {
+        const cacheKey = createCacheKey(text, this.config.model);
+        if (this.cache) {
+            const cached = this.cache.get(cacheKey);
+            if (cached)
+                return cached;
+        }
+        const vector = await embed(text, this.config.model);
+        if (this.cache) {
+            this.cache.set(cacheKey, vector);
+        }
+        return vector;
     }
     /**
      * Load a Simile instance from a previously saved snapshot.
@@ -72,29 +157,76 @@ export class Simile {
     toJSON() {
         return JSON.stringify(this.save());
     }
-    /**
-     * Add new items to the index
-     */
     async add(items) {
         const texts = items.map((item) => this.getSearchableText(item));
-        const newVectors = await embedBatch(texts, this.config.model);
+        // Use embedBatch with cache optimization
+        const newVectors = [];
+        const textsToEmbed = [];
+        const textToIdx = new Map();
+        for (let i = 0; i < texts.length; i++) {
+            const cacheKey = createCacheKey(texts[i], this.config.model);
+            const cached = this.cache?.get(cacheKey);
+            if (cached) {
+                newVectors[i] = cached;
+            }
+            else {
+                textToIdx.set(textsToEmbed.length, i);
+                textsToEmbed.push(texts[i]);
+            }
+        }
+        if (textsToEmbed.length > 0) {
+            const embedded = await embedBatch(textsToEmbed, this.config.model);
+            for (let i = 0; i < embedded.length; i++) {
+                const originalIdx = textToIdx.get(i);
+                newVectors[originalIdx] = embedded[i];
+                this.cache?.set(createCacheKey(textsToEmbed[i], this.config.model), embedded[i]);
+            }
+        }
         for (let i = 0; i < items.length; i++) {
             const item = items[i];
             const existingIdx = this.itemIndex.get(item.id);
             if (existingIdx !== undefined) {
-                // Update existing item
                 this.items[existingIdx] = item;
                 this.vectors[existingIdx] = newVectors[i];
+                this.annIndex?.remove(existingIdx);
+                this.annIndex?.add(existingIdx, newVectors[i]);
             }
             else {
-                // Add new item
                 const newIdx = this.items.length;
                 this.items.push(item);
                 this.vectors.push(newVectors[i]);
                 this.itemIndex.set(item.id, newIdx);
+                // Auto-enable ANN if threshold reached
+                if (!this.annIndex && this.items.length >= this.config.annThreshold) {
+                    this.buildANNIndex();
+                }
+                else {
+                    this.annIndex?.add(newIdx, newVectors[i]);
+                }
             }
         }
     }
+    /**
+     * Queue items for background indexing (non-blocking).
+     */
+    enqueue(items) {
+        this.updater.enqueue(items);
+    }
+    /**
+     * Get indexing information and stats.
+     */
+    getIndexInfo() {
+        let memoryBytes = 0;
+        for (const v of this.vectors)
+            memoryBytes += v.byteLength;
+        return {
+            type: this.annIndex ? "hnsw" : "linear",
+            size: this.items.length,
+            memory: `${(memoryBytes / 1024 / 1024).toFixed(2)} MB`,
+            cacheStats: this.cache?.getStats(),
+            annStats: this.annIndex?.getStats(),
+        };
+    }
     /**
      * Remove items by ID
      */
@@ -111,6 +243,10 @@ export class Simile {
         this.items = newItems;
         this.vectors = newVectors;
         this.itemIndex = new Map(this.items.map((item, i) => [item.id, i]));
+        // Rebuild ANN index if it exists
+        if (this.annIndex) {
+            this.buildANNIndex();
+        }
     }
     /**
      * Get item by ID
@@ -145,62 +281,141 @@ export class Simile {
      * @returns Sorted results by relevance (highest score first)
      */
     async search(query, options = {}) {
-        const { topK = 5, explain = false, filter, threshold = 0, minLength = 1, } = options;
+        const { topK = 5, explain = false, filter, threshold = 0, minLength = 1, semanticOnly = false, } = options;
         // Min character limit - don't search until query meets minimum length
         if (query.length < minLength) {
             return [];
         }
-        const qVector = await embed(query, this.config.model);
-        // First pass: calculate raw scores
-        const rawResults = [];
-        for (let i = 0; i < this.items.length; i++) {
-            const item = this.items[i];
-            if (filter && !filter(item.metadata))
-                continue;
-            const searchableText = this.getSearchableText(item);
-            const semantic = cosine(qVector, this.vectors[i]);
-            const fuzzy = fuzzyScore(query, searchableText);
-            const keyword = keywordScore(query, searchableText);
-            rawResults.push({ index: i, item, semantic, fuzzy, keyword });
-        }
-        // Calculate score statistics for normalization
-        const stats = calculateScoreStats(rawResults);
-        // Second pass: normalize scores and compute hybrid score
-        const results = [];
-        for (const raw of rawResults) {
-            let semantic = raw.semantic;
-            let fuzzy = raw.fuzzy;
-            let keyword = raw.keyword;
-            // Normalize scores if enabled
-            if (this.config.normalizeScores) {
-                semantic = normalizeScore(raw.semantic, stats.semantic.min, stats.semantic.max);
-                fuzzy = normalizeScore(raw.fuzzy, stats.fuzzy.min, stats.fuzzy.max);
-                keyword = normalizeScore(raw.keyword, stats.keyword.min, stats.keyword.max);
+        const qVector = await this.embedWithCache(query);
+        // Use ANN if enabled and available
+        if (this.annIndex && (options.useANN ?? true)) {
+            // Optimize: get fewer candidates for faster search
+            const candidateCount = semanticOnly ? topK : Math.min(topK * 2, 20);
+            const annResults = this.annIndex.search(qVector, candidateCount);
+            // Fast path: semantic-only search (no fuzzy/keyword)
+            if (semanticOnly) {
+                const results = [];
+                for (const res of annResults) {
+                    const item = this.items[res.id];
+                    if (filter && !filter(item.metadata))
+                        continue;
+                    const semantic = 1 - res.distance;
+                    if (semantic < threshold)
+                        continue;
+                    results.push({
+                        id: item.id,
+                        text: item.text,
+                        metadata: item.metadata,
+                        score: semantic,
+                        explain: explain ? { semantic, fuzzy: 0, keyword: 0 } : undefined,
+                    });
+                }
+                return results.sort((a, b) => b.score - a.score).slice(0, topK);
+            }
+            // Full hybrid search path
+            const rawResults = [];
+            for (const res of annResults) {
+                const item = this.items[res.id];
+                if (filter && !filter(item.metadata))
+                    continue;
+                const searchableText = this.getSearchableText(item);
+                const semantic = 1 - res.distance; // distance to similarity
+                const fuzzy = fuzzyScore(query, searchableText);
+                const keyword = keywordScore(query, searchableText);
+                rawResults.push({ index: res.id, item, semantic, fuzzy, keyword });
             }
-            const score = hybridScore(semantic, fuzzy, keyword, this.config.weights);
-            // Apply threshold filter
-            if (score < threshold)
-                continue;
-            results.push({
-                id: raw.item.id,
-                text: raw.item.text,
-                metadata: raw.item.metadata,
-                score,
-                explain: explain
-                    ? {
-                        semantic,
-                        fuzzy,
-                        keyword,
-                        raw: {
-                            semantic: raw.semantic,
-                            fuzzy: raw.fuzzy,
-                            keyword: raw.keyword,
-                        },
-                    }
-                    : undefined,
-            });
-        }
-        // Sort by relevance (highest score first)
-        return results.sort((a, b) => b.score - a.score).slice(0, topK);
+            // Calculate score statistics for normalization
+            const stats = calculateScoreStats(rawResults);
+            // Second pass: normalize scores and compute hybrid score
+            const results = [];
+            for (const raw of rawResults) {
+                let semantic = raw.semantic;
+                let fuzzy = raw.fuzzy;
+                let keyword = raw.keyword;
+                // Normalize scores if enabled
+                if (this.config.normalizeScores) {
+                    semantic = normalizeScore(raw.semantic, stats.semantic.min, stats.semantic.max);
+                    fuzzy = normalizeScore(raw.fuzzy, stats.fuzzy.min, stats.fuzzy.max);
+                    keyword = normalizeScore(raw.keyword, stats.keyword.min, stats.keyword.max);
+                }
+                const score = hybridScore(semantic, fuzzy, keyword, this.config.weights);
+                // Apply threshold filter
+                if (score < threshold)
+                    continue;
+                results.push({
+                    id: raw.item.id,
+                    text: raw.item.text,
+                    metadata: raw.item.metadata,
+                    score,
+                    explain: explain
+                        ? {
+                            semantic,
+                            fuzzy,
+                            keyword,
+                            raw: {
+                                semantic: raw.semantic,
+                                fuzzy: raw.fuzzy,
+                                keyword: raw.keyword,
+                            },
+                        }
+                        : undefined,
+                });
+            }
+            // Sort by relevance (highest score first)
+            return results.sort((a, b) => b.score - a.score).slice(0, topK);
+        }
+        else {
+            // Fallback to linear scan
+            const rawResults = [];
+            for (let i = 0; i < this.items.length; i++) {
+                const item = this.items[i];
+                if (filter && !filter(item.metadata))
+                    continue;
+                const searchableText = this.getSearchableText(item);
+                const semantic = cosine(qVector, this.vectors[i]);
+                const fuzzy = fuzzyScore(query, searchableText);
+                const keyword = keywordScore(query, searchableText);
+                rawResults.push({ index: i, item, semantic, fuzzy, keyword });
+            }
+            // Calculate score statistics for normalization
+            const stats = calculateScoreStats(rawResults);
+            // Second pass: normalize scores and compute hybrid score
+            const results = [];
+            for (const raw of rawResults) {
+                let semantic = raw.semantic;
+                let fuzzy = raw.fuzzy;
+                let keyword = raw.keyword;
+                // Normalize scores if enabled
+                if (this.config.normalizeScores) {
+                    semantic = normalizeScore(raw.semantic, stats.semantic.min, stats.semantic.max);
+                    fuzzy = normalizeScore(raw.fuzzy, stats.fuzzy.min, stats.fuzzy.max);
+                    keyword = normalizeScore(raw.keyword, stats.keyword.min, stats.keyword.max);
+                }
+                const score = hybridScore(semantic, fuzzy, keyword, this.config.weights);
+                // Apply threshold filter
+                if (score < threshold)
+                    continue;
+                results.push({
+                    id: raw.item.id,
+                    text: raw.item.text,
+                    metadata: raw.item.metadata,
+                    score,
+                    explain: explain
+                        ? {
+                            semantic,
+                            fuzzy,
+                            keyword,
+                            raw: {
+                                semantic: raw.semantic,
+                                fuzzy: raw.fuzzy,
+                                keyword: raw.keyword,
+                            },
+                        }
+                        : undefined,
+                });
+            }
+            // Sort by relevance (highest score first)
+            return results.sort((a, b) => b.score - a.score).slice(0, topK);
+        }
     }
 }