embedded-raptor 1.0.0 → 2.0.0

package/README.md

@@ -1,29 +1,29 @@
-# Raptor
+# Embedded Raptor
 
-[![CI](https://img.shields.io/github/actions/workflow/status/artmann/raptor/ci.yml?branch=main&label=CI&logo=github)](https://github.com/artmann/raptor/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/raptor.svg?logo=npm)](https://www.npmjs.com/package/raptor)
-[![npm downloads](https://img.shields.io/npm/dm/raptor.svg)](https://www.npmjs.com/package/raptor)
+[![CI](https://img.shields.io/github/actions/workflow/status/artmann/embedded-raptor/ci.yml?branch=main&label=CI&logo=github)](https://github.com/artmann/embedded-raptor/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/embedded-raptor.svg?logo=npm)](https://www.npmjs.com/package/embedded-raptor)
+[![npm downloads](https://img.shields.io/npm/dm/embedded-raptor.svg)](https://www.npmjs.com/package/embedded-raptor)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg?logo=typescript)](https://www.typescriptlang.org/)
 
 > A lightweight semantic search database with text embeddings for Node.js and
 > Bun
 
-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 Raptor?
+## What is Embedded Raptor?
 
-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".
 
-## Why Raptor?
+## Why Embedded Raptor?
 
 - **Simple API** - No complex setup, just store and search
 - **Semantic Search** - Find content by meaning, not just keywords
@@ -44,10 +44,10 @@ login credentials" or "change account password".
 
 ```bash
 # Using npm
-npm install raptor
+npm install embedded-raptor
 
 # Using bun
-bun add raptor
+bun add embedded-raptor
 ```
 
 ## Quick Start
@@ -55,7 +55,7 @@ bun add raptor
 ### Programmatic API
 
 ```typescript
-import { EmbeddingEngine } from 'raptor'
+import { EmbeddingEngine } from 'embedded-raptor'
 
 const engine = new EmbeddingEngine({
   storePath: './my-database.raptor'
@@ -203,12 +203,12 @@ raptor store key1 "Some text" --storePath ./data/custom.raptor
 
 ## How It Works
 
-1. **Text → Embeddings**: 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, 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-KhnrAv7v.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-DISO9uFr.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-D06Gh_gw.mjs → engine-BvJ0ls3b.mjs}

@@ -1,4 +1,4 @@
-import { EmbeddingModel, FlagEmbedding } from "fastembed";
+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,22 +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;
+	cacheDir;
+	llama;
+	model;
+	embeddingContext;
+	initPromise;
 	constructor(options) {
 		this.storePath = options.storePath;
 		this.fileReader = new BinaryFileReader(options.storePath);
+		this.cacheDir = options.cacheDir ?? DEFAULT_CACHE_DIR;
 	}
 	/**
-	* Generates embedding from text using FastEmbed BGE-Base-EN model
+	* Gets or initializes the embedding model
+	* Caches the model instance to avoid repeated initialization overhead
+	*/
+	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 node-llama-cpp with bge-small-en-v1.5 model
 	* @param text - Text to embed
-	* @returns 768-dimensional embedding vector
+	* @returns 384-dimensional embedding vector (normalized)
 	*/
 	async generateEmbedding(text) {
-		const embeddings = (await FlagEmbedding.init({ model: EmbeddingModel.BGEBaseEN })).embed([text]);
-		for await (const batch of embeddings) return Array.from(batch[0]);
-		return [];
+		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
@@ -290,16 +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 embeddings = (await FlagEmbedding.init({ model: EmbeddingModel.BGEBaseEN })).embed(texts);
-		const embeddingsList = [];
-		for await (const batch of embeddings) for (let i = 0; i < batch.length; i++) embeddingsList.push(Array.from(batch[i]));
-		invariant(embeddingsList.length === items.length, "Number of embeddings must match number of items.");
+		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 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) => ({
@@ -329,6 +375,22 @@ var EmbeddingEngine = class {
 		if (magnitudeA === 0 || magnitudeB === 0) return 0;
 		return dotProduct / (magnitudeA * magnitudeB);
 	}
+	/**
+	* Disposes of the cached embedding model and releases resources
+	* Call this when you're done using the engine to free up memory
+	*/
+	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;
+	}
 };
 
 //#endregion