@voyantjs/catalog-rag 0.19.0

package/dist/embeddings/model-registry.js

@@ -0,0 +1,78 @@
+/**
+ * Embedding model registry helpers.
+ *
+ * Each search-index document carries an `embedding_model_id` field that
+ * identifies which model produced its vector. The registry's job is to:
+ *
+ *   1. Validate at deployment startup that the configured embedding
+ *      provider's `dimensions` matches the configured `IndexerAdapter`'s
+ *      `vectorDimensions`. Mismatch → fail loudly.
+ *   2. Track the active model id so search queries can scope vector
+ *      lookups to documents using a compatible model. During a model
+ *      migration window the index can hold mixed-model documents — old
+ *      ones get skipped on vector queries and re-embedded by the
+ *      `bulkReindex(forceReembed: true)` job.
+ *
+ * See `docs/architecture/catalog-rag-architecture.md` §8.
+ */
+/**
+ * Validate that an embedding provider's capabilities are compatible with
+ * the search engine's vector configuration. Call this at deployment
+ * startup; throw if incompatible.
+ */
+export function validateEmbeddingCompatibility(providerCapabilities, indexerCapabilities) {
+    if (!indexerCapabilities.supportsVectorFields) {
+        throw new Error(`IndexerAdapter does not support vector fields, but an embedding provider is configured (model: ${providerCapabilities.modelId}). ` +
+            `Disable embeddings or swap to an indexer that supports them (e.g. Typesense).`);
+    }
+    if (indexerCapabilities.vectorDimensions != null &&
+        indexerCapabilities.vectorDimensions !== providerCapabilities.dimensions) {
+        throw new Error(`Embedding model ${providerCapabilities.modelId} produces ${providerCapabilities.dimensions}-d vectors, ` +
+            `but IndexerAdapter is configured for ${indexerCapabilities.vectorDimensions}-d. ` +
+            `Either reconfigure the indexer's vectorDimensions, or swap to a compatible embedding model.`);
+    }
+    if (indexerCapabilities.maxVectorsPerDocument != null &&
+        indexerCapabilities.maxVectorsPerDocument < 1) {
+        throw new Error(`IndexerAdapter declares maxVectorsPerDocument=${indexerCapabilities.maxVectorsPerDocument} but Phase 2 requires at least 1 vector per document.`);
+    }
+}
+/**
+ * Returns true if a given document's `embedding_model_id` matches the
+ * deployment's active model. Vector queries should filter to active-model
+ * documents; non-matching documents fall through to keyword-only
+ * scoring until `bulkReindex(forceReembed: true)` re-embeds them.
+ */
+export function isActiveEmbeddingModel(documentModelId, activeModelId) {
+    return documentModelId === activeModelId;
+}
+/**
+ * Convenience: stamp an `IndexerDocument`'s `embedding_model_id` from a
+ * provider's capabilities. Use this when constructing documents in the
+ * embedding pipeline so the active model id propagates to the index.
+ */
+export function stampEmbeddingModelId(providerCapabilities) {
+    return { embedding_model_id: providerCapabilities.modelId };
+}
+export function planEmbeddingMigration(documents, activeModelId) {
+    const embedded = [];
+    const pending = [];
+    const migrating = [];
+    for (const doc of documents) {
+        if (!doc.embedding_model_id) {
+            pending.push(doc.id);
+        }
+        else if (doc.embedding_model_id === activeModelId) {
+            embedded.push(doc.id);
+        }
+        else {
+            migrating.push(doc.id);
+        }
+    }
+    return {
+        embedded,
+        pending,
+        migrating,
+        totalDocuments: documents.length,
+        activeModelId,
+    };
+}

package/dist/embeddings/model-registry.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=model-registry.test.d.ts.map

package/dist/embeddings/model-registry.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-registry.test.d.ts","sourceRoot":"","sources":["../../src/embeddings/model-registry.test.ts"],"names":[],"mappings":""}

package/dist/embeddings/model-registry.test.js

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import { isActiveEmbeddingModel, planEmbeddingMigration, stampEmbeddingModelId, validateEmbeddingCompatibility, } from "./model-registry.js";
+const provider = {
+    modelId: "openai/text-embedding-3-small/v1",
+    dimensions: 1536,
+    maxTokensPerInput: 8191,
+    maxBatchSize: 2048,
+    supportedLanguages: null,
+};
+const indexerCompatible = {
+    supportsKeywordSearch: true,
+    supportsHybridSearch: true,
+    supportsVectorFields: true,
+    vectorDimensions: 1536,
+    maxVectorsPerDocument: null,
+    supportsCrossAudienceFederation: true,
+    supportsAdminDenormalization: true,
+};
+describe("validateEmbeddingCompatibility", () => {
+    it("succeeds when dimensions match", () => {
+        expect(() => validateEmbeddingCompatibility(provider, indexerCompatible)).not.toThrow();
+    });
+    it("throws when the indexer does not support vector fields", () => {
+        expect(() => validateEmbeddingCompatibility(provider, {
+            ...indexerCompatible,
+            supportsVectorFields: false,
+        })).toThrow(/does not support vector fields/);
+    });
+    it("throws when dimensions mismatch", () => {
+        expect(() => validateEmbeddingCompatibility(provider, { ...indexerCompatible, vectorDimensions: 768 })).toThrow(/1536-d/);
+    });
+    it("accepts null vectorDimensions on the indexer (deferred config)", () => {
+        expect(() => validateEmbeddingCompatibility(provider, { ...indexerCompatible, vectorDimensions: null })).not.toThrow();
+    });
+    it("throws when maxVectorsPerDocument is < 1", () => {
+        expect(() => validateEmbeddingCompatibility(provider, {
+            ...indexerCompatible,
+            maxVectorsPerDocument: 0,
+        })).toThrow(/at least 1 vector/);
+    });
+});
+describe("isActiveEmbeddingModel", () => {
+    it("returns true when ids match", () => {
+        expect(isActiveEmbeddingModel(provider.modelId, provider.modelId)).toBe(true);
+    });
+    it("returns false for missing or mismatched ids", () => {
+        expect(isActiveEmbeddingModel(undefined, provider.modelId)).toBe(false);
+        expect(isActiveEmbeddingModel("openai/text-embedding-3-large/v1", provider.modelId)).toBe(false);
+    });
+});
+describe("stampEmbeddingModelId", () => {
+    it("returns an object with the model id from capabilities", () => {
+        expect(stampEmbeddingModelId(provider)).toEqual({
+            embedding_model_id: provider.modelId,
+        });
+    });
+});
+describe("planEmbeddingMigration", () => {
+    it("partitions documents into embedded / pending / migrating", () => {
+        const docs = [
+            { id: "a", embedding_model_id: "openai/text-embedding-3-small/v1" },
+            { id: "b", embedding_model_id: undefined },
+            { id: "c", embedding_model_id: null },
+            { id: "d", embedding_model_id: "openai/text-embedding-ada-002/v1" },
+            { id: "e", embedding_model_id: "openai/text-embedding-3-small/v1" },
+        ];
+        const plan = planEmbeddingMigration(docs, "openai/text-embedding-3-small/v1");
+        expect(plan.embedded.sort()).toEqual(["a", "e"]);
+        expect(plan.pending.sort()).toEqual(["b", "c"]);
+        expect(plan.migrating).toEqual(["d"]);
+        expect(plan.totalDocuments).toBe(5);
+        expect(plan.activeModelId).toBe("openai/text-embedding-3-small/v1");
+    });
+    it("handles an empty document list", () => {
+        const plan = planEmbeddingMigration([], "x");
+        expect(plan.totalDocuments).toBe(0);
+        expect(plan.embedded).toEqual([]);
+        expect(plan.pending).toEqual([]);
+        expect(plan.migrating).toEqual([]);
+    });
+});

package/dist/embeddings/openai.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Default EmbeddingProvider implementation backed by OpenAI's embeddings API.
+ *
+ * Uses native `fetch` so it works in Cloudflare Workers + Node + browsers
+ * without an SDK dependency. Templates pass in the API key (and optionally
+ * a custom `baseUrl` for proxies / Azure OpenAI / OpenRouter etc.).
+ *
+ * Models supported by default:
+ *   - `text-embedding-3-small` — 1536d, multilingual, cheapest. **Default.**
+ *   - `text-embedding-3-large` — 3072d, multilingual, higher quality.
+ *   - `text-embedding-ada-002` — 1536d, legacy (kept for migration paths).
+ *
+ * See `docs/architecture/catalog-rag-architecture.md` §6 for the design.
+ */
+import { type EmbeddingProvider } from "./contract.js";
+/**
+ * Known OpenAI embedding models. Adding a new entry here is the only place
+ * to touch when OpenAI ships a new model — `createOpenAIEmbeddingProvider`
+ * picks up the dimensions / batch limits automatically.
+ */
+declare const OPENAI_MODELS: {
+    readonly "text-embedding-3-small": {
+        readonly dimensions: 1536;
+        readonly maxTokensPerInput: 8191;
+        readonly maxBatchSize: 2048;
+        readonly multilingual: true;
+    };
+    readonly "text-embedding-3-large": {
+        readonly dimensions: 3072;
+        readonly maxTokensPerInput: 8191;
+        readonly maxBatchSize: 2048;
+        readonly multilingual: true;
+    };
+    readonly "text-embedding-ada-002": {
+        readonly dimensions: 1536;
+        readonly maxTokensPerInput: 8191;
+        readonly maxBatchSize: 2048;
+        readonly multilingual: true;
+    };
+};
+export type OpenAIEmbeddingModel = keyof typeof OPENAI_MODELS;
+export interface OpenAIEmbeddingProviderOptions {
+    /** OpenAI API key. */
+    apiKey: string;
+    /**
+     * Embedding model to use. Default: `text-embedding-3-small`.
+     * Switching models is a deliberate `bulkReindex` operation — the catalog
+     * plane scopes vector queries to documents matching the active
+     * `embedding_model_id`, so mid-migration mixes are handled cleanly.
+     */
+    model?: OpenAIEmbeddingModel;
+    /**
+     * Override the API base URL — useful for Azure OpenAI, OpenRouter,
+     * a corporate proxy, or any OpenAI-API-compatible service. Default:
+     * `https://api.openai.com/v1`.
+     */
+    baseUrl?: string;
+    /**
+     * Optional `fetch` override for testing or custom transport. Default:
+     * the global `fetch`. Must follow the standard Fetch API contract.
+     */
+    fetchImpl?: typeof fetch;
+    /**
+     * Override the model id stamped onto search-index documents. Defaults
+     * to `openai/<model>/v1` — keep this stable across deployments so
+     * documents stay queryable across instances.
+     */
+    modelId?: string;
+}
+/**
+ * Build the default OpenAI EmbeddingProvider.
+ */
+export declare function createOpenAIEmbeddingProvider(options: OpenAIEmbeddingProviderOptions): EmbeddingProvider;
+/**
+ * Helper that chunks a large input array into batches sized to the model's
+ * `maxBatchSize` and concatenates the per-batch results. Use this when
+ * embedding more than `maxBatchSize` texts at once.
+ */
+export declare function embedBatched(provider: EmbeddingProvider, texts: string[]): Promise<number[][]>;
+export { OPENAI_MODELS };
+//# sourceMappingURL=openai.d.ts.map

package/dist/embeddings/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/embeddings/openai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAKL,KAAK,iBAAiB,EAGvB,MAAM,eAAe,CAAA;AAEtB;;;;GAIG;AACH,QAAA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;CAmBT,CAAA;AAEV,MAAM,MAAM,oBAAoB,GAAG,MAAM,OAAO,aAAa,CAAA;AAE7D,MAAM,WAAW,8BAA8B;IAC7C,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,KAAK,CAAC,EAAE,oBAAoB,CAAA;IAC5B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAaD;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,8BAA8B,GACtC,iBAAiB,CAyEnB;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,MAAM,EAAE,GACd,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAWrB;AAED,OAAO,EAAE,aAAa,EAAE,CAAA"}

package/dist/embeddings/openai.js

@@ -0,0 +1,123 @@
+/**
+ * Default EmbeddingProvider implementation backed by OpenAI's embeddings API.
+ *
+ * Uses native `fetch` so it works in Cloudflare Workers + Node + browsers
+ * without an SDK dependency. Templates pass in the API key (and optionally
+ * a custom `baseUrl` for proxies / Azure OpenAI / OpenRouter etc.).
+ *
+ * Models supported by default:
+ *   - `text-embedding-3-small` — 1536d, multilingual, cheapest. **Default.**
+ *   - `text-embedding-3-large` — 3072d, multilingual, higher quality.
+ *   - `text-embedding-ada-002` — 1536d, legacy (kept for migration paths).
+ *
+ * See `docs/architecture/catalog-rag-architecture.md` §6 for the design.
+ */
+import { chunkForBatch, EMBEDDING_BATCH_TOO_LARGE, EMBEDDING_INPUT_TOO_LONG, EMBEDDING_PROVIDER_ERROR, EmbeddingProviderError, } from "./contract.js";
+/**
+ * Known OpenAI embedding models. Adding a new entry here is the only place
+ * to touch when OpenAI ships a new model — `createOpenAIEmbeddingProvider`
+ * picks up the dimensions / batch limits automatically.
+ */
+const OPENAI_MODELS = {
+    "text-embedding-3-small": {
+        dimensions: 1536,
+        maxTokensPerInput: 8191,
+        maxBatchSize: 2048,
+        multilingual: true,
+    },
+    "text-embedding-3-large": {
+        dimensions: 3072,
+        maxTokensPerInput: 8191,
+        maxBatchSize: 2048,
+        multilingual: true,
+    },
+    "text-embedding-ada-002": {
+        dimensions: 1536,
+        maxTokensPerInput: 8191,
+        maxBatchSize: 2048,
+        multilingual: true,
+    },
+};
+/**
+ * Build the default OpenAI EmbeddingProvider.
+ */
+export function createOpenAIEmbeddingProvider(options) {
+    const model = options.model ?? "text-embedding-3-small";
+    const modelInfo = OPENAI_MODELS[model];
+    const baseUrl = (options.baseUrl ?? "https://api.openai.com/v1").replace(/\/$/, "");
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    const capabilities = {
+        modelId: options.modelId ?? `openai/${model}/v1`,
+        dimensions: modelInfo.dimensions,
+        maxTokensPerInput: modelInfo.maxTokensPerInput,
+        maxBatchSize: modelInfo.maxBatchSize,
+        supportedLanguages: modelInfo.multilingual ? null : undefined,
+    };
+    return {
+        capabilities,
+        async embed(texts) {
+            if (texts.length === 0)
+                return [];
+            if (texts.length > capabilities.maxBatchSize) {
+                throw new EmbeddingProviderError(EMBEDDING_BATCH_TOO_LARGE, `OpenAI embedding batch size ${texts.length} exceeds max ${capabilities.maxBatchSize}; chunk inputs via chunkForBatch() first`);
+            }
+            // Rough byte-length sanity check — actual token limits enforced by API.
+            // We pass through and let OpenAI return its specific error if too long.
+            const url = `${baseUrl}/embeddings`;
+            const body = JSON.stringify({ input: texts, model });
+            let response;
+            try {
+                response = await fetchImpl(url, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        Authorization: `Bearer ${options.apiKey}`,
+                    },
+                    body,
+                });
+            }
+            catch (cause) {
+                throw new EmbeddingProviderError(EMBEDDING_PROVIDER_ERROR, "OpenAI embeddings request failed at the network layer", cause);
+            }
+            if (!response.ok) {
+                const text = await response.text().catch(() => "");
+                let parsed;
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    // ignore parse failure; surface the raw text
+                }
+                const message = parsed?.error?.message ?? text ?? `HTTP ${response.status}`;
+                const code = parsed?.error?.code === "context_length_exceeded"
+                    ? EMBEDDING_INPUT_TOO_LONG
+                    : EMBEDDING_PROVIDER_ERROR;
+                throw new EmbeddingProviderError(code, `OpenAI embeddings request failed (${response.status}): ${message}`);
+            }
+            const json = (await response.json());
+            // OpenAI returns vectors in `data` with explicit `index` — sort to
+            // guarantee output order matches input order regardless of API
+            // implementation detail.
+            const sorted = [...json.data].sort((a, b) => a.index - b.index);
+            return sorted.map((entry) => entry.embedding);
+        },
+    };
+}
+/**
+ * Helper that chunks a large input array into batches sized to the model's
+ * `maxBatchSize` and concatenates the per-batch results. Use this when
+ * embedding more than `maxBatchSize` texts at once.
+ */
+export async function embedBatched(provider, texts) {
+    if (texts.length <= provider.capabilities.maxBatchSize) {
+        return provider.embed(texts);
+    }
+    const batches = chunkForBatch(texts, provider.capabilities.maxBatchSize);
+    const results = [];
+    for (const batch of batches) {
+        const vectors = await provider.embed(batch);
+        results.push(...vectors);
+    }
+    return results;
+}
+export { OPENAI_MODELS };

package/dist/embeddings/openai.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=openai.test.d.ts.map

package/dist/embeddings/openai.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.test.d.ts","sourceRoot":"","sources":["../../src/embeddings/openai.test.ts"],"names":[],"mappings":""}

package/dist/embeddings/openai.test.js

@@ -0,0 +1,157 @@
+import { describe, expect, it, vi } from "vitest";
+import { EMBEDDING_BATCH_TOO_LARGE, EmbeddingProviderError } from "./contract.js";
+import { createOpenAIEmbeddingProvider, embedBatched, OPENAI_MODELS } from "./openai.js";
+function mockFetch(response) {
+    return vi.fn(async () => {
+        return new Response(typeof response.json === "function" ? JSON.stringify(await response.json()) : "", {
+            status: response.status ?? (response.ok ? 200 : 400),
+        });
+    });
+}
+describe("createOpenAIEmbeddingProvider", () => {
+    it("declares correct capabilities for the default model", () => {
+        const provider = createOpenAIEmbeddingProvider({
+            apiKey: "sk-test",
+            fetchImpl: mockFetch({ ok: true, json: async () => ({ data: [] }) }),
+        });
+        expect(provider.capabilities.modelId).toBe("openai/text-embedding-3-small/v1");
+        expect(provider.capabilities.dimensions).toBe(1536);
+        expect(provider.capabilities.maxBatchSize).toBe(2048);
+    });
+    it("uses the configured model and stamps a matching modelId", () => {
+        const provider = createOpenAIEmbeddingProvider({
+            apiKey: "sk-test",
+            model: "text-embedding-3-large",
+            fetchImpl: mockFetch({ ok: true, json: async () => ({ data: [] }) }),
+        });
+        expect(provider.capabilities.modelId).toBe("openai/text-embedding-3-large/v1");
+        expect(provider.capabilities.dimensions).toBe(OPENAI_MODELS["text-embedding-3-large"].dimensions);
+    });
+    it("returns vectors in input order even when API returns shuffled indices", async () => {
+        const provider = createOpenAIEmbeddingProvider({
+            apiKey: "sk-test",
+            fetchImpl: mockFetch({
+                ok: true,
+                json: async () => ({
+                    object: "list",
+                    model: "text-embedding-3-small",
+                    usage: { prompt_tokens: 5, total_tokens: 5 },
+                    data: [
+                        { object: "embedding", index: 2, embedding: [0.3] },
+                        { object: "embedding", index: 0, embedding: [0.1] },
+                        { object: "embedding", index: 1, embedding: [0.2] },
+                    ],
+                }),
+            }),
+        });
+        const vectors = await provider.embed(["a", "b", "c"]);
+        expect(vectors).toEqual([[0.1], [0.2], [0.3]]);
+    });
+    it("returns an empty array for an empty input without hitting the API", async () => {
+        const fetchSpy = vi.fn();
+        const provider = createOpenAIEmbeddingProvider({ apiKey: "sk-test", fetchImpl: fetchSpy });
+        const vectors = await provider.embed([]);
+        expect(vectors).toEqual([]);
+        expect(fetchSpy).not.toHaveBeenCalled();
+    });
+    it("throws EMBEDDING_BATCH_TOO_LARGE when input exceeds maxBatchSize", async () => {
+        const provider = createOpenAIEmbeddingProvider({
+            apiKey: "sk-test",
+            fetchImpl: mockFetch({ ok: true, json: async () => ({ data: [] }) }),
+        });
+        const tooMany = Array.from({ length: 2049 }, (_, i) => `text-${i}`);
+        await expect(provider.embed(tooMany)).rejects.toMatchObject({
+            code: EMBEDDING_BATCH_TOO_LARGE,
+        });
+    });
+    it("wraps non-2xx responses as EmbeddingProviderError", async () => {
+        const provider = createOpenAIEmbeddingProvider({
+            apiKey: "sk-test",
+            fetchImpl: mockFetch({
+                ok: false,
+                status: 401,
+                json: async () => ({ error: { message: "invalid api key", code: "invalid_api_key" } }),
+            }),
+        });
+        await expect(provider.embed(["x"])).rejects.toBeInstanceOf(EmbeddingProviderError);
+    });
+    it("respects a custom baseUrl (Azure / proxy / OpenRouter)", async () => {
+        const fetchSpy = vi.fn(async () => {
+            return new Response(JSON.stringify({ data: [] }), { status: 200 });
+        });
+        const provider = createOpenAIEmbeddingProvider({
+            apiKey: "sk-test",
+            baseUrl: "https://my-proxy.example.com/openai/v1/",
+            fetchImpl: fetchSpy,
+        });
+        await provider.embed(["x"]);
+        // biome-ignore lint/suspicious/noExplicitAny: vi.fn return type
+        const calledWith = fetchSpy.mock.calls[0]?.[0];
+        // Trailing slash stripped; path appended.
+        expect(calledWith).toBe("https://my-proxy.example.com/openai/v1/embeddings");
+    });
+    it("sends the api key as a Bearer header", async () => {
+        const fetchSpy = vi.fn(async () => {
+            return new Response(JSON.stringify({ data: [] }), { status: 200 });
+        });
+        const provider = createOpenAIEmbeddingProvider({
+            apiKey: "sk-test-12345",
+            fetchImpl: fetchSpy,
+        });
+        await provider.embed(["x"]);
+        // biome-ignore lint/suspicious/noExplicitAny: vi.fn return type
+        const init = fetchSpy.mock.calls[0]?.[1];
+        const headers = init.headers;
+        expect(headers.Authorization).toBe("Bearer sk-test-12345");
+    });
+});
+describe("embedBatched", () => {
+    it("returns results unchanged when input fits in a single batch", async () => {
+        const provider = createOpenAIEmbeddingProvider({
+            apiKey: "sk-test",
+            fetchImpl: mockFetch({
+                ok: true,
+                json: async () => ({
+                    data: [
+                        { index: 0, embedding: [0.1] },
+                        { index: 1, embedding: [0.2] },
+                    ],
+                }),
+            }),
+        });
+        const result = await embedBatched(provider, ["a", "b"]);
+        expect(result).toEqual([[0.1], [0.2]]);
+    });
+    it("chunks oversized inputs into batches and concatenates the results", async () => {
+        let callCount = 0;
+        const fetchImpl = vi.fn(async () => {
+            callCount++;
+            // Return one fake vector per input for whatever batch came in.
+            return new Response(JSON.stringify({
+                data: [
+                    { index: 0, embedding: [callCount * 0.1] },
+                    { index: 1, embedding: [callCount * 0.1 + 0.01] },
+                ],
+            }), { status: 200 });
+        });
+        const provider = createOpenAIEmbeddingProvider({
+            apiKey: "sk-test",
+            fetchImpl,
+            // Override capabilities by using a baseUrl trick? Easier: use the
+            // default model and pass exactly maxBatchSize+ items. But that's
+            // 2048+ which is unwieldy. Instead, since we control `embedBatched`'s
+            // chunking via `provider.capabilities.maxBatchSize`, fake a smaller
+            // batch size by constructing a minimal stub provider.
+        });
+        // Tweak capabilities for the test: replace with a tiny-batch-size proxy.
+        const tinyBatchProvider = {
+            capabilities: { ...provider.capabilities, maxBatchSize: 2 },
+            embed: provider.embed.bind(provider),
+        };
+        const result = await embedBatched(tinyBatchProvider, ["a", "b", "c", "d"]);
+        // Two batches × 2 vectors each = 4 vectors total.
+        expect(result).toHaveLength(4);
+        // biome-ignore lint/suspicious/noExplicitAny: vi.fn type
+        expect(fetchImpl.mock.calls.length).toBe(2);
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { chunkForBatch, EMBEDDING_BATCH_TOO_LARGE, EMBEDDING_INPUT_TOO_LONG, EMBEDDING_PROVIDER_ERROR, type EmbeddingProvider, type EmbeddingProviderCapabilities, EmbeddingProviderError, } from "./embeddings/contract.js";
+export { createGeminiEmbeddingProvider, GEMINI_MODELS, type GeminiEmbeddingModel, type GeminiEmbeddingProviderOptions, type GeminiTaskType, } from "./embeddings/gemini.js";
+export { type EmbeddingMigrationPlan, isActiveEmbeddingModel, planEmbeddingMigration, stampEmbeddingModelId, validateEmbeddingCompatibility, } from "./embeddings/model-registry.js";
+export { createOpenAIEmbeddingProvider, embedBatched, OPENAI_MODELS, type OpenAIEmbeddingModel, type OpenAIEmbeddingProviderOptions, } from "./embeddings/openai.js";
+export { type FederatedSearchOptions, federateAudienceSearch, mergeAndDedupe, } from "./search/federate.js";
+export { executeBYOVectorSearch, executeSemanticSearch, type SemanticSearchOptions, } from "./search/semantic.js";
+//# 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":"AACA,OAAO,EACL,aAAa,EACb,yBAAyB,EACzB,wBAAwB,EACxB,wBAAwB,EACxB,KAAK,iBAAiB,EACtB,KAAK,6BAA6B,EAClC,sBAAsB,GACvB,MAAM,0BAA0B,CAAA;AAEjC,OAAO,EACL,6BAA6B,EAC7B,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,8BAA8B,EACnC,KAAK,cAAc,GACpB,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EACL,KAAK,sBAAsB,EAC3B,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACrB,8BAA8B,GAC/B,MAAM,gCAAgC,CAAA;AAEvC,OAAO,EACL,6BAA6B,EAC7B,YAAY,EACZ,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,8BAA8B,GACpC,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,KAAK,sBAAsB,EAC3B,sBAAsB,EACtB,cAAc,GACf,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAA"}

package/dist/index.js

@@ -0,0 +1,11 @@
+// Embedding contract + standard error codes.
+export { chunkForBatch, EMBEDDING_BATCH_TOO_LARGE, EMBEDDING_INPUT_TOO_LONG, EMBEDDING_PROVIDER_ERROR, EmbeddingProviderError, } from "./embeddings/contract.js";
+// Gemini provider (Google AI Studio).
+export { createGeminiEmbeddingProvider, GEMINI_MODELS, } from "./embeddings/gemini.js";
+// Model registry helpers — validation + migration planning.
+export { isActiveEmbeddingModel, planEmbeddingMigration, stampEmbeddingModelId, validateEmbeddingCompatibility, } from "./embeddings/model-registry.js";
+// OpenAI provider.
+export { createOpenAIEmbeddingProvider, embedBatched, OPENAI_MODELS, } from "./embeddings/openai.js";
+export { federateAudienceSearch, mergeAndDedupe, } from "./search/federate.js";
+// Search orchestration — semantic / hybrid / BYO-vector + federated.
+export { executeBYOVectorSearch, executeSemanticSearch, } from "./search/semantic.js";

package/dist/search/federate.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Cross-audience federated search.
+ *
+ * Per architecture §7, vectors are strictly per-audience — customer
+ * embedding pools only contain customer-visible text, partner pools only
+ * contain partner-visible text, etc. This means the most common admin AI
+ * use case ("find products similar to *X*" where *X* is in customer-
+ * facing language) needs to query a non-staff audience pool.
+ *
+ * Staff actors are authorized to query any audience pool; customer /
+ * partner / supplier agents are pinned to their own audience by API
+ * authorization. This helper takes a list of `search_audiences` and:
+ *
+ *   1. Verifies the actor is authorized for each requested audience.
+ *   2. Issues parallel `IndexerAdapter.search` calls — one per audience.
+ *   3. Deduplicates hits by entity id (same entity may rank in multiple
+ *      pools; keep the highest-scoring instance).
+ *   4. Merges the per-pool result sets into a single ranked list.
+ *
+ * If the adapter declares `supportsCrossAudienceFederation`, the helper
+ * delegates to a single multi-collection adapter call instead of fanning
+ * out client-side. Either way the API contract is the same to callers.
+ *
+ * See `docs/architecture/catalog-rag-architecture.md` §7.3.
+ */
+import type { IndexerAdapter, SearchRequest, SearchResults, Visibility } from "@voyantjs/catalog";
+export interface FederatedSearchOptions {
+    adapter: IndexerAdapter;
+    /**
+     * The actor making the request. The federation helper enforces:
+     *   - `customer` / `partner` / `supplier` actors → may search only
+     *     their own audience pool (no federation).
+     *   - `staff` actors → may search any combination of audience pools.
+     */
+    actor: Visibility;
+    /** The audience pools to federate across. Must be a subset of allowed pools per actor. */
+    searchAudiences: Visibility[];
+    /** The vertical (entity_module) to search. */
+    vertical: string;
+    /** Locale + market for every slice. */
+    locale: string;
+    market: string;
+    /** The base search request — same shape passed to a single-slice search. */
+    request: SearchRequest;
+}
+/**
+ * Federate a search across multiple audience pools. Returns a unified
+ * `SearchResults` with deduplicated hits ranked by score.
+ */
+export declare function federateAudienceSearch(options: FederatedSearchOptions): Promise<SearchResults>;
+/**
+ * Merge several `SearchResults` into one, deduplicating by hit id and
+ * keeping the highest-scoring instance. Total is the count of unique ids
+ * across all pools (after dedupe).
+ */
+export declare function mergeAndDedupe(perSlice: ReadonlyArray<SearchResults>, limit?: number): SearchResults;
+//# sourceMappingURL=federate.d.ts.map

package/dist/search/federate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"federate.d.ts","sourceRoot":"","sources":["../../src/search/federate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EACV,cAAc,EAGd,aAAa,EACb,aAAa,EACb,UAAU,EACX,MAAM,mBAAmB,CAAA;AAE1B,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,cAAc,CAAA;IACvB;;;;;OAKG;IACH,KAAK,EAAE,UAAU,CAAA;IACjB,0FAA0F;IAC1F,eAAe,EAAE,UAAU,EAAE,CAAA;IAC7B,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAA;IAChB,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,4EAA4E;IAC5E,OAAO,EAAE,aAAa,CAAA;CACvB;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,aAAa,CAAC,CAqCxB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,EACtC,KAAK,CAAC,EAAE,MAAM,GACb,aAAa,CAsBf"}