@vivantel/rag-embedder-openai 1.1.0

package/README.md

@@ -0,0 +1,91 @@
+# @vivantel/rag-embedder-openai
+
+[![npm version](https://img.shields.io/npm/v/@vivantel/rag-embedder-openai.svg)](https://www.npmjs.com/package/@vivantel/rag-embedder-openai)
+
+OpenAI-compatible embedding provider for `@vivantel/rag-core`. Works with OpenAI, Azure OpenAI, GitHub Models, Ollama, LM Studio, and any OpenAI-compatible endpoint.
+
+## Installation
+
+```bash
+npm install @vivantel/rag-embedder-openai
+```
+
+## Usage
+
+### OpenAI
+
+```typescript
+import { OpenAICompatibleEmbedder } from "@vivantel/rag-embedder-openai";
+
+const embedder = new OpenAICompatibleEmbedder({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: "text-embedding-3-small",
+  dimensions: 1536,
+});
+```
+
+### GitHub Models (preset)
+
+```typescript
+import { createGitHubModelsEmbedder } from "@vivantel/rag-embedder-openai";
+
+const embedder = createGitHubModelsEmbedder({
+  token: process.env.GITHUB_TOKEN!,
+  model: "openai/text-embedding-3-small", // optional, this is the default
+});
+```
+
+### Azure OpenAI (preset)
+
+```typescript
+import { createAzureOpenAIEmbedder } from "@vivantel/rag-embedder-openai";
+
+const embedder = createAzureOpenAIEmbedder({
+  apiKey: process.env.AZURE_OPENAI_KEY!,
+  endpoint: "https://my-resource.openai.azure.com",
+  model: "text-embedding-3-small",
+});
+```
+
+### Ollama (preset)
+
+```typescript
+import { createOllamaEmbedder } from "@vivantel/rag-embedder-openai";
+
+const embedder = createOllamaEmbedder({
+  model: "nomic-embed-text",
+  dimensions: 768,
+  baseURL: "http://localhost:11434", // optional, this is the default
+});
+```
+
+## JSON config
+
+```json
+{
+  "embedder": {
+    "package": "@vivantel/rag-embedder-openai",
+    "config": {
+      "apiKey": "${GITHUB_TOKEN}",
+      "baseURL": "https://models.github.ai/inference",
+      "model": "openai/text-embedding-3-small",
+      "dimensions": 1536
+    }
+  }
+}
+```
+
+## Options
+
+| Option | Type | Required | Description |
+| --- | --- | --- | --- |
+| `apiKey` | `string` | ✓ | API key |
+| `model` | `string` | ✓ | Model identifier |
+| `dimensions` | `number` | — | Output dimensions (default: 1536) |
+| `baseURL` | `string` | — | API base URL (default: OpenAI) |
+| `organizationId` | `string` | — | OpenAI organization ID |
+| `maxRetries` | `number` | — | Retry attempts (default: 3) |
+
+## License
+
+MIT

package/dist/embedder.d.ts

@@ -0,0 +1,22 @@
+import type { EmbeddingProvider } from "@vivantel/rag-core";
+export interface OpenAICompatibleEmbedderOptions {
+    apiKey: string;
+    model: string;
+    dimensions?: number;
+    /** Defaults to https://api.openai.com/v1 */
+    baseURL?: string;
+    organizationId?: string;
+    maxRetries?: number;
+}
+export declare class OpenAICompatibleEmbedder implements EmbeddingProvider {
+    readonly name: string;
+    readonly dimensions: number;
+    readonly model: string;
+    readonly preferredBatchSize = 100;
+    private readonly client;
+    constructor(options: OpenAICompatibleEmbedderOptions);
+    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,oBAAoB,CAAC;AAG5D,MAAM,WAAW,+BAA+B;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,wBAAyB,YAAW,iBAAiB;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,kBAAkB,OAAO;IAElC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,OAAO,EAAE,+BAA+B;IAe9C,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAStC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAShD,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;CAQtC"}

package/dist/embedder.js

@@ -0,0 +1,47 @@
+import OpenAI from "openai";
+export class OpenAICompatibleEmbedder {
+    name;
+    dimensions;
+    model;
+    preferredBatchSize = 100;
+    client;
+    constructor(options) {
+        this.model = options.model;
+        this.dimensions = options.dimensions ?? 1536;
+        this.name = options.baseURL
+            ? `openai-compatible:${new URL(options.baseURL).hostname}`
+            : "openai";
+        this.client = new OpenAI({
+            apiKey: options.apiKey,
+            baseURL: options.baseURL,
+            organization: options.organizationId,
+            maxRetries: options.maxRetries ?? 3,
+        });
+    }
+    async embed(text) {
+        const res = await this.client.embeddings.create({
+            model: this.model,
+            input: text,
+            dimensions: this.dimensions !== 1536 ? this.dimensions : undefined,
+        });
+        return res.data[0].embedding;
+    }
+    async embedBatch(texts) {
+        const res = await this.client.embeddings.create({
+            model: this.model,
+            input: texts,
+            dimensions: this.dimensions !== 1536 ? this.dimensions : undefined,
+        });
+        return res.data.map((d) => d.embedding);
+    }
+    async healthCheck() {
+        try {
+            await this.embed("health check");
+            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,MAAM,MAAM,QAAQ,CAAC;AAY5B,MAAM,OAAO,wBAAwB;IAC1B,IAAI,CAAS;IACb,UAAU,CAAS;IACnB,KAAK,CAAS;IACd,kBAAkB,GAAG,GAAG,CAAC;IAEjB,MAAM,CAAS;IAEhC,YAAY,OAAwC;QAClD,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC;QAC7C,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,OAAO;YACzB,CAAC,CAAC,qBAAqB,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE;YAC1D,CAAC,CAAC,QAAQ,CAAC;QAEb,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC;YACvB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,YAAY,EAAE,OAAO,CAAC,cAAc;YACpC,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,CAAC;SACpC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;YAC9C,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,KAAK,EAAE,IAAI;YACX,UAAU,EAAE,IAAI,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;SACnE,CAAC,CAAC;QACH,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,KAAe;QAC9B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;YAC9C,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,KAAK,EAAE,KAAK;YACZ,UAAU,EAAE,IAAI,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;SACnE,CAAC,CAAC;QACH,OAAO,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,WAAW;QACf,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;YACjC,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,6 @@
+export { OpenAICompatibleEmbedder, type OpenAICompatibleEmbedderOptions, } from "./embedder.js";
+export { createGitHubModelsEmbedder, createAzureOpenAIEmbedder, createOllamaEmbedder, type GitHubModelsPresetOptions, type AzureOpenAIPresetOptions, type OllamaPresetOptions, } from "./presets.js";
+import type { EmbeddingProvider } from "@vivantel/rag-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,wBAAwB,EACxB,KAAK,+BAA+B,GACrC,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,EACpB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,GACzB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAM5D,8CAA8C;AAC9C,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,iBAAiB,CAyBnB"}

package/dist/index.js

@@ -0,0 +1,26 @@
+export { OpenAICompatibleEmbedder, } from "./embedder.js";
+export { createGitHubModelsEmbedder, createAzureOpenAIEmbedder, createOllamaEmbedder, } from "./presets.js";
+import { OpenAICompatibleEmbedder, } from "./embedder.js";
+/** Factory used by the JSON config loader. */
+export function createEmbedder(config) {
+    const apiKey = config.apiKey;
+    if (typeof apiKey !== "string" || !apiKey) {
+        throw new Error("@vivantel/rag-embedder-openai: config.apiKey is required");
+    }
+    const model = config.model;
+    if (typeof model !== "string" || !model) {
+        throw new Error("@vivantel/rag-embedder-openai: config.model is required");
+    }
+    const opts = {
+        apiKey,
+        model,
+        dimensions: typeof config.dimensions === "number" ? config.dimensions : undefined,
+        baseURL: typeof config.baseURL === "string" ? config.baseURL : undefined,
+        organizationId: typeof config.organizationId === "string"
+            ? config.organizationId
+            : undefined,
+        maxRetries: typeof config.maxRetries === "number" ? config.maxRetries : undefined,
+    };
+    return new OpenAICompatibleEmbedder(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,wBAAwB,GAEzB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,GAIrB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,wBAAwB,GAEzB,MAAM,eAAe,CAAC;AAEvB,8CAA8C;AAC9C,MAAM,UAAU,cAAc,CAC5B,MAA+B;IAE/B,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7B,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC9E,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IAED,MAAM,IAAI,GAAoC;QAC5C,MAAM;QACN,KAAK;QACL,UAAU,EACR,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;QACvE,OAAO,EAAE,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;QACxE,cAAc,EACZ,OAAO,MAAM,CAAC,cAAc,KAAK,QAAQ;YACvC,CAAC,CAAC,MAAM,CAAC,cAAc;YACvB,CAAC,CAAC,SAAS;QACf,UAAU,EACR,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;KACxE,CAAC;IAEF,OAAO,IAAI,wBAAwB,CAAC,IAAI,CAAC,CAAC;AAC5C,CAAC"}

package/dist/presets.d.ts

@@ -0,0 +1,24 @@
+import { OpenAICompatibleEmbedder } from "./embedder.js";
+export interface GitHubModelsPresetOptions {
+    token: string;
+    model?: string;
+    dimensions?: number;
+}
+export interface AzureOpenAIPresetOptions {
+    apiKey: string;
+    endpoint: string;
+    model?: string;
+    dimensions?: number;
+}
+export interface OllamaPresetOptions {
+    model: string;
+    dimensions: number;
+    baseURL?: string;
+}
+/** Pre-configured embedder for GitHub Models (OpenAI-compatible endpoint). */
+export declare function createGitHubModelsEmbedder(options: GitHubModelsPresetOptions): OpenAICompatibleEmbedder;
+/** Pre-configured embedder for Azure OpenAI. */
+export declare function createAzureOpenAIEmbedder(options: AzureOpenAIPresetOptions): OpenAICompatibleEmbedder;
+/** Pre-configured embedder for a local Ollama server. */
+export declare function createOllamaEmbedder(options: OllamaPresetOptions): OpenAICompatibleEmbedder;
+//# sourceMappingURL=presets.d.ts.map

package/dist/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../src/presets.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EAEzB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,8EAA8E;AAC9E,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,yBAAyB,GACjC,wBAAwB,CAO1B;AAED,gDAAgD;AAChD,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,wBAAwB,GAChC,wBAAwB,CAO1B;AAED,yDAAyD;AACzD,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,mBAAmB,GAC3B,wBAAwB,CAO1B"}

package/dist/presets.js

@@ -0,0 +1,29 @@
+import { OpenAICompatibleEmbedder, } from "./embedder.js";
+/** Pre-configured embedder for GitHub Models (OpenAI-compatible endpoint). */
+export function createGitHubModelsEmbedder(options) {
+    return new OpenAICompatibleEmbedder({
+        apiKey: options.token,
+        baseURL: "https://models.github.ai/inference",
+        model: options.model ?? "openai/text-embedding-3-small",
+        dimensions: options.dimensions ?? 1536,
+    });
+}
+/** Pre-configured embedder for Azure OpenAI. */
+export function createAzureOpenAIEmbedder(options) {
+    return new OpenAICompatibleEmbedder({
+        apiKey: options.apiKey,
+        baseURL: `${options.endpoint.replace(/\/$/, "")}/openai`,
+        model: options.model ?? "text-embedding-3-small",
+        dimensions: options.dimensions ?? 1536,
+    });
+}
+/** Pre-configured embedder for a local Ollama server. */
+export function createOllamaEmbedder(options) {
+    return new OpenAICompatibleEmbedder({
+        apiKey: "ollama",
+        baseURL: (options.baseURL ?? "http://localhost:11434") + "/v1",
+        model: options.model,
+        dimensions: options.dimensions,
+    });
+}
+//# sourceMappingURL=presets.js.map

package/dist/presets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.js","sourceRoot":"","sources":["../src/presets.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,GAEzB,MAAM,eAAe,CAAC;AAqBvB,8EAA8E;AAC9E,MAAM,UAAU,0BAA0B,CACxC,OAAkC;IAElC,OAAO,IAAI,wBAAwB,CAAC;QAClC,MAAM,EAAE,OAAO,CAAC,KAAK;QACrB,OAAO,EAAE,oCAAoC;QAC7C,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,+BAA+B;QACvD,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI;KACvC,CAAC,CAAC;AACL,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,yBAAyB,CACvC,OAAiC;IAEjC,OAAO,IAAI,wBAAwB,CAAC;QAClC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS;QACxD,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,wBAAwB;QAChD,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI;KACvC,CAAC,CAAC;AACL,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,oBAAoB,CAClC,OAA4B;IAE5B,OAAO,IAAI,wBAAwB,CAAC;QAClC,MAAM,EAAE,QAAQ;QAChB,OAAO,EAAE,CAAC,OAAO,CAAC,OAAO,IAAI,wBAAwB,CAAC,GAAG,KAAK;QAC9D,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,UAAU,EAAE,OAAO,CAAC,UAAU;KACI,CAAC,CAAC;AACxC,CAAC"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@vivantel/rag-embedder-openai",
+  "version": "1.1.0",
+  "description": "OpenAI-compatible 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",
+    "openai",
+    "azure",
+    "github-models"
+  ],
+  "author": "Vivantel",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vivantel/rag_core",
+    "directory": "packages/rag-embedder-openai"
+  },
+  "dependencies": {
+    "openai": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@vivantel/rag-core": "^2.0.0"
+  },
+  "devDependencies": {
+    "@vivantel/rag-core": "file:../rag-core",
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}