@vivantel/virage-embedder-fastembed 0.2.0

package/README.md

@@ -0,0 +1,62 @@
+# @vivantel/virage-embedder-fastembed
+
+[![npm version](https://img.shields.io/npm/v/@vivantel/virage-embedder-fastembed.svg)](https://www.npmjs.com/package/@vivantel/virage-embedder-fastembed)
+
+Fast, local ONNX-based embedding provider for `@vivantel/virage-core` using [FastEmbed](https://github.com/Anush008/fastembed-js). No API key required.
+
+## Installation
+
+```bash
+npm install @vivantel/virage-embedder-fastembed
+```
+
+> **Note**: `fastembed` downloads ONNX Runtime binaries during install. If you're in a CI environment or want to skip GPU binaries: `npm install @vivantel/virage-embedder-fastembed --ignore-scripts` — the CPU runtime works fine without the postinstall scripts.
+
+## Usage
+
+```typescript
+import { FastEmbedEmbedder } from "@vivantel/virage-embedder-fastembed";
+
+const embedder = new FastEmbedEmbedder({
+  model: "BAAI/bge-small-en-v1.5",
+  dimensions: 384,
+});
+```
+
+The inner model is initialized lazily on the first `embed()` call.
+
+## JSON config
+
+```json
+{
+  "embedder": {
+    "package": "@vivantel/virage-embedder-fastembed",
+    "config": {
+      "model": "BAAI/bge-small-en-v1.5",
+      "dimensions": 384
+    }
+  }
+}
+```
+
+## Supported models
+
+| Model | Dimensions | Notes |
+| --- | --- | --- |
+| `BAAI/bge-small-en-v1.5` | 384 | Default — fast and compact |
+| `BAAI/bge-base-en-v1.5` | 768 | Better quality |
+| `BAAI/bge-large-en-v1.5` | 1024 | Highest quality |
+| `nomic-ai/nomic-embed-text-v1.5` | 768 | Long context (8192 tokens) |
+
+## Options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `model` | `string` | Model name (default: `"BAAI/bge-small-en-v1.5"`) |
+| `dimensions` | `number` | Output dimensions (auto-detected from model if omitted) |
+| `cacheDir` | `string` | Local model cache directory |
+| `showDownloadProgress` | `boolean` | Show download progress bar (default: `false`) |
+
+## License
+
+MIT

package/dist/embedder.d.ts

@@ -0,0 +1,27 @@
+import type { EmbeddingProvider, Logger } from "@vivantel/virage-core";
+export interface FastEmbedEmbedderOptions {
+    /** FastEmbed model name, e.g. "BAAI/bge-small-en-v1.5" */
+    model?: string;
+    /** Output vector dimensions. Defaults based on model. */
+    dimensions?: number;
+    /** Local directory for caching downloaded models. */
+    cacheDir?: string;
+    showDownloadProgress?: boolean;
+}
+export declare class FastEmbedEmbedder implements EmbeddingProvider {
+    readonly name = "fastembed";
+    readonly dimensions: number;
+    readonly model: string;
+    readonly preferredBatchSize = 256;
+    private readonly cacheDir?;
+    private readonly showDownloadProgress;
+    private _inner;
+    private logger;
+    constructor(options?: FastEmbedEmbedderOptions);
+    setLogger(logger: Logger): void;
+    private getModel;
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+    healthCheck(): Promise<boolean>;
+}
+//# sourceMappingURL=embedder.d.ts.map

package/dist/embedder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedder.d.ts","sourceRoot":"","sources":["../src/embedder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAIvE,MAAM,WAAW,wBAAwB;IACvC,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAwBD,qBAAa,iBAAkB,YAAW,iBAAiB;IACzD,QAAQ,CAAC,IAAI,eAAe;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,kBAAkB,OAAO;IAElC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAU;IAC/C,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,MAAM,CAAuB;gBAEzB,OAAO,GAAE,wBAA6B;IAQlD,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;YAIjB,QAAQ;IAsChB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAKtC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAahD,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;CAQtC"}

package/dist/embedder.js

@@ -0,0 +1,84 @@
+import { mkdir } from "fs/promises";
+import path from "path";
+const DEFAULT_MODEL = "fast-bge-small-en-v1.5";
+const DEFAULT_DIMENSIONS = {
+    "fast-bge-small-en-v1.5": 384,
+    "fast-bge-base-en-v1.5": 768,
+    "fast-multilingual-e5-large": 1024,
+    "fast-all-MiniLM-L6-v2": 384,
+};
+export class FastEmbedEmbedder {
+    name = "fastembed";
+    dimensions;
+    model;
+    preferredBatchSize = 256;
+    cacheDir;
+    showDownloadProgress;
+    _inner = null;
+    logger = null;
+    constructor(options = {}) {
+        this.model = options.model ?? DEFAULT_MODEL;
+        this.dimensions =
+            options.dimensions ?? DEFAULT_DIMENSIONS[this.model] ?? 384;
+        this.cacheDir = options.cacheDir;
+        this.showDownloadProgress = options.showDownloadProgress ?? false;
+    }
+    setLogger(logger) {
+        this.logger = logger.withTag("fastembed");
+    }
+    async getModel() {
+        if (this._inner)
+            return this._inner;
+        this.logger?.info(`Loading model ${this.model}`);
+        // Ensure the parent directory exists before fastembed tries to write the
+        // model tarball to it. fastembed creates the top-level cacheDir itself but
+        // not nested vendor subdirectories, so "BAAI/bge-small-en-v1.5" needs
+        // "<cacheDir>/BAAI/" to pre-exist. We must NOT create the model directory
+        // itself or fastembed skips the download and fails with "Tokenizer file
+        // not found". Apply whether or not cacheDir was explicitly configured —
+        // fastembed defaults to "local_cache" when omitted.
+        const effectiveCacheDir = this.cacheDir ?? "local_cache";
+        const modelParent = path.dirname(this.model);
+        if (modelParent !== ".") {
+            await mkdir(path.join(effectiveCacheDir, modelParent), {
+                recursive: true,
+            });
+        }
+        this.logger?.debug(`Cache dir: ${effectiveCacheDir}`);
+        // Lazy import — consumers must install fastembed.
+        // Variable specifier prevents TS from erroring when fastembed isn't installed.
+        const mod = "fastembed";
+        const { FlagEmbedding } = (await import(mod));
+        this._inner = await FlagEmbedding.init({
+            model: this.model,
+            cacheDir: this.cacheDir,
+            showDownloadProgress: this.showDownloadProgress,
+        });
+        this.logger?.info(`Model ${this.model} ready (${this.dimensions}d, batch=${this.preferredBatchSize})`);
+        return this._inner;
+    }
+    async embed(text) {
+        const [result] = await this.embedBatch([text]);
+        return result;
+    }
+    async embedBatch(texts) {
+        const model = await this.getModel();
+        this.logger?.verbose(`Batch ${texts.length} texts`);
+        this.logger?.trace(`Text lengths: ${texts.map((t) => t.length).join(", ")}`);
+        const results = [];
+        for await (const batch of model.embed(texts)) {
+            results.push(...batch);
+        }
+        return results;
+    }
+    async healthCheck() {
+        try {
+            await this.getModel();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=embedder.js.map

package/dist/embedder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedder.js","sourceRoot":"","sources":["../src/embedder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,IAAI,MAAM,MAAM,CAAC;AA0BxB,MAAM,aAAa,GAAG,wBAAwB,CAAC;AAC/C,MAAM,kBAAkB,GAA2B;IACjD,wBAAwB,EAAE,GAAG;IAC7B,uBAAuB,EAAE,GAAG;IAC5B,4BAA4B,EAAE,IAAI;IAClC,uBAAuB,EAAE,GAAG;CAC7B,CAAC;AAEF,MAAM,OAAO,iBAAiB;IACnB,IAAI,GAAG,WAAW,CAAC;IACnB,UAAU,CAAS;IACnB,KAAK,CAAS;IACd,kBAAkB,GAAG,GAAG,CAAC;IAEjB,QAAQ,CAAU;IAClB,oBAAoB,CAAU;IACvC,MAAM,GAA0B,IAAI,CAAC;IACrC,MAAM,GAAkB,IAAI,CAAC;IAErC,YAAY,UAAoC,EAAE;QAChD,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,aAAa,CAAC;QAC5C,IAAI,CAAC,UAAU;YACb,OAAO,CAAC,UAAU,IAAI,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC;QAC9D,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,IAAI,KAAK,CAAC;IACpE,CAAC;IAED,SAAS,CAAC,MAAc;QACtB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5C,CAAC;IAEO,KAAK,CAAC,QAAQ;QACpB,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC,MAAM,CAAC;QAEpC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,iBAAiB,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QAEjD,yEAAyE;QACzE,2EAA2E;QAC3E,sEAAsE;QACtE,0EAA0E;QAC1E,wEAAwE;QACxE,wEAAwE;QACxE,oDAAoD;QACpD,MAAM,iBAAiB,GAAG,IAAI,CAAC,QAAQ,IAAI,aAAa,CAAC;QACzD,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7C,IAAI,WAAW,KAAK,GAAG,EAAE,CAAC;YACxB,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,WAAW,CAAC,EAAE;gBACrD,SAAS,EAAE,IAAI;aAChB,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,cAAc,iBAAiB,EAAE,CAAC,CAAC;QAEtD,kDAAkD;QAClD,+EAA+E;QAC/E,MAAM,GAAG,GAAG,WAAW,CAAC;QACxB,MAAM,EAAE,aAAa,EAAE,GAAG,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,CAA+B,CAAC;QAC5E,IAAI,CAAC,MAAM,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC;YACrC,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,oBAAoB,EAAE,IAAI,CAAC,oBAAoB;SAChD,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,EAAE,IAAI,CACf,SAAS,IAAI,CAAC,KAAK,WAAW,IAAI,CAAC,UAAU,YAAY,IAAI,CAAC,kBAAkB,GAAG,CACpF,CAAC;QACF,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAC/C,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,KAAe;QAC9B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QACpC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,KAAK,CAAC,MAAM,QAAQ,CAAC,CAAC;QACpD,IAAI,CAAC,MAAM,EAAE,KAAK,CAChB,iBAAiB,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACzD,CAAC;QACF,MAAM,OAAO,GAAe,EAAE,CAAC;QAC/B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7C,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC;QACzB,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,WAAW;QACf,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;YACtB,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { FastEmbedEmbedder, type FastEmbedEmbedderOptions, } from "./embedder.js";
+import type { EmbeddingProvider } from "@vivantel/virage-core";
+/** Factory used by the JSON config loader. */
+export declare function createEmbedder(config: Record<string, unknown>): EmbeddingProvider;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,GAC9B,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAM/D,8CAA8C;AAC9C,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,iBAAiB,CAanB"}

package/dist/index.js

@@ -0,0 +1,15 @@
+export { FastEmbedEmbedder, } from "./embedder.js";
+import { FastEmbedEmbedder, } from "./embedder.js";
+/** Factory used by the JSON config loader. */
+export function createEmbedder(config) {
+    const opts = {
+        model: typeof config.model === "string" ? config.model : undefined,
+        dimensions: typeof config.dimensions === "number" ? config.dimensions : undefined,
+        cacheDir: typeof config.cacheDir === "string" ? config.cacheDir : undefined,
+        showDownloadProgress: typeof config.showDownloadProgress === "boolean"
+            ? config.showDownloadProgress
+            : undefined,
+    };
+    return new FastEmbedEmbedder(opts);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,GAElB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,iBAAiB,GAElB,MAAM,eAAe,CAAC;AAEvB,8CAA8C;AAC9C,MAAM,UAAU,cAAc,CAC5B,MAA+B;IAE/B,MAAM,IAAI,GAA6B;QACrC,KAAK,EAAE,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;QAClE,UAAU,EACR,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;QACvE,QAAQ,EAAE,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;QAC3E,oBAAoB,EAClB,OAAO,MAAM,CAAC,oBAAoB,KAAK,SAAS;YAC9C,CAAC,CAAC,MAAM,CAAC,oBAAoB;YAC7B,CAAC,CAAC,SAAS;KAChB,CAAC;IAEF,OAAO,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@vivantel/virage-embedder-fastembed",
+  "version": "0.2.0",
+  "description": "FastEmbed ONNX-based local embedding provider for @vivantel/rag-core",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "fix": "npm run lint:fix && npm run format"
+  },
+  "keywords": [
+    "rag",
+    "embeddings",
+    "fastembed",
+    "onnx",
+    "local",
+    "offline"
+  ],
+  "author": "Vivantel",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vivantel/virage",
+    "directory": "packages/virage-embedder-fastembed"
+  },
+  "dependencies": {
+    "fastembed": "^2.1.0"
+  },
+  "peerDependencies": {
+    "@vivantel/virage-core": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@vivantel/virage-core": "0.2.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}