@kybernesis/brain-embed-openai 0.7.0

package/README.md

@@ -0,0 +1,43 @@
+# @kybernesis/brain-embed-openai
+
+Portable OpenAI embedding provider for [`@kybernesis/brain-core`](../brain-core)'s
+`EmbeddingProvider` seam. It **produces** vectors (`text-embedding-3-small`, 1536-dim);
+the vector **store** lives separately in
+[`@kybernesis/brain-storage-vec`](../brain-storage-vec). See the
+[0.8.0 kickoff](../../docs/specs/embedding-provider-0.8.0-kickoff.md) §3.5 for why the
+embedder sits in the inference plane, not the storage plane.
+
+## Usage
+
+```ts
+import { createOpenAIEmbedder } from '@kybernesis/brain-embed-openai';
+import { setEmbeddingProvider } from '@kybernesis/brain-core';
+
+setEmbeddingProvider(createOpenAIEmbedder());
+```
+
+Once wired, `indexChunk` populates `vectors.db` and `semanticSearch` returns real
+results. Without it, brain-core's vector path no-ops (the seam's default).
+
+## Key resolution (tenant-aware)
+
+The provider resolves `OPENAI_API_KEY` **per tenant**:
+
+1. `<tenant.paths.home>/.env` — where the agent's per-brain key is written;
+2. `process.env.OPENAI_API_KEY` — daemon-global fallback.
+
+One OpenAI client is cached per `tenant.slug`. A tenant with no key degrades to `null`
+(no embedding) rather than throwing — so a mixed fleet (some agents keyed, some not)
+behaves per-agent.
+
+## `openai` is an optional peer dependency
+
+The host application provides the `openai` SDK (`>=4`). Tests inject a fake client via
+`createOpenAIEmbedder({ clientFactory })`, so the package builds and tests without it.
+
+## Constraint: 1536 dimensions
+
+The vector store schema is built for `EMBEDDING_DIM = 1536`. A different embedding model
+must emit 1536-dim vectors, or `EMBEDDING_DIM` + the `vectors.db` schema move together
+and you re-index. Don't mix models within one populated `vectors.db` — distances across
+models aren't comparable.

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @kybernesis/brain-embed-openai
+ *
+ * Portable OpenAI embedding provider for brain-core's `EmbeddingProvider`
+ * seam. Lives in the INFERENCE plane (next to brain-llm-claude) — it produces
+ * vectors; the vector STORE stays in brain-storage-vec (see the 0.8.0 kickoff
+ * §3.5).
+ *
+ * Absorbs the hard-won behaviour from KAD commit df80ea6:
+ *   - resolve OPENAI_API_KEY per tenant from `<home>/.env` (where the Settings
+ *     UI writes per-agent keys), falling back to `process.env`;
+ *   - cache one OpenAI client per tenant (the multi-agent daemon doesn't
+ *     inherit any one agent's `.env`) — keyed on `t.slug`.
+ * The name-vs-path normalization KAD needed is GONE here: TenantContext is the
+ * clean identity, so `t.paths.home` + `t.slug` replace the registry lookups.
+ *
+ * Usage:
+ *   import { createOpenAIEmbedder } from '@kybernesis/brain-embed-openai';
+ *   import { setEmbeddingProvider } from '@kybernesis/brain-core';
+ *   setEmbeddingProvider(createOpenAIEmbedder());
+ */
+import type { TenantContext } from '@kybernesis/brain-contracts';
+import type { EmbeddingProvider } from '@kybernesis/brain-core';
+export declare const EMBEDDING_MODEL = "text-embedding-3-small";
+/** The slice of the OpenAI SDK surface we use — keeps us decoupled from its types. */
+export interface OpenAILike {
+    embeddings: {
+        create(args: {
+            model: string;
+            input: string;
+        }): Promise<{
+            data: Array<{
+                embedding: number[];
+            }>;
+        }>;
+    };
+}
+/** Build an OpenAI-like client from a resolved key. May be async (the default dynamic-imports `openai`). */
+export type OpenAIClientFactory = (apiKey: string) => OpenAILike | Promise<OpenAILike>;
+export interface OpenAIEmbedderOptions {
+    /** Inject a client factory (tests pass a fake; default dynamically imports `openai`). */
+    clientFactory?: OpenAIClientFactory;
+    /** Override the embedding model (default `text-embedding-3-small`). */
+    model?: string;
+}
+/** Resolve the OpenAI key for a tenant: `<home>/.env` first, then `process.env`. */
+export declare function resolveOpenAIKey(t: TenantContext): string | null;
+/**
+ * Create a tenant-aware OpenAI `EmbeddingProvider`. One client is resolved and
+ * cached per `t.slug`; tenants without a key degrade to `null` (brain-core
+ * treats that as "no embedding" — indexChunk no-ops, semanticSearch returns []).
+ */
+export declare function createOpenAIEmbedder(opts?: OpenAIEmbedderOptions): 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;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,eAAO,MAAM,eAAe,2BAA2B,CAAC;AAIxD,sFAAsF;AACtF,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE;QACV,MAAM,CAAC,IAAI,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,GAAG,OAAO,CAAC;YAAE,IAAI,EAAE,KAAK,CAAC;gBAAE,SAAS,EAAE,MAAM,EAAE,CAAA;aAAE,CAAC,CAAA;SAAE,CAAC,CAAC;KACnG,CAAC;CACH;AAED,4GAA4G;AAC5G,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEvF,MAAM,WAAW,qBAAqB;IACpC,yFAAyF;IACzF,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAiCD,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAKhE;AAcD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,qBAA0B,GAAG,iBAAiB,CAoCxF"}

package/dist/index.js

@@ -0,0 +1,125 @@
+/**
+ * @kybernesis/brain-embed-openai
+ *
+ * Portable OpenAI embedding provider for brain-core's `EmbeddingProvider`
+ * seam. Lives in the INFERENCE plane (next to brain-llm-claude) — it produces
+ * vectors; the vector STORE stays in brain-storage-vec (see the 0.8.0 kickoff
+ * §3.5).
+ *
+ * Absorbs the hard-won behaviour from KAD commit df80ea6:
+ *   - resolve OPENAI_API_KEY per tenant from `<home>/.env` (where the Settings
+ *     UI writes per-agent keys), falling back to `process.env`;
+ *   - cache one OpenAI client per tenant (the multi-agent daemon doesn't
+ *     inherit any one agent's `.env`) — keyed on `t.slug`.
+ * The name-vs-path normalization KAD needed is GONE here: TenantContext is the
+ * clean identity, so `t.paths.home` + `t.slug` replace the registry lookups.
+ *
+ * Usage:
+ *   import { createOpenAIEmbedder } from '@kybernesis/brain-embed-openai';
+ *   import { setEmbeddingProvider } from '@kybernesis/brain-core';
+ *   setEmbeddingProvider(createOpenAIEmbedder());
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const EMBEDDING_MODEL = 'text-embedding-3-small';
+const EMBEDDING_DIM = 1536; // text-embedding-3-small; must match the vectors.db schema
+const INPUT_CHAR_CAP = 8192; // hard cap, mirrors KAD df80ea6
+/**
+ * Parse `<home>/.env` into a key→value map. Trivial KEY=VALUE parser (strips
+ * `#` comments and surrounding quotes) — we only need OPENAI_API_KEY, so a full
+ * dotenv dep is overkill. Returns {} if the file is missing or unreadable.
+ */
+function readEnvFile(home) {
+    const path = join(home, '.env');
+    if (!existsSync(path))
+        return {};
+    try {
+        const out = {};
+        for (const raw of readFileSync(path, 'utf-8').split('\n')) {
+            const line = raw.trim();
+            if (!line || line.startsWith('#'))
+                continue;
+            const eq = line.indexOf('=');
+            if (eq <= 0)
+                continue;
+            const key = line.slice(0, eq).trim();
+            let value = line.slice(eq + 1).trim();
+            if ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'"))) {
+                value = value.slice(1, -1);
+            }
+            if (key)
+                out[key] = value;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/** Resolve the OpenAI key for a tenant: `<home>/.env` first, then `process.env`. */
+export function resolveOpenAIKey(t) {
+    const fromEnv = readEnvFile(t.paths.home)['OPENAI_API_KEY'];
+    if (fromEnv && fromEnv.trim().length > 0)
+        return fromEnv.trim();
+    const fromProc = process.env['OPENAI_API_KEY'];
+    return fromProc && fromProc.trim().length > 0 ? fromProc.trim() : null;
+}
+let _openaiModule = null;
+async function defaultClientFactory(apiKey) {
+    if (!_openaiModule) {
+        // Dynamic import keeps `openai` an OPTIONAL peer — the host provides it.
+        _openaiModule = await import('openai');
+    }
+    const mod = _openaiModule;
+    const OpenAI = mod.default ?? mod.OpenAI;
+    if (!OpenAI)
+        throw new Error('openai SDK has no default/OpenAI export');
+    return new OpenAI({ apiKey });
+}
+/**
+ * Create a tenant-aware OpenAI `EmbeddingProvider`. One client is resolved and
+ * cached per `t.slug`; tenants without a key degrade to `null` (brain-core
+ * treats that as "no embedding" — indexChunk no-ops, semanticSearch returns []).
+ */
+export function createOpenAIEmbedder(opts = {}) {
+    const model = opts.model ?? EMBEDDING_MODEL;
+    const makeClient = opts.clientFactory ?? defaultClientFactory;
+    const clients = new Map(); // by t.slug; null = resolved-no-key
+    async function getClient(t) {
+        if (clients.has(t.slug))
+            return clients.get(t.slug) ?? null;
+        const key = resolveOpenAIKey(t);
+        if (!key) {
+            clients.set(t.slug, null);
+            return null;
+        }
+        try {
+            const client = await makeClient(key);
+            clients.set(t.slug, client);
+            return client;
+        }
+        catch {
+            clients.set(t.slug, null);
+            return null;
+        }
+    }
+    return {
+        async embed(t, text) {
+            const client = await getClient(t);
+            if (!client)
+                return null;
+            try {
+                const res = await client.embeddings.create({ model, input: text.slice(0, INPUT_CHAR_CAP) });
+                const vec = res.data?.[0]?.embedding ?? null;
+                if (!vec || vec.length !== EMBEDDING_DIM)
+                    return null;
+                return vec;
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@kybernesis/brain-embed-openai",
+  "version": "0.7.0",
+  "description": "OpenAI text-embedding provider for brain-core (inference-plane EmbeddingProvider)",
+  "license": "MIT",
+  "author": "David Cruwys (AppyDave)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KybernesisAI/cortex.git",
+    "directory": "packages/brain-embed-openai"
+  },
+  "homepage": "https://github.com/KybernesisAI/cortex/tree/main/packages/brain-embed-openai#readme",
+  "bugs": {
+    "url": "https://github.com/KybernesisAI/cortex/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "openai": ">=4",
+    "@kybernesis/brain-contracts": "0.8.0",
+    "@kybernesis/brain-core": "0.8.0"
+  },
+  "peerDependenciesMeta": {
+    "openai": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@kybernesis/brain-contracts": "0.8.0",
+    "@kybernesis/brain-testkit": "0.8.0",
+    "@kybernesis/brain-core": "0.8.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "typecheck": "tsc -b"
+  }
+}