@fgv/ts-extras 5.1.0-33 → 5.1.0-35

package/dist/packlets/ai-assist/embeddingClient.js

@@ -0,0 +1,346 @@
+// Copyright (c) 2026 Erik Fortune
+//
+// 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.
+/**
+ * Cross-provider embedding client for AI assist. Mirrors the completion and
+ * image-generation primitives in `apiClient.ts`: a single dispatcher
+ * ({@link AiAssist.callProviderEmbedding}) resolves the provider descriptor's
+ * embedding capability and routes to the per-format adapter. `text -> vector`,
+ * batch in, `number[][]` out.
+ *
+ * @packageDocumentation
+ */
+import { fail, succeed, Validators } from '@fgv/ts-utils';
+import { resolveModel } from './model';
+import { bearerAuthHeader, resolveEffectiveBaseUrl } from './endpoint';
+import { resolveEmbeddingCapability, supportsEmbedding } from './registry';
+import { fetchJson } from './http';
+const openAiEmbeddingItem = Validators.object({
+    index: Validators.number,
+    embedding: Validators.arrayOf(Validators.number)
+});
+const openAiEmbeddingUsage = Validators.object({
+    prompt_tokens: Validators.number.optional(),
+    total_tokens: Validators.number.optional()
+});
+const openAiEmbeddingResponse = Validators.object({
+    data: Validators.arrayOf(openAiEmbeddingItem).withConstraint((arr) => arr.length > 0),
+    model: Validators.string.optional(),
+    usage: openAiEmbeddingUsage.optional()
+});
+// ============================================================================
+// Shared helpers
+// ============================================================================
+/**
+ * Normalizes the `input` field (string | string[]) into a concrete string array.
+ * @internal
+ */
+function toInputArray(input) {
+    return typeof input === 'string' ? [input] : input;
+}
+/**
+ * Builds an {@link IAiEmbeddingUsage} from OpenAI-format usage, or `undefined`
+ * when no token counts are reported.
+ * @internal
+ */
+function toEmbeddingUsage(usage) {
+    if (usage === undefined || (usage.prompt_tokens === undefined && usage.total_tokens === undefined)) {
+        return undefined;
+    }
+    return Object.assign(Object.assign({}, (usage.prompt_tokens !== undefined ? { promptTokens: usage.prompt_tokens } : {})), (usage.total_tokens !== undefined ? { totalTokens: usage.total_tokens } : {}));
+}
+// ============================================================================
+// OpenAI-format adapter
+// ============================================================================
+/**
+ * Calls the OpenAI `/v1/embeddings` endpoint. Serves OpenAI, Ollama (via `/v1`),
+ * openai-compat self-hosted servers, and Mistral. Sends `dimensions` only when
+ * the capability declares `supportsDimensions`; always requests
+ * `encoding_format: 'float'`.
+ *
+ * @remarks
+ * `encoding_format: 'float'` is a known assumption (design §14 #5): a strict
+ * openai-compat server could in principle reject the field, but mainstream
+ * servers accept it and it keeps us off the base64 decode path. Low risk.
+ *
+ * @internal
+ */
+async function callOpenAiEmbeddings(config, inputs, request, capability, logger, signal) {
+    const body = {
+        model: config.model,
+        input: inputs,
+        encoding_format: 'float'
+    };
+    if (capability.supportsDimensions && request.dimensions !== undefined) {
+        body.dimensions = request.dimensions;
+    }
+    const headers = bearerAuthHeader(config.apiKey);
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`AI embedding: format=openai-embeddings, model=${config.model}, inputs=${inputs.length}`);
+    const jsonResult = await fetchJson(`${config.baseUrl}/embeddings`, headers, body, logger, signal);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    return openAiEmbeddingResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `OpenAI embeddings API response: ${msg}`)
+        .onSuccess((response) => {
+        var _a;
+        // The spec allows `data` in any order; align to request order by `index`.
+        const ordered = [...response.data].sort((a, b) => a.index - b.index);
+        // Validate the response is well-formed against the request before trusting
+        // the alignment: a compat server could return an incomplete batch, gapped
+        // or duplicate indices, or ragged dimensions — all of which would silently
+        // yield misaligned/partial vectors. (inputs is non-empty here; the
+        // empty-input case short-circuits before the wire call.)
+        if (ordered.length !== inputs.length) {
+            return fail(`OpenAI embeddings API response: expected ${inputs.length} embedding(s), got ${ordered.length}`);
+        }
+        // After sorting, a perfect 0..n-1 sequence has item.index === position at
+        // every slot. Any gap OR duplicate shifts a later element off its position
+        // (the second copy of value k, or the element after a missing k, lands at
+        // position > its index), so this single walk catches both.
+        const misindexed = ordered.findIndex((item, i) => item.index !== i);
+        if (misindexed !== -1) {
+            return fail(`OpenAI embeddings API response: malformed embedding indices ` +
+                `(expected 0..${inputs.length - 1}; gap or duplicate at position ${misindexed})`);
+        }
+        const vectors = ordered.map((item) => item.embedding);
+        const dimensions = vectors[0].length;
+        const ragged = vectors.findIndex((v) => v.length !== dimensions);
+        if (ragged !== -1) {
+            return fail(`OpenAI embeddings API response: inconsistent vector dimensionality ` +
+                `(vector ${ragged} has length ${vectors[ragged].length}, expected ${dimensions})`);
+        }
+        const usage = toEmbeddingUsage(response.usage);
+        return succeed(Object.assign({ vectors, model: (_a = response.model) !== null && _a !== void 0 ? _a : config.model, dimensions }, (usage !== undefined ? { usage } : {})));
+    });
+}
+const geminiEmbedding = Validators.object({
+    values: Validators.arrayOf(Validators.number)
+});
+const geminiEmbeddingResponse = Validators.object({
+    embeddings: Validators.arrayOf(geminiEmbedding).withConstraint((arr) => arr.length > 0)
+});
+/**
+ * Maps a cross-provider {@link AiAssist.AiEmbeddingTaskType} (kebab-case) to the
+ * Gemini wire form (`SCREAMING_SNAKE_CASE`), e.g. `'retrieval-document'` becomes
+ * `'RETRIEVAL_DOCUMENT'`.
+ * @internal
+ */
+function toGeminiTaskType(taskType) {
+    return taskType.replace(/-/g, '_').toUpperCase();
+}
+/**
+ * Strips a leading `models/` from a model id so the URL path and the per-request
+ * `model` field can each apply the prefix exactly once.
+ * @internal
+ */
+function bareGeminiModel(model) {
+    return model.startsWith('models/') ? model.slice('models/'.length) : model;
+}
+/**
+ * Calls the Google Gemini `:batchEmbedContents` endpoint. Always uses the batch
+ * route (a single input is a one-element batch). Sends `taskType` /
+ * `outputDimensionality` only when the capability declares support. Gemini does
+ * not report token usage for embeddings, so `usage` is omitted.
+ * @internal
+ */
+async function callGeminiEmbeddings(config, inputs, request, capability, logger, signal) {
+    const bare = bareGeminiModel(config.model);
+    const qualified = `models/${bare}`;
+    // `request.taskType` is the open `AiEmbeddingTaskType` union (includes `string & {}`),
+    // which `!== undefined` cannot narrow to `string`; resolve it cast-free here.
+    const taskType = capability.supportsTaskType && request.taskType !== undefined
+        ? toGeminiTaskType(request.taskType)
+        : undefined;
+    const sendDimensions = capability.supportsDimensions && request.dimensions !== undefined;
+    const requests = inputs.map((text) => (Object.assign(Object.assign({ model: qualified, content: { parts: [{ text }] } }, (taskType !== undefined ? { taskType } : {})), (sendDimensions ? { outputDimensionality: request.dimensions } : {}))));
+    const body = { requests };
+    const headers = { 'x-goog-api-key': config.apiKey };
+    const url = `${config.baseUrl}/models/${bare}:batchEmbedContents`;
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`AI embedding: format=gemini-embeddings, model=${bare}, inputs=${inputs.length}`);
+    const jsonResult = await fetchJson(url, headers, body, logger, signal);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    return geminiEmbeddingResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `Gemini embeddings API response: ${msg}`)
+        .onSuccess((response) => {
+        // Gemini returns embeddings aligned to request order (no index field), so
+        // there is no per-item index to re-sort or gap-check (unlike the OpenAI
+        // path). Validate the response is well-formed against the request before
+        // trusting the positional alignment: a truncated batch or ragged
+        // dimensions would silently yield misaligned/partial vectors. (inputs is
+        // non-empty here; the empty-input case short-circuits before the wire call.)
+        const vectors = response.embeddings.map((e) => e.values);
+        if (vectors.length !== inputs.length) {
+            return fail(`Gemini embeddings API response: expected ${inputs.length} embedding(s), got ${vectors.length}`);
+        }
+        const dimensions = vectors[0].length;
+        const ragged = vectors.findIndex((v) => v.length !== dimensions);
+        if (ragged !== -1) {
+            return fail(`Gemini embeddings API response: inconsistent vector dimensionality ` +
+                `(vector ${ragged} has length ${vectors[ragged].length}, expected ${dimensions})`);
+        }
+        const result = { vectors, model: bare, dimensions };
+        return succeed(result);
+    });
+}
+// ============================================================================
+// Dispatcher
+// ============================================================================
+/**
+ * Notes any caller-supplied embedding knobs that the resolved capability does
+ * not honor. Per design §7 these are a no-op (logged, never a failure) so a
+ * cross-provider call site can pass `taskType`/`dimensions` once and have them
+ * apply only where supported.
+ * @internal
+ */
+function noteUnsupportedKnobs(model, request, capability, logger) {
+    if (logger === undefined) {
+        return;
+    }
+    if (request.taskType !== undefined && !capability.supportsTaskType) {
+        logger.info(`AI embedding: model "${model}" ignores taskType (not supported); proceeding without it`);
+    }
+    if (request.dimensions !== undefined && !capability.supportsDimensions) {
+        logger.info(`AI embedding: model "${model}" ignores dimensions (not supported); proceeding without it`);
+    }
+}
+/**
+ * Calls the appropriate embedding API for a given provider. Routes by the
+ * `format` of the resolved {@link AiAssist.IAiEmbeddingModelCapability}:
+ * `'openai-embeddings'` or `'gemini-embeddings'`.
+ *
+ * @remarks
+ * - Rejects up front when the provider declares no embedding capability, when no
+ *   embedding model resolves, or when the batch exceeds the capability's
+ *   `maxBatchSize` (no auto-chunking).
+ * - An empty `input` array short-circuits to an empty result with no wire call
+ *   (most providers HTTP-400 on empty input).
+ * - Caller-supplied `dimensions`/`taskType` that the model doesn't support are a
+ *   no-op (logged), not a failure (design §7).
+ *
+ * @param params - Request parameters including descriptor, API key, and input.
+ * @returns The embedding vectors aligned to input order, or a failure.
+ * @public
+ */
+export async function callProviderEmbedding(params) {
+    const { descriptor, apiKey, params: request, modelOverride, logger, signal, endpoint } = params;
+    if (!supportsEmbedding(descriptor)) {
+        return fail(`provider "${descriptor.id}" does not support embeddings`);
+    }
+    const model = resolveModel(modelOverride !== null && modelOverride !== void 0 ? modelOverride : descriptor.defaultModel, 'embedding');
+    if (model.length === 0) {
+        return fail(`provider "${descriptor.id}": no embedding model resolved; ` +
+            `pass modelOverride or set descriptor.defaultModel ` +
+            `(a plain string, or an object with an "embedding" entry)`);
+    }
+    const capability = resolveEmbeddingCapability(descriptor, model);
+    if (capability === undefined) {
+        return fail(`provider "${descriptor.id}" does not support embeddings for model "${model}"`);
+    }
+    const inputs = toInputArray(request.input);
+    if (inputs.length === 0) {
+        // Short-circuit: empty batch never hits the wire (design §14 #2).
+        return succeed({ vectors: [], model, dimensions: 0 });
+    }
+    if (capability.maxBatchSize !== undefined && inputs.length > capability.maxBatchSize) {
+        return fail(`provider "${descriptor.id}": embedding batch of ${inputs.length} exceeds ` +
+            `model "${model}" maximum of ${capability.maxBatchSize}`);
+    }
+    const baseUrlResult = resolveEffectiveBaseUrl(descriptor, endpoint);
+    if (baseUrlResult.isFailure()) {
+        return fail(baseUrlResult.message);
+    }
+    noteUnsupportedKnobs(model, request, capability, logger);
+    const config = { baseUrl: baseUrlResult.value, apiKey, model };
+    return dispatchEmbedding(capability.format, config, inputs, request, capability, logger, signal);
+}
+/**
+ * Routes a resolved embedding request to the per-format adapter.
+ * @internal
+ */
+function dispatchEmbedding(format, config, inputs, request, capability, logger, signal) {
+    switch (format) {
+        case 'openai-embeddings':
+            return callOpenAiEmbeddings(config, inputs, request, capability, logger, signal);
+        case 'gemini-embeddings':
+            return callGeminiEmbeddings(config, inputs, request, capability, logger, signal);
+        /* c8 ignore next 4 - defensive: exhaustive switch guaranteed by TypeScript */
+        default: {
+            const _exhaustive = format;
+            return Promise.resolve(fail(`unsupported embedding API format: ${String(_exhaustive)}`));
+        }
+    }
+}
+// ============================================================================
+// Proxied embedding
+// ============================================================================
+const proxiedEmbeddingUsage = Validators.object({
+    promptTokens: Validators.number.optional(),
+    totalTokens: Validators.number.optional()
+});
+const proxiedEmbeddingResponse = Validators.object({
+    vectors: Validators.arrayOf(Validators.arrayOf(Validators.number)),
+    model: Validators.string,
+    dimensions: Validators.number,
+    usage: proxiedEmbeddingUsage.optional()
+});
+/**
+ * Calls the embedding endpoint on a proxy server instead of calling the provider
+ * API directly from the browser. Endpoint: `POST ${proxyUrl}/api/ai/embedding`.
+ * Request body: `{ providerId, apiKey, params, modelOverride? }`. The proxy
+ * handles descriptor lookup, model/capability resolution, and provider dispatch.
+ * Error body `{ error: string }` is surfaced as `proxy: ${error}`.
+ *
+ * @param proxyUrl - Base URL of the proxy server (e.g. `http://localhost:3001`).
+ * @param params - Same parameters as {@link AiAssist.callProviderEmbedding}.
+ * @returns The embedding result, or a failure.
+ * @public
+ */
+export async function callProxiedEmbedding(proxyUrl, params) {
+    const { descriptor, apiKey, params: request, modelOverride, logger, signal } = params;
+    const body = {
+        providerId: descriptor.id,
+        apiKey,
+        params: request
+    };
+    if (modelOverride !== undefined) {
+        body.modelOverride = modelOverride;
+    }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`AI embedding proxy request: provider=${descriptor.id}, proxy=${proxyUrl}`);
+    const url = `${proxyUrl}/api/ai/embedding`;
+    const jsonResult = await fetchJson(url, {}, body, logger, signal);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    const response = jsonResult.value;
+    if (typeof response.error === 'string') {
+        return fail(`proxy: ${response.error}`);
+    }
+    return proxiedEmbeddingResponse
+        .validate(response)
+        .withErrorFormat((msg) => `proxy returned invalid response: ${msg}`);
+}
+//# sourceMappingURL=embeddingClient.js.map

package/dist/packlets/ai-assist/embeddingClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddingClient.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/embeddingClient.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY;AAEZ;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAwB,OAAO,EAAkB,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhG,OAAO,EAQL,YAAY,EACb,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,0BAA0B,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAqB,SAAS,EAAE,MAAM,QAAQ,CAAC;AAqDtD,MAAM,mBAAmB,GAAoC,UAAU,CAAC,MAAM,CAAuB;IACnG,KAAK,EAAE,UAAU,CAAC,MAAM;IACxB,SAAS,EAAE,UAAU,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC;CACjD,CAAC,CAAC;AACH,MAAM,oBAAoB,GAAqC,UAAU,CAAC,MAAM,CAAwB;IACtG,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,QAAQ,EAAE;IAC3C,YAAY,EAAE,UAAU,CAAC,MAAM,CAAC,QAAQ,EAAE;CAC3C,CAAC,CAAC;AACH,MAAM,uBAAuB,GAC3B,UAAU,CAAC,MAAM,CAA2B;IAC1C,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC,cAAc,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IACrF,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,QAAQ,EAAE;IACnC,KAAK,EAAE,oBAAoB,CAAC,QAAQ,EAAE;CACvC,CAAC,CAAC;AAEL,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E;;;GAGG;AACH,SAAS,YAAY,CAAC,KAAqC;IACzD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AACrD,CAAC;AAED;;;;GAIG;AACH,SAAS,gBAAgB,CAAC,KAAwC;IAChE,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,aAAa,KAAK,SAAS,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS,CAAC,EAAE,CAAC;QACnG,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,uCACK,CAAC,KAAK,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,KAAK,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,GAChF,CAAC,KAAK,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAChF;AACJ,CAAC;AAED,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E;;;;;;;;;;;;GAYG;AACH,KAAK,UAAU,oBAAoB,CACjC,MAAoB,EACpB,MAA6B,EAC7B,OAA2B,EAC3B,UAAuC,EACvC,MAAwB,EACxB,MAAoB;IAEpB,MAAM,IAAI,GAA4B;QACpC,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,KAAK,EAAE,MAAM;QACb,eAAe,EAAE,OAAO;KACzB,CAAC;IACF,IAAI,UAAU,CAAC,kBAAkB,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACtE,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IACvC,CAAC;IACD,MAAM,OAAO,GAA2B,gBAAgB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAExE,wCAAwC;IACxC,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,IAAI,CAAC,iDAAiD,MAAM,CAAC,KAAK,YAAY,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAEvG,MAAM,UAAU,GAAG,MAAM,SAAS,CAAC,GAAG,MAAM,CAAC,OAAO,aAAa,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAClG,IAAI,UAAU,CAAC,SAAS,EAAE,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,uBAAuB;SAC3B,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC;SAC1B,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,mCAAmC,GAAG,EAAE,CAAC;SAClE,SAAS,CAAC,CAAC,QAAQ,EAAE,EAAE;;QACtB,0EAA0E;QAC1E,MAAM,OAAO,GAAG,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QACrE,2EAA2E;QAC3E,0EAA0E;QAC1E,2EAA2E;QAC3E,mEAAmE;QACnE,yDAAyD;QACzD,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC;YACrC,OAAO,IAAI,CACT,4CAA4C,MAAM,CAAC,MAAM,sBAAsB,OAAO,CAAC,MAAM,EAAE,CAChG,CAAC;QACJ,CAAC;QACD,0EAA0E;QAC1E,2EAA2E;QAC3E,0EAA0E;QAC1E,2DAA2D;QAC3D,MAAM,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC;QACpE,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;YACtB,OAAO,IAAI,CACT,8DAA8D;gBAC5D,gBAAgB,MAAM,CAAC,MAAM,GAAG,CAAC,kCAAkC,UAAU,GAAG,CACnF,CAAC;QACJ,CAAC;QACD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACtD,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QACrC,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC;QACjE,IAAI,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;YAClB,OAAO,IAAI,CACT,qEAAqE;gBACnE,WAAW,MAAM,eAAe,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,cAAc,UAAU,GAAG,CACpF,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,GAAG,gBAAgB,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC/C,OAAO,OAAO,iBACZ,OAAO,EACP,KAAK,EAAE,MAAA,QAAQ,CAAC,KAAK,mCAAI,MAAM,CAAC,KAAK,EACrC,UAAU,IACP,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EACzC,CAAC;IACL,CAAC,CAAC,CAAC;AACP,CAAC;AAeD,MAAM,eAAe,GAAgC,UAAU,CAAC,MAAM,CAAmB;IACvF,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC;CAC9C,CAAC,CAAC;AACH,MAAM,uBAAuB,GAC3B,UAAU,CAAC,MAAM,CAA2B;IAC1C,UAAU,EAAE,UAAU,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,cAAc,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;CACxF,CAAC,CAAC;AAEL;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,QAAgB;IACxC,OAAO,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AAC7E,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,oBAAoB,CACjC,MAAoB,EACpB,MAA6B,EAC7B,OAA2B,EAC3B,UAAuC,EACvC,MAAwB,EACxB,MAAoB;IAEpB,MAAM,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3C,MAAM,SAAS,GAAG,UAAU,IAAI,EAAE,CAAC;IACnC,uFAAuF;IACvF,8EAA8E;IAC9E,MAAM,QAAQ,GACZ,UAAU,CAAC,gBAAgB,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;QAC3D,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,QAAQ,CAAC;QACpC,CAAC,CAAC,SAAS,CAAC;IAChB,MAAM,cAAc,GAAG,UAAU,CAAC,kBAAkB,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC;IAEzF,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,+BACpC,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAC3B,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,GAC5C,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EACvE,CAAC,CAAC;IACJ,MAAM,IAAI,GAA4B,EAAE,QAAQ,EAAE,CAAC;IACnD,MAAM,OAAO,GAA2B,EAAE,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;IAC5E,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,OAAO,WAAW,IAAI,qBAAqB,CAAC;IAElE,wCAAwC;IACxC,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,IAAI,CAAC,iDAAiD,IAAI,YAAY,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAE/F,MAAM,UAAU,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvE,IAAI,UAAU,CAAC,SAAS,EAAE,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,uBAAuB;SAC3B,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC;SAC1B,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,mCAAmC,GAAG,EAAE,CAAC;SAClE,SAAS,CAAC,CAAC,QAAQ,EAAE,EAAE;QACtB,0EAA0E;QAC1E,wEAAwE;QACxE,yEAAyE;QACzE,iEAAiE;QACjE,yEAAyE;QACzE,6EAA6E;QAC7E,MAAM,OAAO,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACzD,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC;YACrC,OAAO,IAAI,CACT,4CAA4C,MAAM,CAAC,MAAM,sBAAsB,OAAO,CAAC,MAAM,EAAE,CAChG,CAAC;QACJ,CAAC;QACD,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QACrC,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC;QACjE,IAAI,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;YAClB,OAAO,IAAI,CACT,qEAAqE;gBACnE,WAAW,MAAM,eAAe,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,cAAc,UAAU,GAAG,CACpF,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,GAAuB,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;QACxE,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;AACP,CAAC;AAED,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E;;;;;;GAMG;AACH,SAAS,oBAAoB,CAC3B,KAAa,EACb,OAA2B,EAC3B,UAAuC,EACvC,MAAwB;IAExB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO;IACT,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC;QACnE,MAAM,CAAC,IAAI,CAAC,wBAAwB,KAAK,2DAA2D,CAAC,CAAC;IACxG,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,IAAI,CAAC,UAAU,CAAC,kBAAkB,EAAE,CAAC;QACvE,MAAM,CAAC,IAAI,CAAC,wBAAwB,KAAK,6DAA6D,CAAC,CAAC;IAC1G,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAgC;IAEhC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;IAEhG,IAAI,CAAC,iBAAiB,CAAC,UAAU,CAAC,EAAE,CAAC;QACnC,OAAO,IAAI,CAAC,aAAa,UAAU,CAAC,EAAE,+BAA+B,CAAC,CAAC;IACzE,CAAC;IAED,MAAM,KAAK,GAAG,YAAY,CAAC,aAAa,aAAb,aAAa,cAAb,aAAa,GAAI,UAAU,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;IAClF,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,IAAI,CACT,aAAa,UAAU,CAAC,EAAE,kCAAkC;YAC1D,oDAAoD;YACpD,0DAA0D,CAC7D,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,0BAA0B,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACjE,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC,aAAa,UAAU,CAAC,EAAE,4CAA4C,KAAK,GAAG,CAAC,CAAC;IAC9F,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,kEAAkE;QAClE,OAAO,OAAO,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,CAAC;IACxD,CAAC;IACD,IAAI,UAAU,CAAC,YAAY,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,GAAG,UAAU,CAAC,YAAY,EAAE,CAAC;QACrF,OAAO,IAAI,CACT,aAAa,UAAU,CAAC,EAAE,yBAAyB,MAAM,CAAC,MAAM,WAAW;YACzE,UAAU,KAAK,gBAAgB,UAAU,CAAC,YAAY,EAAE,CAC3D,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,uBAAuB,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IACpE,IAAI,aAAa,CAAC,SAAS,EAAE,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IAED,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IAEzD,MAAM,MAAM,GAAiB,EAAE,OAAO,EAAE,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAE7E,OAAO,iBAAiB,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AACnG,CAAC;AAED;;;GAGG;AACH,SAAS,iBAAiB,CACxB,MAA4B,EAC5B,MAAoB,EACpB,MAA6B,EAC7B,OAA2B,EAC3B,UAAuC,EACvC,MAAwB,EACxB,MAAoB;IAEpB,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,mBAAmB;YACtB,OAAO,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACnF,KAAK,mBAAmB;YACtB,OAAO,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACnF,8EAA8E;QAC9E,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,WAAW,GAAU,MAAM,CAAC;YAClC,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,qCAAqC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC;QAC3F,CAAC;IACH,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,oBAAoB;AACpB,+EAA+E;AAE/E,MAAM,qBAAqB,GAAiC,UAAU,CAAC,MAAM,CAAoB;IAC/F,YAAY,EAAE,UAAU,CAAC,MAAM,CAAC,QAAQ,EAAE;IAC1C,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC,QAAQ,EAAE;CAC1C,CAAC,CAAC;AACH,MAAM,wBAAwB,GAAkC,UAAU,CAAC,MAAM,CAAqB;IACpG,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IAClE,KAAK,EAAE,UAAU,CAAC,MAAM;IACxB,UAAU,EAAE,UAAU,CAAC,MAAM;IAC7B,KAAK,EAAE,qBAAqB,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,QAAgB,EAChB,MAAgC;IAEhC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAEtF,MAAM,IAAI,GAA4B;QACpC,UAAU,EAAE,UAAU,CAAC,EAAE;QACzB,MAAM;QACN,MAAM,EAAE,OAAO;KAChB,CAAC;IACF,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;IAED,wCAAwC;IACxC,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,IAAI,CAAC,wCAAwC,UAAU,CAAC,EAAE,WAAW,QAAQ,EAAE,CAAC,CAAC;IAEzF,MAAM,GAAG,GAAG,GAAG,QAAQ,mBAAmB,CAAC;IAC3C,MAAM,UAAU,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAClE,IAAI,UAAU,CAAC,SAAS,EAAE,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAED,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC;IAClC,IAAI,OAAO,QAAQ,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,OAAO,IAAI,CAAC,UAAU,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO,wBAAwB;SAC5B,QAAQ,CAAC,QAAQ,CAAC;SAClB,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,oCAAoC,GAAG,EAAE,CAAC,CAAC;AACzE,CAAC","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\n/**\n * Cross-provider embedding client for AI assist. Mirrors the completion and\n * image-generation primitives in `apiClient.ts`: a single dispatcher\n * ({@link AiAssist.callProviderEmbedding}) resolves the provider descriptor's\n * embedding capability and routes to the per-format adapter. `text -> vector`,\n * batch in, `number[][]` out.\n *\n * @packageDocumentation\n */\n\nimport { fail, type Logging, Result, succeed, type Validator, Validators } from '@fgv/ts-utils';\n\nimport {\n  type AiEmbeddingApiFormat,\n  type IAiEmbeddingModelCapability,\n  type IAiEmbeddingParams,\n  type IAiEmbeddingResult,\n  type IAiEmbeddingUsage,\n  type IAiProviderDescriptor,\n  type ModelSpec,\n  resolveModel\n} from './model';\nimport { bearerAuthHeader, resolveEffectiveBaseUrl } from './endpoint';\nimport { resolveEmbeddingCapability, supportsEmbedding } from './registry';\nimport { type IAiApiConfig, fetchJson } from './http';\n\n// ============================================================================\n// Request types\n// ============================================================================\n\n/**\n * Parameters for a provider embedding request. Mirrors\n * {@link AiAssist.IProviderImageGenerationParams}.\n * @public\n */\nexport interface IProviderEmbeddingParams {\n  /** The provider descriptor. */\n  readonly descriptor: IAiProviderDescriptor;\n  /** API key for authentication (empty string for keyless self-hosted providers). */\n  readonly apiKey: string;\n  /** The embedding request (input + optional knobs). */\n  readonly params: IAiEmbeddingParams;\n  /**\n   * Optional model override — string or context-aware map. Uses\n   * `descriptor.defaultModel.embedding` otherwise. Self-hosted providers\n   * (`ollama`, `openai-compat`) have no default and require this.\n   */\n  readonly modelOverride?: ModelSpec;\n  /** Optional logger for request/response observability. */\n  readonly logger?: Logging.ILogger;\n  /** Optional abort signal for cancelling the in-flight request. */\n  readonly signal?: AbortSignal;\n  /** Optional override of the descriptor's base URL; the `/embeddings` suffix is appended unchanged. */\n  readonly endpoint?: string;\n}\n\n// ============================================================================\n// OpenAI-format (`/v1/embeddings`) response validators\n// ============================================================================\n\n/** @internal */\ninterface IOpenAiEmbeddingItem {\n  index: number;\n  embedding: number[];\n}\n/** @internal */\ninterface IOpenAiEmbeddingUsage {\n  prompt_tokens?: number;\n  total_tokens?: number;\n}\n/** @internal */\ninterface IOpenAiEmbeddingResponse {\n  data: IOpenAiEmbeddingItem[];\n  model?: string;\n  usage?: IOpenAiEmbeddingUsage;\n}\n\nconst openAiEmbeddingItem: Validator<IOpenAiEmbeddingItem> = Validators.object<IOpenAiEmbeddingItem>({\n  index: Validators.number,\n  embedding: Validators.arrayOf(Validators.number)\n});\nconst openAiEmbeddingUsage: Validator<IOpenAiEmbeddingUsage> = Validators.object<IOpenAiEmbeddingUsage>({\n  prompt_tokens: Validators.number.optional(),\n  total_tokens: Validators.number.optional()\n});\nconst openAiEmbeddingResponse: Validator<IOpenAiEmbeddingResponse> =\n  Validators.object<IOpenAiEmbeddingResponse>({\n    data: Validators.arrayOf(openAiEmbeddingItem).withConstraint((arr) => arr.length > 0),\n    model: Validators.string.optional(),\n    usage: openAiEmbeddingUsage.optional()\n  });\n\n// ============================================================================\n// Shared helpers\n// ============================================================================\n\n/**\n * Normalizes the `input` field (string | string[]) into a concrete string array.\n * @internal\n */\nfunction toInputArray(input: string | ReadonlyArray<string>): ReadonlyArray<string> {\n  return typeof input === 'string' ? [input] : input;\n}\n\n/**\n * Builds an {@link IAiEmbeddingUsage} from OpenAI-format usage, or `undefined`\n * when no token counts are reported.\n * @internal\n */\nfunction toEmbeddingUsage(usage: IOpenAiEmbeddingUsage | undefined): IAiEmbeddingUsage | undefined {\n  if (usage === undefined || (usage.prompt_tokens === undefined && usage.total_tokens === undefined)) {\n    return undefined;\n  }\n  return {\n    ...(usage.prompt_tokens !== undefined ? { promptTokens: usage.prompt_tokens } : {}),\n    ...(usage.total_tokens !== undefined ? { totalTokens: usage.total_tokens } : {})\n  };\n}\n\n// ============================================================================\n// OpenAI-format adapter\n// ============================================================================\n\n/**\n * Calls the OpenAI `/v1/embeddings` endpoint. Serves OpenAI, Ollama (via `/v1`),\n * openai-compat self-hosted servers, and Mistral. Sends `dimensions` only when\n * the capability declares `supportsDimensions`; always requests\n * `encoding_format: 'float'`.\n *\n * @remarks\n * `encoding_format: 'float'` is a known assumption (design §14 #5): a strict\n * openai-compat server could in principle reject the field, but mainstream\n * servers accept it and it keeps us off the base64 decode path. Low risk.\n *\n * @internal\n */\nasync function callOpenAiEmbeddings(\n  config: IAiApiConfig,\n  inputs: ReadonlyArray<string>,\n  request: IAiEmbeddingParams,\n  capability: IAiEmbeddingModelCapability,\n  logger?: Logging.ILogger,\n  signal?: AbortSignal\n): Promise<Result<IAiEmbeddingResult>> {\n  const body: Record<string, unknown> = {\n    model: config.model,\n    input: inputs,\n    encoding_format: 'float'\n  };\n  if (capability.supportsDimensions && request.dimensions !== undefined) {\n    body.dimensions = request.dimensions;\n  }\n  const headers: Record<string, string> = bearerAuthHeader(config.apiKey);\n\n  /* c8 ignore next 1 - optional logger */\n  logger?.info(`AI embedding: format=openai-embeddings, model=${config.model}, inputs=${inputs.length}`);\n\n  const jsonResult = await fetchJson(`${config.baseUrl}/embeddings`, headers, body, logger, signal);\n  if (jsonResult.isFailure()) {\n    return fail(jsonResult.message);\n  }\n  return openAiEmbeddingResponse\n    .validate(jsonResult.value)\n    .withErrorFormat((msg) => `OpenAI embeddings API response: ${msg}`)\n    .onSuccess((response) => {\n      // The spec allows `data` in any order; align to request order by `index`.\n      const ordered = [...response.data].sort((a, b) => a.index - b.index);\n      // Validate the response is well-formed against the request before trusting\n      // the alignment: a compat server could return an incomplete batch, gapped\n      // or duplicate indices, or ragged dimensions — all of which would silently\n      // yield misaligned/partial vectors. (inputs is non-empty here; the\n      // empty-input case short-circuits before the wire call.)\n      if (ordered.length !== inputs.length) {\n        return fail(\n          `OpenAI embeddings API response: expected ${inputs.length} embedding(s), got ${ordered.length}`\n        );\n      }\n      // After sorting, a perfect 0..n-1 sequence has item.index === position at\n      // every slot. Any gap OR duplicate shifts a later element off its position\n      // (the second copy of value k, or the element after a missing k, lands at\n      // position > its index), so this single walk catches both.\n      const misindexed = ordered.findIndex((item, i) => item.index !== i);\n      if (misindexed !== -1) {\n        return fail(\n          `OpenAI embeddings API response: malformed embedding indices ` +\n            `(expected 0..${inputs.length - 1}; gap or duplicate at position ${misindexed})`\n        );\n      }\n      const vectors = ordered.map((item) => item.embedding);\n      const dimensions = vectors[0].length;\n      const ragged = vectors.findIndex((v) => v.length !== dimensions);\n      if (ragged !== -1) {\n        return fail(\n          `OpenAI embeddings API response: inconsistent vector dimensionality ` +\n            `(vector ${ragged} has length ${vectors[ragged].length}, expected ${dimensions})`\n        );\n      }\n      const usage = toEmbeddingUsage(response.usage);\n      return succeed({\n        vectors,\n        model: response.model ?? config.model,\n        dimensions,\n        ...(usage !== undefined ? { usage } : {})\n      });\n    });\n}\n\n// ============================================================================\n// Gemini-format (`:batchEmbedContents`) response validators + adapter\n// ============================================================================\n\n/** @internal */\ninterface IGeminiEmbedding {\n  values: number[];\n}\n/** @internal */\ninterface IGeminiEmbeddingResponse {\n  embeddings: IGeminiEmbedding[];\n}\n\nconst geminiEmbedding: Validator<IGeminiEmbedding> = Validators.object<IGeminiEmbedding>({\n  values: Validators.arrayOf(Validators.number)\n});\nconst geminiEmbeddingResponse: Validator<IGeminiEmbeddingResponse> =\n  Validators.object<IGeminiEmbeddingResponse>({\n    embeddings: Validators.arrayOf(geminiEmbedding).withConstraint((arr) => arr.length > 0)\n  });\n\n/**\n * Maps a cross-provider {@link AiAssist.AiEmbeddingTaskType} (kebab-case) to the\n * Gemini wire form (`SCREAMING_SNAKE_CASE`), e.g. `'retrieval-document'` becomes\n * `'RETRIEVAL_DOCUMENT'`.\n * @internal\n */\nfunction toGeminiTaskType(taskType: string): string {\n  return taskType.replace(/-/g, '_').toUpperCase();\n}\n\n/**\n * Strips a leading `models/` from a model id so the URL path and the per-request\n * `model` field can each apply the prefix exactly once.\n * @internal\n */\nfunction bareGeminiModel(model: string): string {\n  return model.startsWith('models/') ? model.slice('models/'.length) : model;\n}\n\n/**\n * Calls the Google Gemini `:batchEmbedContents` endpoint. Always uses the batch\n * route (a single input is a one-element batch). Sends `taskType` /\n * `outputDimensionality` only when the capability declares support. Gemini does\n * not report token usage for embeddings, so `usage` is omitted.\n * @internal\n */\nasync function callGeminiEmbeddings(\n  config: IAiApiConfig,\n  inputs: ReadonlyArray<string>,\n  request: IAiEmbeddingParams,\n  capability: IAiEmbeddingModelCapability,\n  logger?: Logging.ILogger,\n  signal?: AbortSignal\n): Promise<Result<IAiEmbeddingResult>> {\n  const bare = bareGeminiModel(config.model);\n  const qualified = `models/${bare}`;\n  // `request.taskType` is the open `AiEmbeddingTaskType` union (includes `string & {}`),\n  // which `!== undefined` cannot narrow to `string`; resolve it cast-free here.\n  const taskType =\n    capability.supportsTaskType && request.taskType !== undefined\n      ? toGeminiTaskType(request.taskType)\n      : undefined;\n  const sendDimensions = capability.supportsDimensions && request.dimensions !== undefined;\n\n  const requests = inputs.map((text) => ({\n    model: qualified,\n    content: { parts: [{ text }] },\n    ...(taskType !== undefined ? { taskType } : {}),\n    ...(sendDimensions ? { outputDimensionality: request.dimensions } : {})\n  }));\n  const body: Record<string, unknown> = { requests };\n  const headers: Record<string, string> = { 'x-goog-api-key': config.apiKey };\n  const url = `${config.baseUrl}/models/${bare}:batchEmbedContents`;\n\n  /* c8 ignore next 1 - optional logger */\n  logger?.info(`AI embedding: format=gemini-embeddings, model=${bare}, inputs=${inputs.length}`);\n\n  const jsonResult = await fetchJson(url, headers, body, logger, signal);\n  if (jsonResult.isFailure()) {\n    return fail(jsonResult.message);\n  }\n  return geminiEmbeddingResponse\n    .validate(jsonResult.value)\n    .withErrorFormat((msg) => `Gemini embeddings API response: ${msg}`)\n    .onSuccess((response) => {\n      // Gemini returns embeddings aligned to request order (no index field), so\n      // there is no per-item index to re-sort or gap-check (unlike the OpenAI\n      // path). Validate the response is well-formed against the request before\n      // trusting the positional alignment: a truncated batch or ragged\n      // dimensions would silently yield misaligned/partial vectors. (inputs is\n      // non-empty here; the empty-input case short-circuits before the wire call.)\n      const vectors = response.embeddings.map((e) => e.values);\n      if (vectors.length !== inputs.length) {\n        return fail(\n          `Gemini embeddings API response: expected ${inputs.length} embedding(s), got ${vectors.length}`\n        );\n      }\n      const dimensions = vectors[0].length;\n      const ragged = vectors.findIndex((v) => v.length !== dimensions);\n      if (ragged !== -1) {\n        return fail(\n          `Gemini embeddings API response: inconsistent vector dimensionality ` +\n            `(vector ${ragged} has length ${vectors[ragged].length}, expected ${dimensions})`\n        );\n      }\n      const result: IAiEmbeddingResult = { vectors, model: bare, dimensions };\n      return succeed(result);\n    });\n}\n\n// ============================================================================\n// Dispatcher\n// ============================================================================\n\n/**\n * Notes any caller-supplied embedding knobs that the resolved capability does\n * not honor. Per design §7 these are a no-op (logged, never a failure) so a\n * cross-provider call site can pass `taskType`/`dimensions` once and have them\n * apply only where supported.\n * @internal\n */\nfunction noteUnsupportedKnobs(\n  model: string,\n  request: IAiEmbeddingParams,\n  capability: IAiEmbeddingModelCapability,\n  logger?: Logging.ILogger\n): void {\n  if (logger === undefined) {\n    return;\n  }\n  if (request.taskType !== undefined && !capability.supportsTaskType) {\n    logger.info(`AI embedding: model \"${model}\" ignores taskType (not supported); proceeding without it`);\n  }\n  if (request.dimensions !== undefined && !capability.supportsDimensions) {\n    logger.info(`AI embedding: model \"${model}\" ignores dimensions (not supported); proceeding without it`);\n  }\n}\n\n/**\n * Calls the appropriate embedding API for a given provider. Routes by the\n * `format` of the resolved {@link AiAssist.IAiEmbeddingModelCapability}:\n * `'openai-embeddings'` or `'gemini-embeddings'`.\n *\n * @remarks\n * - Rejects up front when the provider declares no embedding capability, when no\n *   embedding model resolves, or when the batch exceeds the capability's\n *   `maxBatchSize` (no auto-chunking).\n * - An empty `input` array short-circuits to an empty result with no wire call\n *   (most providers HTTP-400 on empty input).\n * - Caller-supplied `dimensions`/`taskType` that the model doesn't support are a\n *   no-op (logged), not a failure (design §7).\n *\n * @param params - Request parameters including descriptor, API key, and input.\n * @returns The embedding vectors aligned to input order, or a failure.\n * @public\n */\nexport async function callProviderEmbedding(\n  params: IProviderEmbeddingParams\n): Promise<Result<IAiEmbeddingResult>> {\n  const { descriptor, apiKey, params: request, modelOverride, logger, signal, endpoint } = params;\n\n  if (!supportsEmbedding(descriptor)) {\n    return fail(`provider \"${descriptor.id}\" does not support embeddings`);\n  }\n\n  const model = resolveModel(modelOverride ?? descriptor.defaultModel, 'embedding');\n  if (model.length === 0) {\n    return fail(\n      `provider \"${descriptor.id}\": no embedding model resolved; ` +\n        `pass modelOverride or set descriptor.defaultModel ` +\n        `(a plain string, or an object with an \"embedding\" entry)`\n    );\n  }\n\n  const capability = resolveEmbeddingCapability(descriptor, model);\n  if (capability === undefined) {\n    return fail(`provider \"${descriptor.id}\" does not support embeddings for model \"${model}\"`);\n  }\n\n  const inputs = toInputArray(request.input);\n  if (inputs.length === 0) {\n    // Short-circuit: empty batch never hits the wire (design §14 #2).\n    return succeed({ vectors: [], model, dimensions: 0 });\n  }\n  if (capability.maxBatchSize !== undefined && inputs.length > capability.maxBatchSize) {\n    return fail(\n      `provider \"${descriptor.id}\": embedding batch of ${inputs.length} exceeds ` +\n        `model \"${model}\" maximum of ${capability.maxBatchSize}`\n    );\n  }\n\n  const baseUrlResult = resolveEffectiveBaseUrl(descriptor, endpoint);\n  if (baseUrlResult.isFailure()) {\n    return fail(baseUrlResult.message);\n  }\n\n  noteUnsupportedKnobs(model, request, capability, logger);\n\n  const config: IAiApiConfig = { baseUrl: baseUrlResult.value, apiKey, model };\n\n  return dispatchEmbedding(capability.format, config, inputs, request, capability, logger, signal);\n}\n\n/**\n * Routes a resolved embedding request to the per-format adapter.\n * @internal\n */\nfunction dispatchEmbedding(\n  format: AiEmbeddingApiFormat,\n  config: IAiApiConfig,\n  inputs: ReadonlyArray<string>,\n  request: IAiEmbeddingParams,\n  capability: IAiEmbeddingModelCapability,\n  logger?: Logging.ILogger,\n  signal?: AbortSignal\n): Promise<Result<IAiEmbeddingResult>> {\n  switch (format) {\n    case 'openai-embeddings':\n      return callOpenAiEmbeddings(config, inputs, request, capability, logger, signal);\n    case 'gemini-embeddings':\n      return callGeminiEmbeddings(config, inputs, request, capability, logger, signal);\n    /* c8 ignore next 4 - defensive: exhaustive switch guaranteed by TypeScript */\n    default: {\n      const _exhaustive: never = format;\n      return Promise.resolve(fail(`unsupported embedding API format: ${String(_exhaustive)}`));\n    }\n  }\n}\n\n// ============================================================================\n// Proxied embedding\n// ============================================================================\n\nconst proxiedEmbeddingUsage: Validator<IAiEmbeddingUsage> = Validators.object<IAiEmbeddingUsage>({\n  promptTokens: Validators.number.optional(),\n  totalTokens: Validators.number.optional()\n});\nconst proxiedEmbeddingResponse: Validator<IAiEmbeddingResult> = Validators.object<IAiEmbeddingResult>({\n  vectors: Validators.arrayOf(Validators.arrayOf(Validators.number)),\n  model: Validators.string,\n  dimensions: Validators.number,\n  usage: proxiedEmbeddingUsage.optional()\n});\n\n/**\n * Calls the embedding endpoint on a proxy server instead of calling the provider\n * API directly from the browser. Endpoint: `POST ${proxyUrl}/api/ai/embedding`.\n * Request body: `{ providerId, apiKey, params, modelOverride? }`. The proxy\n * handles descriptor lookup, model/capability resolution, and provider dispatch.\n * Error body `{ error: string }` is surfaced as `proxy: ${error}`.\n *\n * @param proxyUrl - Base URL of the proxy server (e.g. `http://localhost:3001`).\n * @param params - Same parameters as {@link AiAssist.callProviderEmbedding}.\n * @returns The embedding result, or a failure.\n * @public\n */\nexport async function callProxiedEmbedding(\n  proxyUrl: string,\n  params: IProviderEmbeddingParams\n): Promise<Result<IAiEmbeddingResult>> {\n  const { descriptor, apiKey, params: request, modelOverride, logger, signal } = params;\n\n  const body: Record<string, unknown> = {\n    providerId: descriptor.id,\n    apiKey,\n    params: request\n  };\n  if (modelOverride !== undefined) {\n    body.modelOverride = modelOverride;\n  }\n\n  /* c8 ignore next 1 - optional logger */\n  logger?.info(`AI embedding proxy request: provider=${descriptor.id}, proxy=${proxyUrl}`);\n\n  const url = `${proxyUrl}/api/ai/embedding`;\n  const jsonResult = await fetchJson(url, {}, body, logger, signal);\n  if (jsonResult.isFailure()) {\n    return fail(jsonResult.message);\n  }\n\n  const response = jsonResult.value;\n  if (typeof response.error === 'string') {\n    return fail(`proxy: ${response.error}`);\n  }\n\n  return proxiedEmbeddingResponse\n    .validate(response)\n    .withErrorFormat((msg) => `proxy returned invalid response: ${msg}`);\n}\n"]}

package/dist/packlets/ai-assist/http.js

@@ -0,0 +1,75 @@
+// Copyright (c) 2026 Erik Fortune
+//
+// 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.
+/**
+ * Shared low-level HTTP helpers for the AI-assist provider clients (completion,
+ * image generation, embedding). Internal to the packlet.
+ * @packageDocumentation
+ */
+import { isJsonObject } from '@fgv/ts-json-base';
+import { fail, succeed } from '@fgv/ts-utils';
+/**
+ * Makes a JSON POST request and returns the parsed object body, or a failure.
+ * Non-2xx responses, network errors, invalid JSON, and non-object JSON bodies
+ * are all surfaced as `Result.fail`.
+ * @internal
+ */
+export async function fetchJson(url, headers, body, logger, signal) {
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.detail(`AI API request: POST ${url}`);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers: Object.assign({ 'Content-Type': 'application/json' }, headers),
+            body: JSON.stringify(body),
+            signal
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error(`AI API request failed: ${detail}`);
+        return fail(`AI API request failed: ${detail}`);
+    }
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => 'unknown error');
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error(`AI API returned ${response.status}: ${errorText}`);
+        return fail(`AI API returned ${response.status}: ${errorText}`);
+    }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.detail(`AI API response: ${response.status}`);
+    let json;
+    try {
+        json = await response.json();
+    }
+    catch (_a) {
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error('AI API returned invalid JSON response');
+        return fail('AI API returned invalid JSON response');
+    }
+    if (!isJsonObject(json)) {
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error('AI API returned non-object JSON response');
+        return fail('AI API returned non-object JSON response');
+    }
+    return succeed(json);
+}
+//# sourceMappingURL=http.js.map

package/dist/packlets/ai-assist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/http.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY;AAEZ;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAmB,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,IAAI,EAAwB,OAAO,EAAE,MAAM,eAAe,CAAC;AAYpE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,GAAW,EACX,OAA+B,EAC/B,IAAa,EACb,MAAwB,EACxB,MAAoB;IAEpB,wCAAwC;IACxC,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,MAAM,CAAC,wBAAwB,GAAG,EAAE,CAAC,CAAC;IAE9C,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAC1B,MAAM,EAAE,MAAM;YACd,OAAO,kBACL,cAAc,EAAE,kBAAkB,IAC/B,OAAO,CACX;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;YAC1B,MAAM;SACP,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChE,wCAAwC;QACxC,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,KAAK,CAAC,0BAA0B,MAAM,EAAE,CAAC,CAAC;QAClD,OAAO,IAAI,CAAC,0BAA0B,MAAM,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,CAAC;QACrE,wCAAwC;QACxC,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,KAAK,CAAC,mBAAmB,QAAQ,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC,CAAC;QAClE,OAAO,IAAI,CAAC,mBAAmB,QAAQ,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC,CAAC;IAClE,CAAC;IAED,wCAAwC;IACxC,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,MAAM,CAAC,oBAAoB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IAEtD,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IAAC,WAAM,CAAC;QACP,wCAAwC;QACxC,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,KAAK,CAAC,uCAAuC,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC,uCAAuC,CAAC,CAAC;IACvD,CAAC;IAED,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,wCAAwC;QACxC,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC1D,OAAO,IAAI,CAAC,0CAA0C,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\n/**\n * Shared low-level HTTP helpers for the AI-assist provider clients (completion,\n * image generation, embedding). Internal to the packlet.\n * @packageDocumentation\n */\n\nimport { isJsonObject, type JsonObject } from '@fgv/ts-json-base';\nimport { fail, type Logging, Result, succeed } from '@fgv/ts-utils';\n\n/**\n * Internal API configuration built from a provider descriptor.\n * @internal\n */\nexport interface IAiApiConfig {\n  readonly baseUrl: string;\n  readonly apiKey: string;\n  readonly model: string;\n}\n\n/**\n * Makes a JSON POST request and returns the parsed object body, or a failure.\n * Non-2xx responses, network errors, invalid JSON, and non-object JSON bodies\n * are all surfaced as `Result.fail`.\n * @internal\n */\nexport async function fetchJson(\n  url: string,\n  headers: Record<string, string>,\n  body: unknown,\n  logger?: Logging.ILogger,\n  signal?: AbortSignal\n): Promise<Result<JsonObject>> {\n  /* c8 ignore next 1 - optional logger */\n  logger?.detail(`AI API request: POST ${url}`);\n\n  let response: Response;\n  try {\n    response = await fetch(url, {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n        ...headers\n      },\n      body: JSON.stringify(body),\n      signal\n    });\n  } catch (err: unknown) {\n    const detail = err instanceof Error ? err.message : String(err);\n    /* c8 ignore next 1 - optional logger */\n    logger?.error(`AI API request failed: ${detail}`);\n    return fail(`AI API request failed: ${detail}`);\n  }\n\n  if (!response.ok) {\n    const errorText = await response.text().catch(() => 'unknown error');\n    /* c8 ignore next 1 - optional logger */\n    logger?.error(`AI API returned ${response.status}: ${errorText}`);\n    return fail(`AI API returned ${response.status}: ${errorText}`);\n  }\n\n  /* c8 ignore next 1 - optional logger */\n  logger?.detail(`AI API response: ${response.status}`);\n\n  let json: unknown;\n  try {\n    json = await response.json();\n  } catch {\n    /* c8 ignore next 1 - optional logger */\n    logger?.error('AI API returned invalid JSON response');\n    return fail('AI API returned invalid JSON response');\n  }\n\n  if (!isJsonObject(json)) {\n    /* c8 ignore next 1 - optional logger */\n    logger?.error('AI API returned non-object JSON response');\n    return fail('AI API returned non-object JSON response');\n  }\n  return succeed(json);\n}\n"]}

package/dist/packlets/ai-assist/index.js

@@ -2,13 +2,15 @@
  * AI assist packlet - provider registry, prompt class, settings, and API client.
  * @packageDocumentation
  */
-export { AiPrompt, DEFAULT_AI_ASSIST, allModelSpecKeys, MODEL_SPEC_BASE_KEY, resolveModel, toDataUrl } from './model';
+export { AiPrompt, allModelCapabilities, DEFAULT_AI_ASSIST, allModelSpecKeys, MODEL_SPEC_BASE_KEY, resolveModel, toDataUrl } from './model';
 export { resolveImageOptions, validateResolvedOptions } from './imageOptionsResolver';
-export { allProviderIds, getProviderDescriptors, getProviderDescriptor, resolveImageCapability, supportsImageGeneration, DEFAULT_MODEL_CAPABILITY_CONFIG } from './registry';
+export { allProviderIds, getProviderDescriptors, getProviderDescriptor, resolveImageCapability, supportsImageGeneration, resolveEmbeddingCapability, supportsEmbedding, DEFAULT_MODEL_CAPABILITY_CONFIG } from './registry';
 export { callProviderCompletion, callProxiedCompletion, callProviderImageGeneration, callProxiedImageGeneration, callProviderListModels, callProxiedListModels } from './apiClient';
-export { callProviderCompletionStream, callProxiedCompletionStream } from './streamingClient';
-export { aiProviderId, aiServerToolType, aiWebSearchToolConfig, aiServerToolConfig, aiToolEnablement, aiAssistProviderConfig, aiAssistSettings, modelSpecKey, modelSpec } from './converters';
+export { callProviderEmbedding, callProxiedEmbedding } from './embeddingClient';
+export { callProviderCompletionStream, callProxiedCompletionStream, executeClientToolTurn } from './streamingClient';
+export { aiProviderId, aiServerToolType, aiWebSearchToolConfig, aiServerToolConfig, aiClientToolConfig, aiToolEnablement, aiAssistProviderConfig, aiAssistSettings, modelSpecKey, modelSpec } from './converters';
 export { resolveEffectiveTools } from './toolFormats';
 export { extractJsonText, fencedStringifiedJson } from './jsonResponse';
 export { generateJsonCompletion, SMART_JSON_PROMPT_HINT } from './jsonCompletion';
+export { anthropicEffortToBudgetTokens } from './thinkingOptionsResolver';
 //# sourceMappingURL=index.js.map

package/dist/packlets/ai-assist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,QAAQ,EAeR,iBAAiB,EA2CjB,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EACZ,SAAS,EAiBV,MAAM,SAAS,CAAC;AAEjB,OAAO,EAEL,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,+BAA+B,EAChC,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,2BAA2B,EAC3B,0BAA0B,EAC1B,sBAAsB,EACtB,qBAAqB,EAItB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,4BAA4B,EAC5B,2BAA2B,EAE5B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACV,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,EACL,eAAe,EACf,qBAAqB,EAItB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EAIvB,MAAM,kBAAkB,CAAC","sourcesContent":["/**\n * AI assist packlet - provider registry, prompt class, settings, and API client.\n * @packageDocumentation\n */\n\nexport {\n  AiPrompt,\n  type AiModelCapability,\n  type AiProviderId,\n  type AiServerToolType,\n  type AiServerToolConfig,\n  type IAiWebSearchToolConfig,\n  type IAiToolEnablement,\n  type IAiCompletionResponse,\n  type IChatMessage,\n  type AiApiFormat,\n  type AiImageApiFormat,\n  type IAiImageModelCapability,\n  type IAiProviderDescriptor,\n  type IAiAssistProviderConfig,\n  type IAiAssistSettings,\n  DEFAULT_AI_ASSIST,\n  type IAiAssistKeyStore,\n  type IAiImageAttachment,\n  type IAiImageData,\n  type AiImageSize,\n  type AiImageQuality,\n  type DallE2Size,\n  type DallE3Size,\n  type GptImageSize,\n  type DallE3Quality,\n  type GptImageQuality,\n  type DallEModelNames,\n  type GptImageModelNames,\n  type GrokImagineModelNames,\n  type Imagen4ModelNames,\n  type GeminiFlashImageModelNames,\n  type IDallEImageGenerationConfig,\n  type IGptImageGenerationConfig,\n  type IGrokImagineImageGenerationConfig,\n  type IImagen4GenerationConfig,\n  type IGeminiFlashImageGenerationConfig,\n  type IDallEModelOptions,\n  type IGptImageModelOptions,\n  type IGrokImagineModelOptions,\n  type IImagen4ModelOptions,\n  type IGeminiFlashImageModelOptions,\n  type IOtherModelOptions,\n  type IModelFamilyConfig,\n  type IAiImageGenerationOptions,\n  type IAiImageGenerationParams,\n  type IAiGeneratedImage,\n  type IAiImageGenerationResponse,\n  type IAiModelCapabilityRule,\n  type IAiModelCapabilityConfig,\n  type IAiModelInfo,\n  type IAiStreamEvent,\n  type IAiStreamTextDelta,\n  type IAiStreamToolEvent,\n  type IAiStreamDone,\n  type IAiStreamError,\n  type ModelSpec,\n  type ModelSpecKey,\n  type IModelSpecMap,\n  allModelSpecKeys,\n  MODEL_SPEC_BASE_KEY,\n  resolveModel,\n  toDataUrl,\n  type AiThinkingMode,\n  type IThinkingConfig,\n  type IThinkingProviderConfig,\n  type IAnthropicThinkingOptions,\n  type IOpenAiThinkingOptions,\n  type IGeminiThinkingOptions,\n  type IXAiThinkingOptions,\n  type IOtherThinkingOptions,\n  type IAnthropicThinkingConfig,\n  type IOpenAiThinkingConfig,\n  type IGeminiThinkingConfig,\n  type IXAiThinkingConfig,\n  type AnthropicThinkingModelNames,\n  type OpenAiThinkingModelNames,\n  type GeminiThinkingModelNames,\n  type XAiThinkingModelNames\n} from './model';\n\nexport {\n  type IResolvedImageOptions,\n  resolveImageOptions,\n  validateResolvedOptions\n} from './imageOptionsResolver';\n\nexport {\n  allProviderIds,\n  getProviderDescriptors,\n  getProviderDescriptor,\n  resolveImageCapability,\n  supportsImageGeneration,\n  DEFAULT_MODEL_CAPABILITY_CONFIG\n} from './registry';\n\nexport {\n  callProviderCompletion,\n  callProxiedCompletion,\n  callProviderImageGeneration,\n  callProxiedImageGeneration,\n  callProviderListModels,\n  callProxiedListModels,\n  type IProviderCompletionParams,\n  type IProviderImageGenerationParams,\n  type IProviderListModelsParams\n} from './apiClient';\n\nexport {\n  callProviderCompletionStream,\n  callProxiedCompletionStream,\n  type IProviderCompletionStreamParams\n} from './streamingClient';\n\nexport {\n  aiProviderId,\n  aiServerToolType,\n  aiWebSearchToolConfig,\n  aiServerToolConfig,\n  aiToolEnablement,\n  aiAssistProviderConfig,\n  aiAssistSettings,\n  modelSpecKey,\n  modelSpec\n} from './converters';\n\nexport { resolveEffectiveTools } from './toolFormats';\n\nexport {\n  extractJsonText,\n  fencedStringifiedJson,\n  type IFencedStringifiedJsonExtractorOptions,\n  type IFencedStringifiedJsonOptions,\n  type JsonTextExtractor\n} from './jsonResponse';\n\nexport {\n  generateJsonCompletion,\n  SMART_JSON_PROMPT_HINT,\n  type IGenerateJsonCompletionParams,\n  type IGenerateJsonCompletionResult,\n  type JsonPromptHint\n} from './jsonCompletion';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,QAAQ,EAER,oBAAoB,EA2BpB,iBAAiB,EA8CjB,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EACZ,SAAS,EAiBV,MAAM,SAAS,CAAC;AAEjB,OAAO,EAEL,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,EAC1B,iBAAiB,EACjB,+BAA+B,EAChC,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,2BAA2B,EAC3B,0BAA0B,EAC1B,sBAAsB,EACtB,qBAAqB,EAItB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EAErB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,4BAA4B,EAC5B,2BAA2B,EAE3B,qBAAqB,EAGtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACV,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,EACL,eAAe,EACf,qBAAqB,EAItB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EAIvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,6BAA6B,EAAgC,MAAM,2BAA2B,CAAC","sourcesContent":["/**\n * AI assist packlet - provider registry, prompt class, settings, and API client.\n * @packageDocumentation\n */\n\nexport {\n  AiPrompt,\n  type AiModelCapability,\n  allModelCapabilities,\n  type AiProviderId,\n  type AiServerToolType,\n  type AiServerToolConfig,\n  type AiToolConfig,\n  type IAiWebSearchToolConfig,\n  type IAiClientToolConfig,\n  type IAiClientTool,\n  type IAiClientToolCallSummary,\n  type IAiClientToolContinuation,\n  type IAiClientToolTurnResult,\n  type IAiToolEnablement,\n  type IAiCompletionResponse,\n  type IChatMessage,\n  type IChatRequest,\n  type AiApiFormat,\n  type AiImageApiFormat,\n  type AiEmbeddingApiFormat,\n  type AiEmbeddingTaskType,\n  type IAiEmbeddingModelCapability,\n  type IAiEmbeddingParams,\n  type IAiEmbeddingUsage,\n  type IAiEmbeddingResult,\n  type IAiImageModelCapability,\n  type IAiProviderDescriptor,\n  type IAiAssistProviderConfig,\n  type IAiAssistSettings,\n  DEFAULT_AI_ASSIST,\n  type IAiAssistKeyStore,\n  type IAiImageAttachment,\n  type IAiImageData,\n  type AiImageSize,\n  type AiImageQuality,\n  type DallE2Size,\n  type DallE3Size,\n  type GptImageSize,\n  type DallE3Quality,\n  type GptImageQuality,\n  type DallEModelNames,\n  type GptImageModelNames,\n  type GrokImagineModelNames,\n  type Imagen4ModelNames,\n  type GeminiFlashImageModelNames,\n  type IDallEImageGenerationConfig,\n  type IGptImageGenerationConfig,\n  type IGrokImagineImageGenerationConfig,\n  type IImagen4GenerationConfig,\n  type IGeminiFlashImageGenerationConfig,\n  type IDallEModelOptions,\n  type IGptImageModelOptions,\n  type IGrokImagineModelOptions,\n  type IImagen4ModelOptions,\n  type IGeminiFlashImageModelOptions,\n  type IOtherModelOptions,\n  type IModelFamilyConfig,\n  type IAiImageGenerationOptions,\n  type IAiImageGenerationParams,\n  type IAiGeneratedImage,\n  type IAiImageGenerationResponse,\n  type IAiModelCapabilityRule,\n  type IAiModelCapabilityConfig,\n  type IAiModelInfo,\n  type IAiStreamEvent,\n  type IAiStreamTextDelta,\n  type IAiStreamToolEvent,\n  type IAiStreamToolUseStart,\n  type IAiStreamToolUseDelta,\n  type IAiStreamToolUseComplete,\n  type IAiStreamDone,\n  type IAiStreamError,\n  type ModelSpec,\n  type ModelSpecKey,\n  type IModelSpecMap,\n  allModelSpecKeys,\n  MODEL_SPEC_BASE_KEY,\n  resolveModel,\n  toDataUrl,\n  type AiThinkingMode,\n  type IThinkingConfig,\n  type IThinkingProviderConfig,\n  type IAnthropicThinkingOptions,\n  type IOpenAiThinkingOptions,\n  type IGeminiThinkingOptions,\n  type IXAiThinkingOptions,\n  type IOtherThinkingOptions,\n  type IAnthropicThinkingConfig,\n  type IOpenAiThinkingConfig,\n  type IGeminiThinkingConfig,\n  type IXAiThinkingConfig,\n  type AnthropicThinkingModelNames,\n  type OpenAiThinkingModelNames,\n  type GeminiThinkingModelNames,\n  type XAiThinkingModelNames\n} from './model';\n\nexport {\n  type IResolvedImageOptions,\n  resolveImageOptions,\n  validateResolvedOptions\n} from './imageOptionsResolver';\n\nexport {\n  allProviderIds,\n  getProviderDescriptors,\n  getProviderDescriptor,\n  resolveImageCapability,\n  supportsImageGeneration,\n  resolveEmbeddingCapability,\n  supportsEmbedding,\n  DEFAULT_MODEL_CAPABILITY_CONFIG\n} from './registry';\n\nexport {\n  callProviderCompletion,\n  callProxiedCompletion,\n  callProviderImageGeneration,\n  callProxiedImageGeneration,\n  callProviderListModels,\n  callProxiedListModels,\n  type IProviderCompletionParams,\n  type IProviderImageGenerationParams,\n  type IProviderListModelsParams\n} from './apiClient';\n\nexport {\n  callProviderEmbedding,\n  callProxiedEmbedding,\n  type IProviderEmbeddingParams\n} from './embeddingClient';\n\nexport {\n  callProviderCompletionStream,\n  callProxiedCompletionStream,\n  type IProviderCompletionStreamParams,\n  executeClientToolTurn,\n  type IExecuteClientToolTurnParams,\n  type IExecuteClientToolTurnResult\n} from './streamingClient';\n\nexport {\n  aiProviderId,\n  aiServerToolType,\n  aiWebSearchToolConfig,\n  aiServerToolConfig,\n  aiClientToolConfig,\n  aiToolEnablement,\n  aiAssistProviderConfig,\n  aiAssistSettings,\n  modelSpecKey,\n  modelSpec\n} from './converters';\n\nexport { resolveEffectiveTools } from './toolFormats';\n\nexport {\n  extractJsonText,\n  fencedStringifiedJson,\n  type IFencedStringifiedJsonExtractorOptions,\n  type IFencedStringifiedJsonOptions,\n  type JsonTextExtractor\n} from './jsonResponse';\n\nexport {\n  generateJsonCompletion,\n  SMART_JSON_PROMPT_HINT,\n  type IGenerateJsonCompletionParams,\n  type IGenerateJsonCompletionResult,\n  type JsonPromptHint\n} from './jsonCompletion';\n\nexport { anthropicEffortToBudgetTokens, type IResolvedThinkingConfig } from './thinkingOptionsResolver';\n"]}

package/dist/packlets/ai-assist/jsonCompletion.js

@@ -39,7 +39,6 @@ var __rest = (this && this.__rest) || function (s, e) {
 import { fail, succeed } from '@fgv/ts-utils';
 import { callProviderCompletion } from './apiClient';
 import { fencedStringifiedJson } from './jsonResponse';
-import { AiPrompt } from './model';
 /**
  * Default system-prompt suffix appended when {@link AiAssist.IGenerateJsonCompletionParams.promptHint}
  * is `'smart'` (the default). Designed to discourage code fences and prose in
@@ -48,13 +47,12 @@ import { AiPrompt } from './model';
  */
 export const SMART_JSON_PROMPT_HINT = 'Respond with raw JSON only — no Markdown code fences, no explanatory prose, ' +
     'no preamble or trailing commentary. The response must parse with JSON.parse.';
-function applyPromptHint(prompt, hint) {
+function applyPromptHint(system, hint) {
     if (hint === 'none') {
-        return prompt;
+        return system;
     }
     const suffix = hint === 'smart' ? SMART_JSON_PROMPT_HINT : hint;
-    const system = prompt.system.length > 0 ? `${prompt.system}\n\n${suffix}` : suffix;
-    return new AiPrompt(prompt.user, system, prompt.attachments);
+    return system !== undefined && system.length > 0 ? `${system}\n\n${suffix}` : suffix;
 }
 /**
  * Calls {@link AiAssist.callProviderCompletion}, then runs the response text
@@ -76,13 +74,13 @@ function applyPromptHint(prompt, hint) {
  * @public
  */
 export async function generateJsonCompletion(params) {
-    const { converter, jsonConverter, promptHint = 'smart', prompt } = params, rest = __rest(params, ["converter", "jsonConverter", "promptHint", "prompt"]);
+    const { converter, jsonConverter, promptHint = 'smart', system } = params, rest = __rest(params, ["converter", "jsonConverter", "promptHint", "system"]);
     if (jsonConverter === undefined && converter === undefined) {
         return fail('generateJsonCompletion: either converter or jsonConverter must be provided.');
     }
     const pipeline = jsonConverter !== null && jsonConverter !== void 0 ? jsonConverter : fencedStringifiedJson({ inner: converter });
-    const augmentedPrompt = applyPromptHint(prompt, promptHint);
-    const response = await callProviderCompletion(Object.assign(Object.assign({}, rest), { prompt: augmentedPrompt }));
+    const augmentedSystem = applyPromptHint(system, promptHint);
+    const response = await callProviderCompletion(Object.assign(Object.assign({}, rest), { system: augmentedSystem }));
     if (response.isFailure()) {
         return fail(response.message);
     }