embedded-raptor 1.1.0 → 2.0.0

package/README.md

@@ -9,16 +9,16 @@
 > A lightweight semantic search database with text embeddings for Node.js and
 > Bun
 
-Embedded Raptor lets you build semantic search into your applications with just a few
-lines of code. Store text, search by meaning, and find similar content—perfect
-for RAG systems, chatbots, and recommendation engines.
+Embedded Raptor lets you build semantic search into your applications with just
+a few lines of code. Store text, search by meaning, and find similar
+content—perfect for RAG systems, chatbots, and recommendation engines.
 
 ## What is Embedded Raptor?
 
-Embedded Raptor is an embedding database that automatically converts text into vector
-embeddings and stores them in an efficient binary format. Instead of searching
-by exact keywords, you can search by semantic similarity—finding documents that
-mean the same thing, even if they use different words.
+Embedded Raptor is an embedding database that automatically converts text into
+vector embeddings and stores them in an efficient binary format. Instead of
+searching by exact keywords, you can search by semantic similarity—finding
+documents that mean the same thing, even if they use different words.
 
 **Example:** Search for "how to reset password" and find results like "forgot my
 login credentials" or "change account password".
@@ -203,12 +203,12 @@ raptor store key1 "Some text" --storePath ./data/custom.raptor
 
 ## How It Works
 
-1. **Text → Embeddings**: Embedded Raptor uses the BGE-Base-EN model to convert text into
-   768-dimensional vector embeddings
+1. **Text → Embeddings**: Embedded Raptor uses the BGE-Base-EN model to convert
+   text into 768-dimensional vector embeddings
 2. **Storage**: Embeddings are stored in an efficient binary format (.raptor
    files)
-3. **Search**: When you search, Embedded Raptor compares your query embedding against all
-   stored embeddings using cosine similarity
+3. **Search**: When you search, Embedded Raptor compares your query embedding
+   against all stored embeddings using cosine similarity
 4. **Results**: Returns the most similar results ranked by similarity score
 
 **Embedding Model**:

package/dist/cli.cjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-const require_engine = require('./engine-CTvg_66e.cjs');
-let node_fs = require("node:fs");
-node_fs = require_engine.__toESM(node_fs);
+const require_engine = require('./engine-DLM7PWhV.cjs');
 let node_path = require("node:path");
 node_path = require_engine.__toESM(node_path);
+let node_fs = require("node:fs");
+node_fs = require_engine.__toESM(node_fs);
 let cleye = require("cleye");
 cleye = require_engine.__toESM(cleye);
 let node_url = require("node:url");
@@ -89,6 +89,27 @@ const search = (0, cleye.command)({
 	}
 });
 
+//#endregion
+//#region src/commands/delete.ts
+const deleteCmd = (0, cleye.command)({
+	name: "delete",
+	description: "Delete an embedding entry by key",
+	parameters: ["<key>"],
+	flags: { ...sharedFlags }
+}, async (argv) => {
+	const engine = new require_engine.EmbeddingEngine({ storePath: argv.flags.storePath });
+	try {
+		const [key] = argv._;
+		if (await engine.delete(key)) console.log(`Deleted key "${key}"`);
+		else {
+			console.log(`Key "${key}" not found`);
+			process.exit(1);
+		}
+	} finally {
+		await engine.dispose();
+	}
+});
+
 //#endregion
 //#region src/cli.ts
 const __dirname$1 = (0, node_path.dirname)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href));
@@ -100,7 +121,8 @@ function main() {
 		commands: [
 			store,
 			get,
-			search
+			search,
+			deleteCmd
 		]
 	}, () => {});
 }

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { t as EmbeddingEngine } from "./engine-ez6nFONK.mjs";
-import { readFileSync } from "node:fs";
+import { t as EmbeddingEngine } from "./engine-Cuz0P5Od.mjs";
 import { dirname, resolve } from "node:path";
+import { readFileSync } from "node:fs";
 import { cli, command } from "cleye";
 import { fileURLToPath } from "node:url";
 
@@ -85,6 +85,27 @@ const search = command({
 	}
 });
 
+//#endregion
+//#region src/commands/delete.ts
+const deleteCmd = command({
+	name: "delete",
+	description: "Delete an embedding entry by key",
+	parameters: ["<key>"],
+	flags: { ...sharedFlags }
+}, async (argv) => {
+	const engine = new EmbeddingEngine({ storePath: argv.flags.storePath });
+	try {
+		const [key] = argv._;
+		if (await engine.delete(key)) console.log(`Deleted key "${key}"`);
+		else {
+			console.log(`Key "${key}" not found`);
+			process.exit(1);
+		}
+	} finally {
+		await engine.dispose();
+	}
+});
+
 //#endregion
 //#region src/cli.ts
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -96,7 +117,8 @@ function main() {
 		commands: [
 			store,
 			get,
-			search
+			search,
+			deleteCmd
 		]
 	}, () => {});
 }

package/dist/commands/delete.d.ts

@@ -0,0 +1,41 @@
+export declare const deleteCmd: import("cleye").Command<{
+    name: "delete";
+    description: string;
+    parameters: "<key>"[];
+    flags: {
+        storePath: {
+            readonly type: StringConstructor;
+            readonly description: "Path to the embeddings store file";
+            readonly default: "./database.raptor";
+            readonly alias: "s";
+        };
+    };
+}, {
+    command: "delete";
+} & import("type-flag").TypeFlag<{
+    storePath: {
+        readonly type: StringConstructor;
+        readonly description: "Path to the embeddings store file";
+        readonly default: "./database.raptor";
+        readonly alias: "s";
+    };
+} & {
+    help: BooleanConstructor;
+}> & {
+    _: {
+        key: string;
+    };
+    showHelp: (options?: {
+        version?: string;
+        description?: string;
+        usage?: false | string | string[];
+        examples?: string | string[];
+        render?: (nodes: {
+            id?: string;
+            type: keyof import("cleye").Renderers;
+            data: any;
+        }[], renderers: import("cleye").Renderers) => string;
+    }) => void;
+    showVersion: () => void;
+}>;
+//# sourceMappingURL=delete.d.ts.map

package/dist/commands/delete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delete.d.ts","sourceRoot":"","sources":["../../src/commands/delete.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;sBA6B2kM,CAAC;;;;;;;;;;;;EADjmM,CAAA"}

package/dist/commands/index.d.ts

@@ -1,4 +1,5 @@
 export { store } from './store';
 export { get } from './get';
 export { search } from './search';
+export { deleteCmd } from './delete';
 //# sourceMappingURL=index.d.ts.map

package/dist/commands/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA"}

package/dist/{engine-ez6nFONK.mjs → engine-BvJ0ls3b.mjs}

@@ -1,4 +1,4 @@
-import { env, pipeline } from "@xenova/transformers";
+import { getLlama, resolveModelFile } from "node-llama-cpp";
 import { existsSync } from "node:fs";
 import { appendFile, mkdir, open, stat, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
@@ -221,35 +221,64 @@ var CandidateSetEntry = class {
 
 //#endregion
 //#region src/engine.ts
+const DEFAULT_MODEL_URI = "hf:CompendiumLabs/bge-small-en-v1.5-gguf/bge-small-en-v1.5-q8_0.gguf";
+const DEFAULT_CACHE_DIR = "./.cache/models";
 var EmbeddingEngine = class {
 	fileReader;
 	storePath;
-	extractor;
+	cacheDir;
+	llama;
+	model;
+	embeddingContext;
+	initPromise;
 	constructor(options) {
 		this.storePath = options.storePath;
 		this.fileReader = new BinaryFileReader(options.storePath);
-		env.cacheDir = "./.cache";
+		this.cacheDir = options.cacheDir ?? DEFAULT_CACHE_DIR;
 	}
 	/**
 	* Gets or initializes the embedding model
 	* Caches the model instance to avoid repeated initialization overhead
-	* @returns Initialized feature extraction pipeline
 	*/
-	async getOrInitModel() {
-		this.extractor ??= await pipeline("feature-extraction", "Xenova/bge-small-en-v1.5");
-		return this.extractor;
+	async ensureModelLoaded() {
+		if (this.embeddingContext) return;
+		if (this.initPromise) return this.initPromise;
+		this.initPromise = this.initializeModel();
+		await this.initPromise;
+	}
+	async initializeModel() {
+		this.llama = await getLlama();
+		const modelPath = await resolveModelFile(DEFAULT_MODEL_URI, this.cacheDir);
+		this.model = await this.llama.loadModel({ modelPath });
+		this.embeddingContext = await this.model.createEmbeddingContext();
+	}
+	/**
+	* Truncates text to fit within the model's context size
+	* Uses the model's tokenizer for accurate token counting
+	* BGE-small supports 512 tokens, we use 500 to leave room for special tokens
+	*/
+	truncateToContextSize(text) {
+		if (!this.model) {
+			const maxChars = 300 * 3;
+			return text.length <= maxChars ? text : text.slice(0, maxChars);
+		}
+		const maxTokens = 500;
+		const tokens = this.model.tokenize(text);
+		if (tokens.length <= maxTokens) return text;
+		const truncatedTokens = tokens.slice(0, maxTokens);
+		return this.model.detokenize(truncatedTokens);
 	}
 	/**
-	* Generates embedding from text using Transformers.js bge-small-en-v1.5 model
+	* Generates embedding from text using node-llama-cpp with bge-small-en-v1.5 model
 	* @param text - Text to embed
 	* @returns 384-dimensional embedding vector (normalized)
 	*/
 	async generateEmbedding(text) {
-		const output = await (await this.getOrInitModel())(text, {
-			pooling: "mean",
-			normalize: true
-		});
-		return Array.from(output.data);
+		await this.ensureModelLoaded();
+		invariant(this.embeddingContext, "Embedding context not initialized");
+		const truncatedText = this.truncateToContextSize(text);
+		const embedding = await this.embeddingContext.getEmbeddingFor(truncatedText);
+		return Array.from(embedding.vector);
 	}
 	/**
 	* Retrieves an embedding entry by key
@@ -303,26 +332,20 @@ var EmbeddingEngine = class {
 	/**
 	* Stores multiple text embeddings in batch
 	* More efficient than calling store() multiple times
-	* Generates embeddings in a single batch and writes all records at once
+	* Generates embeddings in parallel and writes all records at once
 	* @param items - Array of {key, text} objects to store
 	*/
 	async storeMany(items) {
 		invariant(items.length > 0, "Items array must not be empty.");
-		const texts = items.map((item) => item.text);
-		const output = await (await this.getOrInitModel())(texts, {
-			pooling: "mean",
-			normalize: true
+		await this.ensureModelLoaded();
+		const embeddingContext = this.embeddingContext;
+		invariant(embeddingContext, "Embedding context not initialized");
+		const embeddingPromises = items.map(async (item) => {
+			const truncatedText = this.truncateToContextSize(item.text);
+			const embedding = await embeddingContext.getEmbeddingFor(truncatedText);
+			return Array.from(embedding.vector);
 		});
-		const batchSize = output.dims[0];
-		const embeddingDim = output.dims[1];
-		const embeddingsList = [];
-		for (let i = 0; i < batchSize; i++) {
-			const start = i * embeddingDim;
-			const end = start + embeddingDim;
-			const data = Array.from(output.data);
-			embeddingsList.push(data.slice(start, end));
-		}
-		invariant(embeddingsList.length === items.length, "Number of embeddings must match number of items.");
+		const embeddingsList = await Promise.all(embeddingPromises);
 		await mkdir(dirname(this.storePath), { recursive: true });
 		if (!existsSync(this.storePath)) await writeHeader(this.storePath, embeddingsList[0].length);
 		const records = items.map((item, index) => ({
@@ -356,8 +379,17 @@ var EmbeddingEngine = class {
 	* Disposes of the cached embedding model and releases resources
 	* Call this when you're done using the engine to free up memory
 	*/
-	dispose() {
-		this.extractor = void 0;
+	async dispose() {
+		if (this.embeddingContext) {
+			await this.embeddingContext.dispose();
+			this.embeddingContext = void 0;
+		}
+		if (this.model) {
+			await this.model.dispose();
+			this.model = void 0;
+		}
+		this.llama = void 0;
+		this.initPromise = void 0;
 	}
 };