simile-search 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aavash Baral
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,268 @@
+<div align="center">
+  <img src="assets/logo.jpeg" alt="Simile Logo" width="200">
+</div>
+
+# Simile 🔍
+
+![npm](https://img.shields.io/npm/v/simile-search)
+![npm](https://img.shields.io/npm/dm/simile-search)
+![license](https://img.shields.io/npm/l/simile-search)
+
+**Offline-first semantic + fuzzy search engine for catalogs, names, and products.**
+
+Simile combines the power of AI embeddings with fuzzy string matching and keyword search to deliver highly relevant search results—all running locally, no API calls required.
+
+## ✨ Features
+
+- 🧠 **Semantic Search** - Understands meaning, not just keywords ("phone charger" finds "USB-C cable")
+- 🔤 **Fuzzy Matching** - Handles typos and partial matches gracefully
+- 🎯 **Keyword Boost** - Exact matches get priority
+- 💾 **Persistence** - Save/load embeddings to avoid re-computing
+- ⚡ **Batch Processing** - Optimized for large catalogs
+- 🔧 **Configurable** - Tune scoring weights for your use case
+- 📦 **Zero API Calls** - Everything runs locally with Transformers.js
+
+## 📦 Installation
+
+```bash
+npm install simile-search
+```
+
+## 🚀 Quick Start
+
+```typescript
+import { Simile } from 'simile-search';
+
+// Create a search engine with your items
+const engine = await Simile.from([
+  { id: '1', text: 'Bathroom floor cleaner', metadata: { category: 'Cleaning' } },
+  { id: '2', text: 'Dishwashing liquid', metadata: { category: 'Kitchen' } },
+  { id: '3', text: 'iPhone Charger', metadata: { category: 'Electronics' } },
+  { id: '4', text: 'USB-C phone charger cable', metadata: { category: 'Electronics' } },
+]);
+
+// Search!
+const results = await engine.search('phone charger');
+console.log(results);
+// [
+//   { id: '3', text: 'iPhone Charger', score: 0.72, ... },
+//   { id: '4', text: 'USB-C phone charger cable', score: 0.68, ... },
+//   ...
+// ]
+```
+
+## 💾 Persistence (Save & Load)
+
+The first embedding run can be slow. Save your embeddings to load instantly next time:
+
+```typescript
+import { Simile } from 'simile-search';
+import * as fs from 'fs';
+
+// First run: embed and save (slow, but only once!)
+const engine = await Simile.from(items);
+fs.writeFileSync('catalog.json', engine.toJSON());
+
+// Later: instant load from file (no re-embedding!)
+const json = fs.readFileSync('catalog.json', 'utf-8');
+const loadedEngine = Simile.loadFromJSON(json);
+
+// Works exactly the same
+const results = await loadedEngine.search('cleaner');
+```
+
+### Snapshot Format
+
+```typescript
+// For database storage
+const snapshot = engine.save();
+// {
+//   version: '0.2.0',
+//   model: 'Xenova/all-MiniLM-L6-v2',
+//   items: [...],
+//   vectors: ['base64...', 'base64...'],
+//   createdAt: '2024-12-28T...'
+// }
+
+// Load from snapshot object
+const restored = Simile.load(snapshot);
+```
+
+## 🔧 Configuration
+
+### Custom Scoring Weights
+
+Tune how much each scoring method contributes:
+
+```typescript
+const engine = await Simile.from(items, {
+  weights: {
+    semantic: 0.7,  // AI embedding similarity (default: 0.7)
+    fuzzy: 0.15,    // Levenshtein distance (default: 0.15)
+    keyword: 0.15,  // Exact keyword matches (default: 0.15)
+  }
+});
+
+// Or adjust later
+engine.setWeights({ semantic: 0.9, fuzzy: 0.05, keyword: 0.05 });
+```
+
+### Search Options
+
+```typescript
+const results = await engine.search('cleaner', {
+  topK: 10,           // Max results to return (default: 5)
+  threshold: 0.5,     // Minimum score (default: 0)
+  explain: true,      // Include score breakdown
+  filter: (meta) => meta.category === 'Cleaning',  // Filter by metadata
+});
+
+// With explain: true
+// {
+//   id: '1',
+//   text: 'Bathroom floor cleaner',
+//   score: 0.63,
+//   explain: { semantic: 0.62, fuzzy: 0.32, keyword: 1.0 }
+// }
+```
+
+## 📝 Dynamic Catalog Management
+
+Add, update, or remove items without rebuilding:
+
+```typescript
+// Add new items
+await engine.add([
+  { id: '5', text: 'Wireless headphones', metadata: { category: 'Electronics' } }
+]);
+
+// Update existing item (same ID)
+await engine.add([
+  { id: '1', text: 'Premium bathroom cleaner', metadata: { category: 'Cleaning' } }
+]);
+
+// Remove items
+engine.remove(['2', '3']);
+
+// Get item by ID
+const item = engine.get('1');
+
+// Get all items
+const allItems = engine.getAll();
+
+// Get count
+console.log(engine.size); // 3
+```
+
+## 🎯 Advanced: Direct Access to Utilities
+
+For custom implementations:
+
+```typescript
+import { 
+  embed, 
+  embedBatch, 
+  cosine, 
+  fuzzyScore, 
+  keywordScore,
+  hybridScore,
+  vectorToBase64,
+  base64ToVector 
+} from 'simile-search';
+
+// Embed text directly
+const vector = await embed('hello world');
+
+// Batch embed for performance
+const vectors = await embedBatch(['text1', 'text2', 'text3']);
+
+// Calculate similarities
+const similarity = cosine(vectorA, vectorB);
+const fuzzy = fuzzyScore('cleaner', 'cleenr');
+const keyword = keywordScore('phone charger', 'USB phone charger cable');
+
+// Combine scores
+const score = hybridScore(0.8, 0.6, 0.5, { semantic: 0.7, fuzzy: 0.15, keyword: 0.15 });
+```
+
+## 📊 API Reference
+
+### `Simile.from(items, config?)`
+Create a new engine from items. Embeds all items (async).
+
+### `Simile.load(snapshot, config?)`
+Load from a saved snapshot (instant, no embedding).
+
+### `Simile.loadFromJSON(json, config?)`
+Load from JSON string.
+
+### `engine.search(query, options?)`
+Search for similar items.
+
+### `engine.save()`
+Export snapshot object for persistence.
+
+### `engine.toJSON()`
+Export as JSON string.
+
+### `engine.add(items)`
+Add or update items (async).
+
+### `engine.remove(ids)`
+Remove items by ID.
+
+### `engine.get(id)`
+Get single item by ID.
+
+### `engine.getAll()`
+Get all items.
+
+### `engine.size`
+Number of items.
+
+### `engine.setWeights(weights)`
+Update scoring weights.
+
+## 🧪 Types
+
+```typescript
+interface SearchItem<T = any> {
+  id: string;
+  text: string;
+  metadata?: T;
+}
+
+interface SearchResult<T = any> {
+  id: string;
+  text: string;
+  score: number;
+  metadata?: T;
+  explain?: { semantic: number; fuzzy: number; keyword: number };
+}
+
+interface SearchOptions {
+  topK?: number;
+  explain?: boolean;
+  threshold?: number;
+  filter?: (metadata: any) => boolean;
+}
+
+interface SimileConfig {
+  weights?: { semantic?: number; fuzzy?: number; keyword?: number };
+  model?: string;
+}
+```
+
+## 🤖 Model
+
+Simile uses [Xenova/all-MiniLM-L6-v2](https://huggingface.co/Xenova/all-MiniLM-L6-v2) via Transformers.js by default. This model runs entirely in JavaScript—no Python or external APIs required.
+
+## 📄 License
+
+MIT © [Aavash Baral](https://github.com/iaavas)
+
+---
+
+<p align="center">
+  Made with ❤️ by <a href="https://github.com/iaavas">Aavash Baral</a>
+</p>

package/dist/embedder.d.ts

@@ -0,0 +1,11 @@
+export declare function getEmbedder(model?: string): Promise<any>;
+export declare function embed(text: string, model?: string): Promise<Float32Array>;
+/**
+ * Batch embed multiple texts at once for better performance.
+ * This is significantly faster than embedding one by one.
+ */
+export declare function embedBatch(texts: string[], model?: string): Promise<Float32Array[]>;
+/** Serialize Float32Array to base64 string for storage */
+export declare function vectorToBase64(vector: Float32Array): string;
+/** Deserialize base64 string back to Float32Array */
+export declare function base64ToVector(base64: string): Float32Array;

package/dist/embedder.js

@@ -0,0 +1,44 @@
+import { pipeline } from "@xenova/transformers";
+let extractor;
+let currentModel = "";
+export async function getEmbedder(model = "Xenova/all-MiniLM-L6-v2") {
+    if (!extractor || currentModel !== model) {
+        extractor = await pipeline("feature-extraction", model);
+        currentModel = model;
+    }
+    return extractor;
+}
+export async function embed(text, model) {
+    const embedder = await getEmbedder(model);
+    const output = await embedder(text, {
+        pooling: "mean",
+        normalize: true,
+    });
+    return output.data;
+}
+/**
+ * Batch embed multiple texts at once for better performance.
+ * This is significantly faster than embedding one by one.
+ */
+export async function embedBatch(texts, model) {
+    const embedder = await getEmbedder(model);
+    const results = [];
+    // Process in batches of 32 for memory efficiency
+    const BATCH_SIZE = 32;
+    for (let i = 0; i < texts.length; i += BATCH_SIZE) {
+        const batch = texts.slice(i, i + BATCH_SIZE);
+        const outputs = await Promise.all(batch.map((text) => embedder(text, { pooling: "mean", normalize: true })));
+        results.push(...outputs.map((o) => o.data));
+    }
+    return results;
+}
+/** Serialize Float32Array to base64 string for storage */
+export function vectorToBase64(vector) {
+    const buffer = Buffer.from(vector.buffer);
+    return buffer.toString("base64");
+}
+/** Deserialize base64 string back to Float32Array */
+export function base64ToVector(base64) {
+    const buffer = Buffer.from(base64, "base64");
+    return new Float32Array(buffer.buffer, buffer.byteOffset, buffer.length / 4);
+}

package/dist/engine.d.ts

@@ -0,0 +1,59 @@
+import { SearchItem, SearchResult, SearchOptions, SimileConfig, SimileSnapshot, HybridWeights } from "./types";
+export declare class Simile<T = any> {
+    private items;
+    private vectors;
+    private itemIndex;
+    private config;
+    private constructor();
+    /**
+     * Create a new Simile instance from items.
+     * This will embed all items (slow for first run, but cached after).
+     */
+    static from<T>(items: SearchItem<T>[], config?: SimileConfig): Promise<Simile<T>>;
+    /**
+     * Load a Simile instance from a previously saved snapshot.
+     * This is INSTANT - no embedding needed!
+     */
+    static load<T>(snapshot: SimileSnapshot<T>, config?: SimileConfig): Simile<T>;
+    /**
+     * Load from JSON string (e.g., from file or localStorage)
+     */
+    static loadFromJSON<T>(json: string, config?: SimileConfig): Simile<T>;
+    /**
+     * Save the current state to a snapshot object.
+     * Store this in a file or database for instant loading later.
+     */
+    save(): SimileSnapshot<T>;
+    /**
+     * Export as JSON string for file storage
+     */
+    toJSON(): string;
+    /**
+     * Add new items to the index
+     */
+    add(items: SearchItem<T>[]): Promise<void>;
+    /**
+     * Remove items by ID
+     */
+    remove(ids: string[]): void;
+    /**
+     * Get item by ID
+     */
+    get(id: string): SearchItem<T> | undefined;
+    /**
+     * Get all items
+     */
+    getAll(): SearchItem<T>[];
+    /**
+     * Get the number of items in the index
+     */
+    get size(): number;
+    /**
+     * Set custom scoring weights
+     */
+    setWeights(weights: HybridWeights): void;
+    /**
+     * Search for similar items
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResult<T>[]>;
+}

package/dist/engine.js

@@ -0,0 +1,152 @@
+import { embed, embedBatch, vectorToBase64, base64ToVector } from "./embedder";
+import { cosine, fuzzyScore, keywordScore } from "./similarity";
+import { hybridScore, getDefaultWeights } from "./ranker";
+const PACKAGE_VERSION = "0.2.0";
+export class Simile {
+    constructor(items, vectors, config = {}) {
+        this.items = items;
+        this.vectors = vectors;
+        this.itemIndex = new Map(items.map((item, i) => [item.id, i]));
+        this.config = {
+            weights: config.weights ?? getDefaultWeights(),
+            model: config.model ?? "Xenova/all-MiniLM-L6-v2",
+        };
+    }
+    /**
+     * Create a new Simile instance from items.
+     * This will embed all items (slow for first run, but cached after).
+     */
+    static async from(items, config = {}) {
+        const model = config.model ?? "Xenova/all-MiniLM-L6-v2";
+        const texts = items.map((item) => item.text);
+        const vectors = await embedBatch(texts, model);
+        return new Simile(items, vectors, config);
+    }
+    /**
+     * Load a Simile instance from a previously saved snapshot.
+     * This is INSTANT - no embedding needed!
+     */
+    static load(snapshot, config = {}) {
+        const vectors = snapshot.vectors.map(base64ToVector);
+        return new Simile(snapshot.items, vectors, { ...config, model: snapshot.model });
+    }
+    /**
+     * Load from JSON string (e.g., from file or localStorage)
+     */
+    static loadFromJSON(json, config = {}) {
+        const snapshot = JSON.parse(json);
+        return Simile.load(snapshot, config);
+    }
+    /**
+     * Save the current state to a snapshot object.
+     * Store this in a file or database for instant loading later.
+     */
+    save() {
+        return {
+            version: PACKAGE_VERSION,
+            model: this.config.model,
+            items: this.items,
+            vectors: this.vectors.map(vectorToBase64),
+            createdAt: new Date().toISOString(),
+        };
+    }
+    /**
+     * Export as JSON string for file storage
+     */
+    toJSON() {
+        return JSON.stringify(this.save());
+    }
+    /**
+     * Add new items to the index
+     */
+    async add(items) {
+        const texts = items.map((item) => item.text);
+        const newVectors = await embedBatch(texts, this.config.model);
+        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];
+            }
+            else {
+                // Add new item
+                const newIdx = this.items.length;
+                this.items.push(item);
+                this.vectors.push(newVectors[i]);
+                this.itemIndex.set(item.id, newIdx);
+            }
+        }
+    }
+    /**
+     * Remove items by ID
+     */
+    remove(ids) {
+        const idsToRemove = new Set(ids);
+        const newItems = [];
+        const newVectors = [];
+        for (let i = 0; i < this.items.length; i++) {
+            if (!idsToRemove.has(this.items[i].id)) {
+                newItems.push(this.items[i]);
+                newVectors.push(this.vectors[i]);
+            }
+        }
+        this.items = newItems;
+        this.vectors = newVectors;
+        this.itemIndex = new Map(this.items.map((item, i) => [item.id, i]));
+    }
+    /**
+     * Get item by ID
+     */
+    get(id) {
+        const idx = this.itemIndex.get(id);
+        return idx !== undefined ? this.items[idx] : undefined;
+    }
+    /**
+     * Get all items
+     */
+    getAll() {
+        return [...this.items];
+    }
+    /**
+     * Get the number of items in the index
+     */
+    get size() {
+        return this.items.length;
+    }
+    /**
+     * Set custom scoring weights
+     */
+    setWeights(weights) {
+        this.config.weights = { ...this.config.weights, ...weights };
+    }
+    /**
+     * Search for similar items
+     */
+    async search(query, options = {}) {
+        const { topK = 5, explain = false, filter, threshold = 0, } = options;
+        const qVector = await embed(query, this.config.model);
+        const results = [];
+        for (let i = 0; i < this.items.length; i++) {
+            const item = this.items[i];
+            if (filter && !filter(item.metadata))
+                continue;
+            const semantic = cosine(qVector, this.vectors[i]);
+            const fuzzy = fuzzyScore(query, item.text);
+            const keyword = keywordScore(query, item.text);
+            const score = hybridScore(semantic, fuzzy, keyword, this.config.weights);
+            // Apply threshold filter
+            if (score < threshold)
+                continue;
+            results.push({
+                id: item.id,
+                text: item.text,
+                metadata: item.metadata,
+                score,
+                explain: explain ? { semantic, fuzzy, keyword } : undefined,
+            });
+        }
+        return results.sort((a, b) => b.score - a.score).slice(0, topK);
+    }
+}

package/dist/engine.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/engine.test.js

@@ -0,0 +1,148 @@
+import { describe, it, expect } from "vitest";
+import { Simile } from "./engine";
+import * as fs from "fs";
+import * as path from "path";
+const testItems = [
+    {
+        id: "1",
+        text: "Bathroom floor cleaner",
+        metadata: { category: "Cleaning" },
+    },
+    {
+        id: "2",
+        text: "Dishwashing liquid",
+        metadata: { category: "Kitchen" },
+    },
+    {
+        id: "3",
+        text: "Ipod Charger",
+        metadata: { category: "Electronics" },
+    },
+    {
+        id: "4",
+        text: "Kitchen cleaning spray",
+        metadata: { category: "Cleaning" },
+    },
+    {
+        id: "5",
+        text: "USB-C phone charger cable",
+        metadata: { category: "Electronics" },
+    },
+];
+describe("simile search", () => {
+    it("returns semantically similar items", async () => {
+        const engine = await Simile.from(testItems.slice(0, 3));
+        const results = await engine.search("cleaner", { explain: true });
+        console.log("Search for 'cleaner':", results);
+        expect(results.length).toBeGreaterThan(0);
+        expect(results[0].id).toBe("1");
+        expect(results[0].score).toBeGreaterThan(0.5);
+    }, 30000);
+    it("differentiates between unrelated items", async () => {
+        const engine = await Simile.from(testItems);
+        // Search for "phone charger" - should clearly prefer electronics
+        const results = await engine.search("phone charger", { explain: true });
+        console.log("Search for 'phone charger':", results);
+        // Both chargers should be in top 2 (order may vary based on model)
+        const topTwoIds = [results[0].id, results[1].id];
+        expect(topTwoIds).toContain("5"); // USB-C phone charger
+        expect(topTwoIds).toContain("3"); // iPod Charger
+        // Both chargers should score significantly higher than cleaning products
+        const chargerScores = results.filter((r) => r.metadata?.category === "Electronics");
+        const cleaningScores = results.filter((r) => r.metadata?.category === "Cleaning");
+        // Electronics should score at least 0.4 higher than cleaning items
+        expect(chargerScores[0].score).toBeGreaterThan(cleaningScores[0].score + 0.4);
+    }, 30000);
+    it("applies threshold filtering", async () => {
+        const engine = await Simile.from(testItems);
+        // With high threshold, should filter out low-scoring results
+        const results = await engine.search("cleaner", { threshold: 0.5 });
+        console.log("Search with threshold 0.5:", results);
+        results.forEach((r) => {
+            expect(r.score).toBeGreaterThanOrEqual(0.5);
+        });
+    }, 30000);
+});
+describe("simile persistence", () => {
+    const snapshotPath = path.join(__dirname, "../.test-snapshot.json");
+    it("saves and loads from snapshot", async () => {
+        // Create engine and save
+        const engine = await Simile.from(testItems);
+        const snapshot = engine.save();
+        expect(snapshot.version).toBe("0.2.0");
+        expect(snapshot.items.length).toBe(5);
+        expect(snapshot.vectors.length).toBe(5);
+        expect(snapshot.model).toBe("Xenova/all-MiniLM-L6-v2");
+        // Load from snapshot (instant - no embedding!)
+        const loadedEngine = Simile.load(snapshot);
+        expect(loadedEngine.size).toBe(5);
+        // Search should work the same
+        const results = await loadedEngine.search("cleaner");
+        expect(results[0].text).toContain("cleaner");
+    }, 30000);
+    it("saves and loads from JSON file", async () => {
+        // Create and save to file
+        const engine = await Simile.from(testItems);
+        const json = engine.toJSON();
+        fs.writeFileSync(snapshotPath, json);
+        // Load from file (instant!)
+        const loadedJson = fs.readFileSync(snapshotPath, "utf-8");
+        const loadedEngine = Simile.loadFromJSON(loadedJson);
+        expect(loadedEngine.size).toBe(5);
+        // Cleanup
+        fs.unlinkSync(snapshotPath);
+    }, 30000);
+});
+describe("simile dynamic items", () => {
+    it("adds new items", async () => {
+        const engine = await Simile.from(testItems.slice(0, 2));
+        expect(engine.size).toBe(2);
+        await engine.add([testItems[2], testItems[3]]);
+        expect(engine.size).toBe(4);
+        const results = await engine.search("charger");
+        expect(results.some((r) => r.id === "3")).toBe(true);
+    }, 30000);
+    it("removes items", async () => {
+        const engine = await Simile.from(testItems);
+        expect(engine.size).toBe(5);
+        engine.remove(["1", "2"]);
+        expect(engine.size).toBe(3);
+        expect(engine.get("1")).toBeUndefined();
+        expect(engine.get("3")).toBeDefined();
+    }, 30000);
+    it("updates existing items", async () => {
+        const engine = await Simile.from(testItems.slice(0, 2));
+        // Update item with same ID but different text
+        await engine.add([
+            { id: "1", text: "Wireless Bluetooth headphones", metadata: { category: "Electronics" } },
+        ]);
+        expect(engine.size).toBe(2); // Still 2 items, not 3
+        expect(engine.get("1")?.text).toBe("Wireless Bluetooth headphones");
+    }, 30000);
+});
+describe("simile custom weights", () => {
+    it("respects custom weights", async () => {
+        // Engine with high semantic weight
+        const semanticEngine = await Simile.from(testItems, {
+            weights: { semantic: 0.9, fuzzy: 0.05, keyword: 0.05 },
+        });
+        // Engine with high keyword weight
+        const keywordEngine = await Simile.from(testItems, {
+            weights: { semantic: 0.1, fuzzy: 0.1, keyword: 0.8 },
+        });
+        const query = "floor";
+        const semanticResults = await semanticEngine.search(query, { explain: true });
+        const keywordResults = await keywordEngine.search(query, { explain: true });
+        console.log("Semantic-weighted results:", semanticResults.map((r) => ({
+            text: r.text,
+            score: r.score,
+        })));
+        console.log("Keyword-weighted results:", keywordResults.map((r) => ({
+            text: r.text,
+            score: r.score,
+        })));
+        // Both should find floor cleaner first (it has "floor" in text)
+        expect(semanticResults[0].text).toContain("floor");
+        expect(keywordResults[0].text).toContain("floor");
+    }, 30000);
+});

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { Simile } from "./engine";
+export * from "./types";
+export { embed, embedBatch, vectorToBase64, base64ToVector } from "./embedder";
+export { cosine, fuzzyScore, keywordScore } from "./similarity";
+export { hybridScore, getDefaultWeights } from "./ranker";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { Simile } from "./engine";
+export * from "./types";
+export { embed, embedBatch, vectorToBase64, base64ToVector } from "./embedder";
+export { cosine, fuzzyScore, keywordScore } from "./similarity";
+export { hybridScore, getDefaultWeights } from "./ranker";

package/dist/ranker.d.ts

@@ -0,0 +1,3 @@
+import { HybridWeights } from "./types";
+export declare function hybridScore(semantic: number, fuzzy: number, keyword: number, weights?: HybridWeights): number;
+export declare function getDefaultWeights(): Required<HybridWeights>;

package/dist/ranker.js

@@ -0,0 +1,19 @@
+const DEFAULT_WEIGHTS = {
+    semantic: 0.7,
+    fuzzy: 0.15,
+    keyword: 0.15,
+};
+export function hybridScore(semantic, fuzzy, keyword, weights = {}) {
+    const w = { ...DEFAULT_WEIGHTS, ...weights };
+    // Normalize weights to sum to 1
+    const total = w.semantic + w.fuzzy + w.keyword;
+    const normalizedSemantic = w.semantic / total;
+    const normalizedFuzzy = w.fuzzy / total;
+    const normalizedKeyword = w.keyword / total;
+    return (normalizedSemantic * semantic +
+        normalizedFuzzy * fuzzy +
+        normalizedKeyword * keyword);
+}
+export function getDefaultWeights() {
+    return { ...DEFAULT_WEIGHTS };
+}

package/dist/similarity.d.ts

@@ -0,0 +1,3 @@
+export declare function cosine(a: Float32Array, b: Float32Array): number;
+export declare function fuzzyScore(a: string, b: string): number;
+export declare function keywordScore(query: string, text: string): number;

package/dist/similarity.js

@@ -0,0 +1,18 @@
+import levenshtein from "fast-levenshtein";
+export function cosine(a, b) {
+    let dot = 0;
+    for (let i = 0; i < a.length; i++)
+        dot += a[i] * b[i];
+    return dot;
+}
+export function fuzzyScore(a, b) {
+    const dist = levenshtein.get(a.toLowerCase(), b.toLowerCase());
+    const maxLen = Math.max(a.length, b.length);
+    return 1 - dist / maxLen;
+}
+export function keywordScore(query, text) {
+    const q = query.toLowerCase().split(" ");
+    const t = text.toLowerCase();
+    const hits = q.filter((w) => t.includes(w)).length;
+    return hits / q.length;
+}

package/dist/types.d.ts

@@ -0,0 +1,46 @@
+export interface SearchItem<T = any> {
+    id: string;
+    text: string;
+    metadata?: T;
+}
+export interface SearchResult<T = any> {
+    id: string;
+    text: string;
+    score: number;
+    metadata?: T;
+    explain?: {
+        semantic: number;
+        fuzzy: number;
+        keyword: number;
+    };
+}
+export interface SearchOptions {
+    topK?: number;
+    explain?: boolean;
+    filter?: (metadata: any) => boolean;
+    /** Minimum score threshold (0-1). Results below this are filtered out */
+    threshold?: number;
+}
+export interface HybridWeights {
+    /** Semantic similarity weight (0-1), default: 0.7 */
+    semantic?: number;
+    /** Fuzzy string similarity weight (0-1), default: 0.15 */
+    fuzzy?: number;
+    /** Keyword match weight (0-1), default: 0.15 */
+    keyword?: number;
+}
+export interface SimileConfig {
+    /** Custom hybrid scoring weights */
+    weights?: HybridWeights;
+    /** Model to use for embeddings (default: "Xenova/all-MiniLM-L6-v2") */
+    model?: string;
+}
+/** Serialized state for persistence */
+export interface SimileSnapshot<T = any> {
+    version: string;
+    model: string;
+    items: SearchItem<T>[];
+    /** Base64-encoded Float32Array vectors */
+    vectors: string[];
+    createdAt: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "simile-search",
+  "version": "0.2.0",
+  "description": "Offline-first semantic + fuzzy search engine for catalogs, names, and products",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "semantic-search",
+    "vector-search",
+    "fuzzy-search",
+    "offline-search",
+    "ai-search"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "author": "Aavash Baral",
+  "license": "MIT",
+  "dependencies": {
+    "@xenova/transformers": "^2.17.2",
+    "fast-levenshtein": "^3.0.0",
+    "vitest": "^4.0.16"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "@types/fast-levenshtein": "^0.0.4",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.16"
+  }
+}