simile-search 0.3.1 → 0.4.0

package/dist/engine.js

@@ -2,9 +2,14 @@ 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.1";
+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,31 @@ 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) {
+            this.buildANNIndex();
+        }
+        // Initialize Updater
+        this.updater = new BackgroundUpdater(this);
+    }
+    buildANNIndex() {
+        if (this.vectors.length === 0)
+            return;
+        const dims = this.vectors[0].length;
+        const hnswConfig = 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 +57,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 +148,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 +234,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
@@ -150,18 +277,35 @@ export class Simile {
         if (query.length < minLength) {
             return [];
         }
-        const qVector = await embed(query, this.config.model);
+        const qVector = await this.embedWithCache(query);
         // 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 });
+        // Use ANN if enabled and available
+        if (this.annIndex && (options.useANN ?? true)) {
+            const annResults = this.annIndex.search(qVector, topK * 2); // Get more for filtering
+            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 });
+            }
+        }
+        else {
+            // Fallback to linear scan
+            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);

package/dist/engine.test.js

@@ -178,7 +178,7 @@ describe("simile persistence", () => {
         // Create engine and save
         const engine = await Simile.from(testItems);
         const snapshot = engine.save();
-        expect(snapshot.version).toBe("0.2.0");
+        expect(snapshot.version).toBe("0.4.0");
         expect(snapshot.items.length).toBe(5);
         expect(snapshot.vectors.length).toBe(5);
         expect(snapshot.model).toBe("Xenova/all-MiniLM-L6-v2");
@@ -268,3 +268,51 @@ describe("simile custom weights", () => {
         expect(keywordResults[0].text).toContain("floor");
     }, 30000);
 });
+describe("simile performance features", () => {
+    it("enables ANN index for large datasets", async () => {
+        // Generate many items to trigger ANN threshold
+        const manyItems = Array.from({ length: 100 }, (_, i) => ({
+            id: `many-${i}`,
+            text: `Item number ${i} for testing ANN index`,
+            metadata: { index: i },
+        }));
+        const engine = await Simile.from(manyItems, {
+            annThreshold: 50, // Set low to trigger for 100 items
+            useANN: true,
+        });
+        const info = engine.getIndexInfo();
+        expect(info.type).toBe("hnsw");
+        expect(info.annStats).toBeDefined();
+        expect(info.annStats?.size).toBe(100);
+        const results = await engine.search("Item number 42");
+        expect(results[0].id).toBe("many-42");
+    }, 30000);
+    it("uses cache for redundant embeddings", async () => {
+        const engine = await Simile.from(testItems, {
+            cache: { enableStats: true },
+        });
+        // Reset stats
+        const info1 = engine.getIndexInfo();
+        // Search for same query twice
+        await engine.search("cleaner");
+        await engine.search("cleaner");
+        const info2 = engine.getIndexInfo();
+        expect(info2.cacheStats?.hits).toBeGreaterThan(0);
+        expect(info2.cacheStats?.hitRate).toBeGreaterThan(0);
+    }, 30000);
+    it("adds items with cache optimization", async () => {
+        const engine = await Simile.from(testItems.slice(0, 1));
+        const info1 = engine.getIndexInfo();
+        // Add same item again (should hit cache)
+        await engine.add(testItems.slice(0, 1));
+        const info2 = engine.getIndexInfo();
+        // Cache stats might be null if not enabled, let's enable it
+        engine.remove(['1']);
+        const engineWithStats = await Simile.from(testItems.slice(0, 1), {
+            cache: { enableStats: true }
+        });
+        await engineWithStats.add([{ id: 'new', text: testItems[0].text }]);
+        const stats = engineWithStats.getIndexInfo().cacheStats;
+        expect(stats?.hits).toBe(1);
+    }, 30000);
+});

package/dist/index.d.ts

@@ -2,4 +2,9 @@ export * from "./types.js";
 export { embed, embedBatch, vectorToBase64, base64ToVector } from "./embedder.js";
 export { cosine, fuzzyScore, keywordScore, calculateScoreStats } from "./similarity.js";
 export { hybridScore, getDefaultWeights } from "./ranker.js";
+export { Simile } from "./engine.js";
 export { getByPath, extractText, normalizeScore } from "./utils.js";
+export { HNSWIndex } from "./ann.js";
+export { VectorCache, createCacheKey } from "./cache.js";
+export { BackgroundUpdater, DebouncedUpdater, PriorityUpdater } from "./updater.js";
+export { quantizeVector, dequantizeVector, cosineQuantized, quantizedToBase64, base64ToQuantized } from "./quantization.js";

package/dist/index.js

@@ -2,4 +2,9 @@ export * from "./types.js";
 export { embed, embedBatch, vectorToBase64, base64ToVector } from "./embedder.js";
 export { cosine, fuzzyScore, keywordScore, calculateScoreStats } from "./similarity.js";
 export { hybridScore, getDefaultWeights } from "./ranker.js";
+export { Simile } from "./engine.js";
 export { getByPath, extractText, normalizeScore } from "./utils.js";
+export { HNSWIndex } from "./ann.js";
+export { VectorCache, createCacheKey } from "./cache.js";
+export { BackgroundUpdater, DebouncedUpdater, PriorityUpdater } from "./updater.js";
+export { quantizeVector, dequantizeVector, cosineQuantized, quantizedToBase64, base64ToQuantized } from "./quantization.js";

package/dist/quantization.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Vector Quantization - Reduce memory footprint by 50-75%.
+ *
+ * Quantization levels:
+ * - Float32: Full precision (4 bytes per dimension) - default
+ * - Float16: Half precision (2 bytes, ~0.1% accuracy loss)
+ * - Int8: 8-bit quantization (1 byte, ~1% accuracy loss)
+ */
+export type QuantizationType = 'float32' | 'float16' | 'int8';
+export interface QuantizedVector {
+    data: ArrayBuffer;
+    type: QuantizationType;
+    /** Scale factor for Int8 quantization */
+    scale?: number;
+    /** Offset for Int8 quantization */
+    offset?: number;
+}
+/**
+ * Quantize a Float32Array to a more memory-efficient format.
+ */
+export declare function quantizeVector(vector: Float32Array, type: QuantizationType): QuantizedVector;
+/**
+ * Dequantize back to Float32Array for computation.
+ */
+export declare function dequantizeVector(quantized: QuantizedVector): Float32Array;
+/**
+ * Compute cosine similarity directly on quantized vectors.
+ * More efficient than dequantizing first for large batches.
+ */
+export declare function cosineQuantized(a: QuantizedVector, b: QuantizedVector): number;
+/**
+ * Serialize quantized vector to base64 for storage.
+ */
+export declare function quantizedToBase64(quantized: QuantizedVector): string;
+/**
+ * Deserialize quantized vector from base64.
+ */
+export declare function base64ToQuantized(base64: string): QuantizedVector;
+/**
+ * Get bytes per dimension for a quantization type.
+ */
+export declare function getBytesPerDimension(type: QuantizationType): number;
+/**
+ * Estimate memory savings compared to Float32.
+ */
+export declare function estimateMemorySavings(vectorCount: number, dimensions: number, type: QuantizationType): {
+    original: number;
+    quantized: number;
+    savings: number;
+};

package/dist/quantization.js

@@ -0,0 +1,271 @@
+/**
+ * Vector Quantization - Reduce memory footprint by 50-75%.
+ *
+ * Quantization levels:
+ * - Float32: Full precision (4 bytes per dimension) - default
+ * - Float16: Half precision (2 bytes, ~0.1% accuracy loss)
+ * - Int8: 8-bit quantization (1 byte, ~1% accuracy loss)
+ */
+/**
+ * Quantize a Float32Array to a more memory-efficient format.
+ */
+export function quantizeVector(vector, type) {
+    switch (type) {
+        case 'float32':
+            // Ensure we get a proper ArrayBuffer (not SharedArrayBuffer)
+            const float32Data = new ArrayBuffer(vector.byteLength);
+            new Float32Array(float32Data).set(vector);
+            return {
+                data: float32Data,
+                type: 'float32',
+            };
+        case 'float16':
+            return {
+                data: float32ToFloat16(vector),
+                type: 'float16',
+            };
+        case 'int8':
+            return quantizeToInt8(vector);
+        default:
+            throw new Error(`Unknown quantization type: ${type}`);
+    }
+}
+/**
+ * Dequantize back to Float32Array for computation.
+ */
+export function dequantizeVector(quantized) {
+    switch (quantized.type) {
+        case 'float32':
+            return new Float32Array(quantized.data);
+        case 'float16':
+            return float16ToFloat32(quantized.data);
+        case 'int8':
+            return dequantizeFromInt8(quantized);
+        default:
+            throw new Error(`Unknown quantization type: ${quantized.type}`);
+    }
+}
+/**
+ * Compute cosine similarity directly on quantized vectors.
+ * More efficient than dequantizing first for large batches.
+ */
+export function cosineQuantized(a, b) {
+    if (a.type !== b.type) {
+        throw new Error('Cannot compute similarity between different quantization types');
+    }
+    switch (a.type) {
+        case 'float32': {
+            const va = new Float32Array(a.data);
+            const vb = new Float32Array(b.data);
+            return cosineFloat32(va, vb);
+        }
+        case 'float16': {
+            // For Float16, dequantize and compute (hardware Float16 not widely supported)
+            const va = float16ToFloat32(a.data);
+            const vb = float16ToFloat32(b.data);
+            return cosineFloat32(va, vb);
+        }
+        case 'int8': {
+            // For Int8, use integer arithmetic then scale
+            return cosineInt8(a, b);
+        }
+        default:
+            throw new Error(`Unknown quantization type: ${a.type}`);
+    }
+}
+/**
+ * Serialize quantized vector to base64 for storage.
+ */
+export function quantizedToBase64(quantized) {
+    const meta = JSON.stringify({
+        type: quantized.type,
+        scale: quantized.scale,
+        offset: quantized.offset,
+    });
+    const metaBuffer = Buffer.from(meta);
+    const dataBuffer = Buffer.from(quantized.data);
+    // Format: [2 bytes meta length][meta][data]
+    const combined = Buffer.alloc(2 + metaBuffer.length + dataBuffer.length);
+    combined.writeUInt16LE(metaBuffer.length, 0);
+    metaBuffer.copy(combined, 2);
+    dataBuffer.copy(combined, 2 + metaBuffer.length);
+    return combined.toString('base64');
+}
+/**
+ * Deserialize quantized vector from base64.
+ */
+export function base64ToQuantized(base64) {
+    const combined = Buffer.from(base64, 'base64');
+    const metaLength = combined.readUInt16LE(0);
+    const metaBuffer = combined.subarray(2, 2 + metaLength);
+    const dataBuffer = combined.subarray(2 + metaLength);
+    const meta = JSON.parse(metaBuffer.toString());
+    return {
+        data: dataBuffer.buffer.slice(dataBuffer.byteOffset, dataBuffer.byteOffset + dataBuffer.length),
+        type: meta.type,
+        scale: meta.scale,
+        offset: meta.offset,
+    };
+}
+/**
+ * Get bytes per dimension for a quantization type.
+ */
+export function getBytesPerDimension(type) {
+    switch (type) {
+        case 'float32': return 4;
+        case 'float16': return 2;
+        case 'int8': return 1;
+        default: return 4;
+    }
+}
+/**
+ * Estimate memory savings compared to Float32.
+ */
+export function estimateMemorySavings(vectorCount, dimensions, type) {
+    const original = vectorCount * dimensions * 4; // Float32
+    const quantized = vectorCount * dimensions * getBytesPerDimension(type);
+    return {
+        original,
+        quantized,
+        savings: 1 - (quantized / original),
+    };
+}
+// ============ Internal Helpers ============
+/**
+ * Convert Float32Array to Float16 (stored as Uint16Array buffer).
+ */
+function float32ToFloat16(float32) {
+    const uint16 = new Uint16Array(float32.length);
+    for (let i = 0; i < float32.length; i++) {
+        uint16[i] = floatToHalf(float32[i]);
+    }
+    return uint16.buffer;
+}
+/**
+ * Convert Float16 buffer back to Float32Array.
+ */
+function float16ToFloat32(buffer) {
+    const uint16 = new Uint16Array(buffer);
+    const float32 = new Float32Array(uint16.length);
+    for (let i = 0; i < uint16.length; i++) {
+        float32[i] = halfToFloat(uint16[i]);
+    }
+    return float32;
+}
+/**
+ * Quantize Float32Array to Int8 with scale/offset.
+ */
+function quantizeToInt8(vector) {
+    let min = Infinity;
+    let max = -Infinity;
+    for (let i = 0; i < vector.length; i++) {
+        if (vector[i] < min)
+            min = vector[i];
+        if (vector[i] > max)
+            max = vector[i];
+    }
+    const scale = (max - min) / 255;
+    const offset = min;
+    const int8 = new Int8Array(vector.length);
+    for (let i = 0; i < vector.length; i++) {
+        // Map to 0-255 range, then shift to -128 to 127
+        const normalized = scale > 0 ? (vector[i] - offset) / scale : 0;
+        int8[i] = Math.round(normalized) - 128;
+    }
+    return {
+        data: int8.buffer,
+        type: 'int8',
+        scale,
+        offset,
+    };
+}
+/**
+ * Dequantize Int8 back to Float32Array.
+ */
+function dequantizeFromInt8(quantized) {
+    const int8 = new Int8Array(quantized.data);
+    const float32 = new Float32Array(int8.length);
+    const scale = quantized.scale ?? 1;
+    const offset = quantized.offset ?? 0;
+    for (let i = 0; i < int8.length; i++) {
+        float32[i] = (int8[i] + 128) * scale + offset;
+    }
+    return float32;
+}
+/**
+ * Cosine similarity for Float32 vectors.
+ */
+function cosineFloat32(a, b) {
+    let dot = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+    }
+    return dot;
+}
+/**
+ * Cosine similarity for Int8 quantized vectors.
+ * Uses integer arithmetic for speed.
+ */
+function cosineInt8(a, b) {
+    const int8A = new Int8Array(a.data);
+    const int8B = new Int8Array(b.data);
+    // Compute dot product in integer space
+    let dotInt = 0;
+    let normAInt = 0;
+    let normBInt = 0;
+    for (let i = 0; i < int8A.length; i++) {
+        const valA = int8A[i] + 128;
+        const valB = int8B[i] + 128;
+        dotInt += valA * valB;
+        normAInt += valA * valA;
+        normBInt += valB * valB;
+    }
+    // For normalized vectors, we can simplify
+    // Since embeddings are already normalized, dot product ≈ cosine
+    const scaleA = a.scale ?? 1;
+    const scaleB = b.scale ?? 1;
+    return (dotInt * scaleA * scaleB) / (Math.sqrt(normAInt) * Math.sqrt(normBInt) * scaleA * scaleB);
+}
+/**
+ * Convert a 32-bit float to 16-bit half precision.
+ */
+function floatToHalf(val) {
+    const floatView = new Float32Array(1);
+    const int32View = new Int32Array(floatView.buffer);
+    floatView[0] = val;
+    const x = int32View[0];
+    let bits = (x >> 16) & 0x8000; // Sign
+    let m = (x >> 12) & 0x07ff; // Mantissa
+    const e = (x >> 23) & 0xff; // Exponent
+    if (e < 103) {
+        return bits;
+    }
+    if (e > 142) {
+        bits |= 0x7c00;
+        bits |= (e === 255 ? 0 : 1) && (x & 0x007fffff);
+        return bits;
+    }
+    if (e < 113) {
+        m |= 0x0800;
+        bits |= (m >> (114 - e)) + ((m >> (113 - e)) & 1);
+        return bits;
+    }
+    bits |= ((e - 112) << 10) | (m >> 1);
+    bits += m & 1;
+    return bits;
+}
+/**
+ * Convert a 16-bit half precision to 32-bit float.
+ */
+function halfToFloat(val) {
+    const s = (val & 0x8000) >> 15;
+    const e = (val & 0x7c00) >> 10;
+    const f = val & 0x03ff;
+    if (e === 0) {
+        return (s ? -1 : 1) * Math.pow(2, -14) * (f / Math.pow(2, 10));
+    }
+    else if (e === 0x1f) {
+        return f ? NaN : (s ? -Infinity : Infinity);
+    }
+    return (s ? -1 : 1) * Math.pow(2, e - 15) * (1 + f / Math.pow(2, 10));
+}

package/dist/similarity.d.ts

@@ -4,6 +4,25 @@
  * Returns a value between -1 and 1, where 1 is identical.
  */
 export declare function cosine(a: Float32Array, b: Float32Array): number;
+/**
+ * SIMD-style unrolled cosine similarity for better performance.
+ * Processes 4 elements at a time for ~2-4x speedup.
+ */
+export declare function cosineFast(a: Float32Array, b: Float32Array): number;
+/**
+ * Early-exit cosine similarity with threshold.
+ * Returns null if the result would definitely be below threshold.
+ * Useful for filtering out low-scoring candidates quickly.
+ */
+export declare function cosineWithThreshold(a: Float32Array, b: Float32Array, threshold: number): number | null;
+/**
+ * Batch cosine similarity with built-in top-K selection.
+ * More efficient than computing all similarities then sorting.
+ */
+export declare function batchCosine(query: Float32Array, vectors: Float32Array[], topK: number, threshold?: number): Array<{
+    index: number;
+    score: number;
+}>;
 /**
  * Compute fuzzy similarity score using Levenshtein distance.
  * Returns a value between 0 and 1, where 1 is an exact match.
@@ -14,6 +33,11 @@ export declare function fuzzyScore(a: string, b: string): number;
  * Returns the proportion of query words found in the text (0 to 1).
  */
 export declare function keywordScore(query: string, text: string): number;
+/**
+ * Fast keyword score with early exit.
+ * Stops as soon as all query words are found.
+ */
+export declare function keywordScoreFast(query: string, text: string): number;
 /**
  * Score normalization statistics for a batch of results.
  */