@anvia/fastembed 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Indra Zulfi
+
+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,90 @@
+# @anvia/fastembed
+
+FastEmbed embedding model adapter for Anvia.
+
+Use this package when you want local embedding generation through `fastembed`, especially for RAG workflows that should avoid remote embedding APIs.
+
+## Installation
+
+```sh
+pnpm add @anvia/fastembed @anvia/core fastembed
+```
+
+In this monorepo, the package is available through the workspace:
+
+```sh
+pnpm --filter @anvia/fastembed build
+```
+
+## Usage
+
+```ts
+import { embedDocuments, InMemoryVectorStore } from "@anvia/core";
+import { createFastEmbedEmbeddingModel } from "@anvia/fastembed";
+
+const embeddingModel = await createFastEmbedEmbeddingModel();
+
+const documents = await embedDocuments(
+  embeddingModel,
+  [
+    {
+      id: "password-reset",
+      title: "Password reset policy",
+      body: "Password reset links expire after 30 minutes.",
+    },
+    {
+      id: "priority-support",
+      title: "Priority support",
+      body: "Enterprise customers receive priority support.",
+    },
+  ],
+  {
+    id: (document) => document.id,
+    content: (document) => `${document.title}\n${document.body}`,
+  },
+);
+
+const store = InMemoryVectorStore.fromDocuments(documents);
+const index = store.index(embeddingModel);
+
+const results = await index.search({
+  query: "How long does a password reset link last?",
+  topK: 3,
+});
+
+console.log(results);
+```
+
+## Default Model
+
+The default embedding model is:
+
+```ts
+fast-bge-small-en-v1.5
+```
+
+You can pass another FastEmbed model name:
+
+```ts
+const embeddingModel = await createFastEmbedEmbeddingModel({
+  model: "fast-bge-base-en-v1.5",
+  maxBatchSize: 32,
+});
+```
+
+## Exports
+
+- `FastEmbedEmbeddingModel`
+- `createFastEmbedEmbeddingModel`
+- `DEFAULT_FASTEMBED_EMBEDDING_MODEL`
+- `FastEmbedEmbeddingModelName`
+- `FastEmbedEmbeddingModelOptions`
+- `FastEmbedRuntime`
+
+## Development
+
+```sh
+pnpm --filter @anvia/fastembed typecheck
+pnpm --filter @anvia/fastembed test
+pnpm --filter @anvia/fastembed build
+```

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { EmbeddingModel, Embedding } from '@anvia/core';
+import { EmbeddingModel as EmbeddingModel$1, ExecutionProvider } from 'fastembed';
+
+declare const DEFAULT_FASTEMBED_EMBEDDING_MODEL = FastEmbedModel.BGESmallENV15;
+type FastEmbedEmbeddingModelName = `${Exclude<EmbeddingModel$1, EmbeddingModel$1.CUSTOM>}`;
+type FastEmbedRuntime = {
+    embed(texts: string[], batchSize?: number): AsyncIterable<unknown>;
+};
+type FastEmbedEmbeddingModelOptions = {
+    model?: FastEmbedEmbeddingModelName | undefined;
+    maxBatchSize?: number | undefined;
+    initOptions?: {
+        executionProviders?: ExecutionProvider[] | undefined;
+        maxLength?: number | undefined;
+        cacheDir?: string | undefined;
+        showDownloadProgress?: boolean | undefined;
+        modelName?: string | undefined;
+    } | undefined;
+};
+declare class FastEmbedEmbeddingModel implements EmbeddingModel {
+    private readonly runtime;
+    readonly model: string;
+    readonly maxBatchSize: number;
+    constructor(runtime: FastEmbedRuntime, options?: FastEmbedEmbeddingModelOptions);
+    static create(options?: FastEmbedEmbeddingModelOptions): Promise<FastEmbedEmbeddingModel>;
+    embedTexts(texts: string[]): Promise<Embedding[]>;
+}
+declare function createFastEmbedEmbeddingModel(options?: FastEmbedEmbeddingModelOptions): Promise<FastEmbedEmbeddingModel>;
+
+export { DEFAULT_FASTEMBED_EMBEDDING_MODEL, FastEmbedEmbeddingModel, type FastEmbedEmbeddingModelName, type FastEmbedEmbeddingModelOptions, type FastEmbedRuntime, createFastEmbedEmbeddingModel };

package/dist/index.js

@@ -0,0 +1,71 @@
+// src/index.ts
+import { EmbeddingModel as FastEmbedModel, FlagEmbedding } from "fastembed";
+var DEFAULT_FASTEMBED_EMBEDDING_MODEL = FastEmbedModel.BGESmallENV15;
+var FastEmbedEmbeddingModel = class _FastEmbedEmbeddingModel {
+  constructor(runtime, options = {}) {
+    this.runtime = runtime;
+    this.model = options.model ?? DEFAULT_FASTEMBED_EMBEDDING_MODEL;
+    this.maxBatchSize = Math.max(1, Math.trunc(options.maxBatchSize ?? 256));
+  }
+  runtime;
+  model;
+  maxBatchSize;
+  static async create(options = {}) {
+    const model = options.model ?? DEFAULT_FASTEMBED_EMBEDDING_MODEL;
+    const runtime = await FlagEmbedding.init({
+      ...options.initOptions ?? {},
+      model
+    });
+    return new _FastEmbedEmbeddingModel(runtime, { ...options, model });
+  }
+  async embedTexts(texts) {
+    if (texts.length === 0) {
+      return [];
+    }
+    const vectors = [];
+    for await (const batch of this.runtime.embed(texts, this.maxBatchSize)) {
+      vectors.push(...parseBatch(batch, vectors.length));
+    }
+    if (vectors.length !== texts.length) {
+      throw new Error(
+        `FastEmbed embedding model returned ${vectors.length} embeddings for ${texts.length} texts`
+      );
+    }
+    return texts.map((document, index) => ({
+      document,
+      vector: vectors[index]
+    }));
+  }
+};
+function createFastEmbedEmbeddingModel(options = {}) {
+  return FastEmbedEmbeddingModel.create(options);
+}
+function parseBatch(batch, offset) {
+  if (!Array.isArray(batch)) {
+    throw new Error(`FastEmbed embedding model returned an invalid batch at offset ${offset}`);
+  }
+  return batch.map((vector, index) => {
+    const values = vectorToArray(vector);
+    if (values === void 0) {
+      throw new Error(
+        `FastEmbed embedding model returned an invalid vector at index ${offset + index}`
+      );
+    }
+    return values;
+  });
+}
+function vectorToArray(vector) {
+  if (Array.isArray(vector) && vector.every((item) => typeof item === "number")) {
+    return vector;
+  }
+  if (ArrayBuffer.isView(vector) && !(vector instanceof DataView)) {
+    return Array.from(vector);
+  }
+  return void 0;
+}
+export {
+  DEFAULT_FASTEMBED_EMBEDDING_MODEL,
+  FastEmbedEmbeddingModel,
+  createFastEmbedEmbeddingModel
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { Embedding, EmbeddingModel } from \"@anvia/core\";\nimport type { ExecutionProvider } from \"fastembed\";\nimport { EmbeddingModel as FastEmbedModel, FlagEmbedding } from \"fastembed\";\n\nexport const DEFAULT_FASTEMBED_EMBEDDING_MODEL = FastEmbedModel.BGESmallENV15;\n\nexport type FastEmbedEmbeddingModelName = `${Exclude<FastEmbedModel, FastEmbedModel.CUSTOM>}`;\n\nexport type FastEmbedRuntime = {\n  embed(texts: string[], batchSize?: number): AsyncIterable<unknown>;\n};\n\nexport type FastEmbedEmbeddingModelOptions = {\n  model?: FastEmbedEmbeddingModelName | undefined;\n  maxBatchSize?: number | undefined;\n  initOptions?:\n    | {\n        executionProviders?: ExecutionProvider[] | undefined;\n        maxLength?: number | undefined;\n        cacheDir?: string | undefined;\n        showDownloadProgress?: boolean | undefined;\n        modelName?: string | undefined;\n      }\n    | undefined;\n};\n\nexport class FastEmbedEmbeddingModel implements EmbeddingModel {\n  readonly model: string;\n  readonly maxBatchSize: number;\n\n  constructor(\n    private readonly runtime: FastEmbedRuntime,\n    options: FastEmbedEmbeddingModelOptions = {},\n  ) {\n    this.model = options.model ?? DEFAULT_FASTEMBED_EMBEDDING_MODEL;\n    this.maxBatchSize = Math.max(1, Math.trunc(options.maxBatchSize ?? 256));\n  }\n\n  static async create(\n    options: FastEmbedEmbeddingModelOptions = {},\n  ): Promise<FastEmbedEmbeddingModel> {\n    const model = options.model ?? DEFAULT_FASTEMBED_EMBEDDING_MODEL;\n    const runtime = await FlagEmbedding.init({\n      ...(options.initOptions ?? {}),\n      model,\n    } as never);\n\n    return new FastEmbedEmbeddingModel(runtime, { ...options, model });\n  }\n\n  async embedTexts(texts: string[]): Promise<Embedding[]> {\n    if (texts.length === 0) {\n      return [];\n    }\n\n    const vectors: number[][] = [];\n    for await (const batch of this.runtime.embed(texts, this.maxBatchSize)) {\n      vectors.push(...parseBatch(batch, vectors.length));\n    }\n\n    if (vectors.length !== texts.length) {\n      throw new Error(\n        `FastEmbed embedding model returned ${vectors.length} embeddings for ${texts.length} texts`,\n      );\n    }\n\n    return texts.map((document, index) => ({\n      document,\n      vector: vectors[index] as number[],\n    }));\n  }\n}\n\nexport function createFastEmbedEmbeddingModel(\n  options: FastEmbedEmbeddingModelOptions = {},\n): Promise<FastEmbedEmbeddingModel> {\n  return FastEmbedEmbeddingModel.create(options);\n}\n\nfunction parseBatch(batch: unknown, offset: number): number[][] {\n  if (!Array.isArray(batch)) {\n    throw new Error(`FastEmbed embedding model returned an invalid batch at offset ${offset}`);\n  }\n\n  return batch.map((vector, index) => {\n    const values = vectorToArray(vector);\n    if (values === undefined) {\n      throw new Error(\n        `FastEmbed embedding model returned an invalid vector at index ${offset + index}`,\n      );\n    }\n    return values;\n  });\n}\n\nfunction vectorToArray(vector: unknown): number[] | undefined {\n  if (Array.isArray(vector) && vector.every((item) => typeof item === \"number\")) {\n    return vector;\n  }\n\n  if (ArrayBuffer.isView(vector) && !(vector instanceof DataView)) {\n    return Array.from(vector as unknown as ArrayLike<number>);\n  }\n\n  return undefined;\n}\n"],"mappings":";AAEA,SAAS,kBAAkB,gBAAgB,qBAAqB;AAEzD,IAAM,oCAAoC,eAAe;AAsBzD,IAAM,0BAAN,MAAM,yBAAkD;AAAA,EAI7D,YACmB,SACjB,UAA0C,CAAC,GAC3C;AAFiB;AAGjB,SAAK,QAAQ,QAAQ,SAAS;AAC9B,SAAK,eAAe,KAAK,IAAI,GAAG,KAAK,MAAM,QAAQ,gBAAgB,GAAG,CAAC;AAAA,EACzE;AAAA,EALmB;AAAA,EAJV;AAAA,EACA;AAAA,EAUT,aAAa,OACX,UAA0C,CAAC,GACT;AAClC,UAAM,QAAQ,QAAQ,SAAS;AAC/B,UAAM,UAAU,MAAM,cAAc,KAAK;AAAA,MACvC,GAAI,QAAQ,eAAe,CAAC;AAAA,MAC5B;AAAA,IACF,CAAU;AAEV,WAAO,IAAI,yBAAwB,SAAS,EAAE,GAAG,SAAS,MAAM,CAAC;AAAA,EACnE;AAAA,EAEA,MAAM,WAAW,OAAuC;AACtD,QAAI,MAAM,WAAW,GAAG;AACtB,aAAO,CAAC;AAAA,IACV;AAEA,UAAM,UAAsB,CAAC;AAC7B,qBAAiB,SAAS,KAAK,QAAQ,MAAM,OAAO,KAAK,YAAY,GAAG;AACtE,cAAQ,KAAK,GAAG,WAAW,OAAO,QAAQ,MAAM,CAAC;AAAA,IACnD;AAEA,QAAI,QAAQ,WAAW,MAAM,QAAQ;AACnC,YAAM,IAAI;AAAA,QACR,sCAAsC,QAAQ,MAAM,mBAAmB,MAAM,MAAM;AAAA,MACrF;AAAA,IACF;AAEA,WAAO,MAAM,IAAI,CAAC,UAAU,WAAW;AAAA,MACrC;AAAA,MACA,QAAQ,QAAQ,KAAK;AAAA,IACvB,EAAE;AAAA,EACJ;AACF;AAEO,SAAS,8BACd,UAA0C,CAAC,GACT;AAClC,SAAO,wBAAwB,OAAO,OAAO;AAC/C;AAEA,SAAS,WAAW,OAAgB,QAA4B;AAC9D,MAAI,CAAC,MAAM,QAAQ,KAAK,GAAG;AACzB,UAAM,IAAI,MAAM,iEAAiE,MAAM,EAAE;AAAA,EAC3F;AAEA,SAAO,MAAM,IAAI,CAAC,QAAQ,UAAU;AAClC,UAAM,SAAS,cAAc,MAAM;AACnC,QAAI,WAAW,QAAW;AACxB,YAAM,IAAI;AAAA,QACR,iEAAiE,SAAS,KAAK;AAAA,MACjF;AAAA,IACF;AACA,WAAO;AAAA,EACT,CAAC;AACH;AAEA,SAAS,cAAc,QAAuC;AAC5D,MAAI,MAAM,QAAQ,MAAM,KAAK,OAAO,MAAM,CAAC,SAAS,OAAO,SAAS,QAAQ,GAAG;AAC7E,WAAO;AAAA,EACT;AAEA,MAAI,YAAY,OAAO,MAAM,KAAK,EAAE,kBAAkB,WAAW;AAC/D,WAAO,MAAM,KAAK,MAAsC;AAAA,EAC1D;AAEA,SAAO;AACT;","names":[]}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@anvia/fastembed",
+  "version": "0.1.0",
+  "description": "FastEmbed embedding model adapter for Anvia.",
+  "author": "anvia",
+  "maintainer": "Indra Zulfi",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "fastembed": "^2.1.0",
+    "@anvia/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.9.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.8"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --sourcemap --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}