@fgv/ts-extras 5.1.0-36 → 5.1.0-39

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

@@ -28,7 +28,7 @@
  */
 import { isJsonObject } from '@fgv/ts-json-base';
 import { fail, mapResults, succeed, Validators } from '@fgv/ts-utils';
-import { allModelCapabilities, resolveModel } from './model';
+import { allModelCapabilities, isResponsesOnlyModel, resolveProviderModel } from './model';
 import { anthropicEffortToBudgetTokens, checkTemperatureConflict, mergeThinkingConfig, providerDiscriminatorForId } from './thinkingOptionsResolver';
 import { buildAnthropicMessages, buildGeminiContents, buildMessages, buildOpenAiChatUserContent, buildOpenAiResponsesUserContent, normalizeOutboundMessages, splitChatRequest } from './chatRequestBuilders';
 import { bearerAuthHeader, resolveEffectiveBaseUrl } from './endpoint';
@@ -221,14 +221,14 @@ const geminiResponse = Validators.object({
  * Works for xAI Grok, OpenAI, Groq, and Mistral.
  * @internal
  */
-async function callOpenAiCompletion(config, prompt, head, temperature = 0.7, logger, signal, resolvedThinking) {
+async function callOpenAiCompletion(config, prompt, head, temperature, logger, signal, resolvedThinking) {
     var _a;
     const url = `${config.baseUrl}/chat/completions`;
     const messages = buildMessages(prompt.system, buildOpenAiChatUserContent(prompt), {
         head
     });
     const effort = (_a = resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.openAiEffort) !== null && _a !== void 0 ? _a : resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.xaiEffort;
-    const body = Object.assign(Object.assign({ model: config.model, messages }, (effort === undefined || effort === 'none' ? { temperature } : {})), (effort !== undefined && config.model !== 'grok-4' ? { reasoning_effort: effort } : {}));
+    const body = Object.assign(Object.assign({ model: config.model, messages }, (temperature !== undefined ? { temperature } : {})), (effort !== undefined && config.model !== 'grok-4' ? { reasoning_effort: effort } : {}));
     if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.otherParams) !== undefined) {
         Object.assign(body, resolvedThinking.otherParams);
     }
@@ -274,14 +274,14 @@ function extractResponsesApiText(output) {
  * Used when tools are configured for an openai-format provider.
  * @internal
  */
-async function callOpenAiResponsesCompletion(config, prompt, tools, head, temperature = 0.7, logger, signal, resolvedThinking) {
+async function callOpenAiResponsesCompletion(config, prompt, tools = [], head, temperature, logger, signal, resolvedThinking) {
     var _a;
     const url = `${config.baseUrl}/responses`;
     const input = buildMessages(prompt.system, buildOpenAiResponsesUserContent(prompt), {
         head
     });
     const effort = (_a = resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.openAiEffort) !== null && _a !== void 0 ? _a : resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.xaiEffort;
-    const body = Object.assign(Object.assign({ model: config.model, input, tools: toResponsesApiTools(tools) }, (effort === undefined || effort === 'none' ? { temperature } : {})), (effort !== undefined && config.model !== 'grok-4' ? { reasoning: { effort } } : {}));
+    const body = Object.assign(Object.assign(Object.assign({ model: config.model, input }, (tools.length > 0 ? { tools: toResponsesApiTools(tools) } : {})), (temperature !== undefined ? { temperature } : {})), (effort !== undefined && config.model !== 'grok-4' ? { reasoning: { effort } } : {}));
     if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.otherParams) !== undefined) {
         Object.assign(body, resolvedThinking.otherParams);
     }
@@ -328,10 +328,10 @@ function extractAnthropicText(content) {
     return succeed(textParts.join(''));
 }
 /** Calls the Anthropic Messages API with optional tool support. @internal */
-async function callAnthropicCompletion(config, prompt, head, temperature = 0.7, logger, tools, signal, resolvedThinking) {
+async function callAnthropicCompletion(config, prompt, head, temperature, logger, tools, signal, resolvedThinking) {
     const url = `${config.baseUrl}/messages`;
     const messages = buildAnthropicMessages(prompt, { head });
-    const body = Object.assign({ model: config.model, system: prompt.system, messages, max_tokens: 4096 }, ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.anthropicEffort) === undefined ? { temperature } : {}));
+    const body = Object.assign({ model: config.model, system: prompt.system, messages, max_tokens: 4096 }, (temperature !== undefined ? { temperature } : {}));
     const effort = resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.anthropicEffort;
     if (effort !== undefined) {
         body.thinking = { type: 'enabled', budget_tokens: anthropicEffortToBudgetTokens(effort) };
@@ -378,10 +378,14 @@ async function callAnthropicCompletion(config, prompt, head, temperature = 0.7,
  * When tools are configured, includes Google Search grounding.
  * @internal
  */
-async function callGeminiCompletion(config, prompt, head, temperature = 0.7, logger, tools, signal, resolvedThinking) {
+async function callGeminiCompletion(config, prompt, head, temperature, logger, tools, signal, resolvedThinking) {
     const url = `${config.baseUrl}/models/${config.model}:generateContent`;
     const contents = buildGeminiContents(prompt, { head });
-    const generationConfig = { temperature };
+    // Temperature is sent only when explicitly provided; otherwise Gemini's default applies.
+    const generationConfig = {};
+    if (temperature !== undefined) {
+        generationConfig.temperature = temperature;
+    }
     if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.geminiThinkingBudget) !== undefined) {
         generationConfig.thinkingConfig = { thinkingBudget: resolvedThinking.geminiThinkingBudget };
     }
@@ -430,8 +434,7 @@ async function callGeminiCompletion(config, prompt, head, temperature = 0.7, log
  * @public
  */
 export async function callProviderCompletion(params) {
-    var _a;
-    const { descriptor, apiKey, system, messages, temperature, modelOverride, logger, tools, signal, endpoint, thinking } = params;
+    const { descriptor, apiKey, system, messages, temperature, modelOverride, tier, logger, tools, signal, endpoint, thinking } = params;
     const splitResult = splitChatRequest(system, messages);
     if (splitResult.isFailure()) {
         return fail(splitResult.message);
@@ -446,14 +449,14 @@ export async function callProviderCompletion(params) {
     }
     const hasTools = tools !== undefined && tools.length > 0;
     const discriminator = providerDiscriminatorForId(descriptor.id);
-    const hasThinkingConfig = discriminator !== undefined &&
-        ((thinking === null || thinking === void 0 ? void 0 : thinking.effort) !== undefined ||
-            ((_a = thinking === null || thinking === void 0 ? void 0 : thinking.providers) === null || _a === void 0 ? void 0 : _a.some((b) => b.provider === 'other' || b.provider === discriminator)) === true);
-    const modelContext = hasThinkingConfig ? 'thinking' : hasTools ? 'tools' : undefined;
-    const model = resolveModel(modelOverride !== null && modelOverride !== void 0 ? modelOverride : descriptor.defaultModel, modelContext);
-    if (model.length === 0) {
-        return fail(`provider "${descriptor.id}": no model resolved; pass modelOverride or set descriptor.defaultModel`);
-    }
+    // The quality tier is the only completion-model selector; thinking and tools
+    // are orthogonal request params/capabilities and never pick a model.
+    const modelContext = tier;
+    const modelResult = resolveProviderModel(descriptor, modelOverride, modelContext);
+    if (modelResult.isFailure()) {
+        return fail(modelResult.message);
+    }
+    const model = modelResult.value;
     let resolvedThinking;
     if (thinking !== undefined) {
         if (discriminator !== undefined) {
@@ -469,7 +472,6 @@ export async function callProviderCompletion(params) {
             }
         }
     }
-    const effectiveTemperature = temperature !== null && temperature !== void 0 ? temperature : 0.7;
     const config = {
         baseUrl: baseUrlResult.value,
         apiKey,
@@ -484,14 +486,16 @@ export async function callProviderCompletion(params) {
     }
     switch (descriptor.apiFormat) {
         case 'openai':
-            if (hasTools) {
-                return callOpenAiResponsesCompletion(config, prompt, tools, head, effectiveTemperature, logger, signal, resolvedThinking);
+            // Responses-API-only models (e.g. gpt-5.5-pro) 400 on /chat/completions, so they route
+            // to the Responses path even with no tools requested — same path the tools case uses.
+            if (hasTools || isResponsesOnlyModel(descriptor, config.model)) {
+                return callOpenAiResponsesCompletion(config, prompt, tools, head, temperature, logger, signal, resolvedThinking);
             }
-            return callOpenAiCompletion(config, prompt, head, effectiveTemperature, logger, signal, resolvedThinking);
+            return callOpenAiCompletion(config, prompt, head, temperature, logger, signal, resolvedThinking);
         case 'anthropic':
-            return callAnthropicCompletion(config, prompt, head, effectiveTemperature, logger, tools, signal, resolvedThinking);
+            return callAnthropicCompletion(config, prompt, head, temperature, logger, tools, signal, resolvedThinking);
         case 'gemini':
-            return callGeminiCompletion(config, prompt, head, effectiveTemperature, logger, tools, signal, resolvedThinking);
+            return callGeminiCompletion(config, prompt, head, temperature, logger, tools, signal, resolvedThinking);
         /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
         default: {
             const _exhaustive = descriptor.apiFormat;
@@ -506,13 +510,6 @@ const openAiImageItem = Validators.object({
 const openAiImageResponse = Validators.object({
     data: Validators.arrayOf(openAiImageItem).withConstraint((arr) => arr.length > 0)
 });
-const imagenPrediction = Validators.object({
-    bytesBase64Encoded: Validators.string,
-    mimeType: Validators.string.optional()
-});
-const imagenResponse = Validators.object({
-    predictions: Validators.arrayOf(imagenPrediction).withConstraint((arr) => arr.length > 0)
-});
 const geminiImageInlineData = Validators.object({
     mimeType: Validators.string,
     data: Validators.string
@@ -522,11 +519,12 @@ const geminiImageOutPart = Validators.object({
     inlineData: geminiImageInlineData.optional()
 });
 const geminiImageOutContent = Validators.object({
-    parts: Validators.arrayOf(geminiImageOutPart).withConstraint((arr) => arr.length > 0)
+    parts: Validators.arrayOf(geminiImageOutPart)
 });
 const geminiImageOutCandidate = Validators.object({
-    content: geminiImageOutContent,
-    finishReason: Validators.string.optional()
+    content: geminiImageOutContent.optional(),
+    finishReason: Validators.string.optional(),
+    finishMessage: Validators.string.optional()
 });
 const geminiImageOutResponse = Validators.object({
     candidates: Validators.arrayOf(geminiImageOutCandidate).withConstraint((arr) => arr.length > 0)
@@ -593,9 +591,6 @@ function callOpenAiImagesGenerations(config, request, headers, resolved, capabil
     if (resolved.seed !== undefined) {
         body.seed = resolved.seed;
     }
-    if (resolved.style !== undefined) {
-        body.style = resolved.style;
-    }
     if (resolved.background !== undefined) {
         body.background = resolved.background;
     }
@@ -703,6 +698,14 @@ async function callXaiImageGeneration(config, request, capability, resolved, log
         })
     })));
 }
+/**
+ * Gemini `finishReason` values that indicate a normal terminal completion rather
+ * than a refusal. `STOP` is set on every successful generation (and on completions
+ * that return a text part instead of an image); `MAX_TOKENS` is a benign truncation.
+ * A candidate carrying only one of these is NOT a decline — treating it as one would
+ * mislabel an ordinary no-image outcome as a policy refusal. @internal
+ */
+const benignGeminiImageFinishReasons = new Set(['STOP', 'MAX_TOKENS']);
 /** Calls Gemini :generateContent for image output; accepts ref images as inlineData. @internal */
 async function callGeminiImageOutGeneration(config, request, resolved, logger, signal) {
     var _a;
@@ -732,9 +735,10 @@ async function callGeminiImageOutGeneration(config, request, resolved, logger, s
         .validate(json)
         .withErrorFormat((msg) => `Gemini image API response: ${msg}`)
         .onSuccess((response) => {
+        var _a, _b;
         const images = [];
         for (const candidate of response.candidates) {
-            for (const part of candidate.content.parts) {
+            for (const part of (_b = (_a = candidate.content) === null || _a === void 0 ? void 0 : _a.parts) !== null && _b !== void 0 ? _b : []) {
                 if (part.inlineData) {
                     images.push({
                         mimeType: part.inlineData.mimeType,
@@ -744,80 +748,30 @@ async function callGeminiImageOutGeneration(config, request, resolved, logger, s
             }
         }
         if (images.length === 0) {
+            // A candidate with no image parts is a *decline* only when it carries a
+            // refusal-shaped finishReason — i.e. present and not a benign terminal reason
+            // (`STOP`/`MAX_TOKENS`). A normal completion that emitted text-instead-of-image
+            // carries `finishReason: 'STOP'` and must fall through to the no-image message.
+            const declined = response.candidates.find((candidate) => candidate.finishReason !== undefined &&
+                !benignGeminiImageFinishReasons.has(candidate.finishReason));
+            if ((declined === null || declined === void 0 ? void 0 : declined.finishReason) !== undefined) {
+                // Truthiness (not `!== undefined`) so an empty-string finishMessage is treated
+                // as "no message" and produces no dangling ` — ` separator.
+                const suffix = declined.finishMessage ? ` — ${declined.finishMessage}` : '';
+                return fail(`Gemini image generation declined: ${declined.finishReason}${suffix}`);
+            }
             return fail('Gemini image API response: no image parts in response');
         }
         return succeed({ images });
     }));
 }
-/** Calls the Gemini Imagen :predict endpoint with Imagen 4 params. @internal */
-async function callImagenGeneration(config, request, resolved, logger, signal) {
-    const url = `${config.baseUrl}/models/${config.model}:predict`;
-    const parameters = {
-        sampleCount: resolved.n
-    };
-    if (resolved.imagenAspectRatio !== undefined) {
-        parameters.aspectRatio = resolved.imagenAspectRatio;
-    }
-    if (resolved.imageSize !== undefined) {
-        parameters.imageSize = resolved.imageSize;
-    }
-    if (resolved.addWatermark !== undefined) {
-        parameters.addWatermark = resolved.addWatermark;
-    }
-    if (resolved.enhancePrompt !== undefined) {
-        parameters.enhancePrompt = resolved.enhancePrompt;
-    }
-    if (resolved.imagenOutputMimeType !== undefined || resolved.imagenOutputCompressionQuality !== undefined) {
-        const outputOptions = {};
-        if (resolved.imagenOutputMimeType !== undefined) {
-            outputOptions.mimeType = resolved.imagenOutputMimeType;
-        }
-        if (resolved.imagenOutputCompressionQuality !== undefined) {
-            outputOptions.compressionQuality = resolved.imagenOutputCompressionQuality;
-        }
-        parameters.outputOptions = outputOptions;
-    }
-    if (resolved.personGeneration !== undefined) {
-        parameters.personGeneration = resolved.personGeneration;
-    }
-    if (resolved.seed !== undefined) {
-        parameters.seed = resolved.seed;
-    }
-    if (resolved.otherParams !== undefined) {
-        Object.assign(parameters, resolved.otherParams);
-    }
-    const body = {
-        instances: [{ prompt: request.prompt }],
-        parameters
-    };
-    const headers = { 'x-goog-api-key': config.apiKey };
-    /* c8 ignore next 1 - optional logger */
-    logger === null || logger === void 0 ? void 0 : logger.info(`Imagen generation: model=${config.model}, n=${parameters.sampleCount}`);
-    const jsonResult = await fetchJson(url, headers, body, logger, signal);
-    if (jsonResult.isFailure()) {
-        return fail(jsonResult.message);
-    }
-    return imagenResponse
-        .validate(jsonResult.value)
-        .withErrorFormat((msg) => `Imagen API response: ${msg}`)
-        .onSuccess((response) => {
-        const images = response.predictions.map((p) => {
-            var _a;
-            return ({
-                mimeType: (_a = p.mimeType) !== null && _a !== void 0 ? _a : 'image/png',
-                base64: p.bytesBase64Encoded
-            });
-        });
-        return succeed({ images });
-    });
-}
 // ============================================================================
 // Image generation — dispatcher
 // ============================================================================
 /**
  * Calls the appropriate image-generation API for a given provider. Routes by the
  * `format` field of the resolved {@link IAiImageModelCapability}:
- * `'openai-images'`, `'xai-images'`, `'xai-images-edits'`, `'gemini-imagen'`, or
+ * `'openai-images'`, `'xai-images'`, `'xai-images-edits'`, or
  * `'gemini-image-out'`. Rejects up front if `referenceImages` is set but the
  * capability does not declare `acceptsImageReferenceInput`.
  * @param params - Request parameters including descriptor, API key, and prompt
@@ -833,12 +787,11 @@ export async function callProviderImageGeneration(params) {
     if (baseUrlResult.isFailure()) {
         return fail(baseUrlResult.message);
     }
-    const model = resolveModel(modelOverride !== null && modelOverride !== void 0 ? modelOverride : descriptor.defaultModel, 'image');
-    if (model.length === 0) {
-        return fail(`provider "${descriptor.id}": no image model resolved; ` +
-            `pass modelOverride or set descriptor.defaultModel ` +
-            `(a plain string, or an object with an "image" entry)`);
+    const modelResult = resolveProviderModel(descriptor, modelOverride, 'image');
+    if (modelResult.isFailure()) {
+        return fail(modelResult.message);
     }
+    const model = modelResult.value;
     const capability = resolveImageCapability(descriptor, model);
     if (capability === undefined) {
         return fail(`provider "${descriptor.id}" does not support image generation for model "${model}"`);
@@ -885,8 +838,6 @@ export async function callProviderImageGeneration(params) {
             }
             return callXaiImageGeneration(config, request, capability, resolved, logger, signal);
         }
-        case 'gemini-imagen':
-            return callImagenGeneration(config, request, resolved, logger, signal);
         case 'gemini-image-out':
             return callGeminiImageOutGeneration(config, request, resolved, logger, signal);
         /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
@@ -1180,9 +1131,13 @@ export async function callProxiedCompletion(proxyUrl, params) {
     const body = {
         providerId: descriptor.id,
         apiKey,
-        messages: normalizeOutboundMessages(splitResult.value),
-        temperature: temperature !== null && temperature !== void 0 ? temperature : 0.7
+        messages: normalizeOutboundMessages(splitResult.value)
     };
+    // Temperature is forwarded only when explicitly provided, matching the direct path — the proxy
+    // omits it from the upstream request so the provider default applies.
+    if (temperature !== undefined) {
+        body.temperature = temperature;
+    }
     if (system !== undefined) {
         body.system = system;
     }