The best way to control Claude Code, Codex and more from any computer or phone

main
ts 1,848 lines 58.2 KB
Raw
1 /**
2 * The `OpenAiLanguageModel` module adapts OpenAI-compatible chat completions
3 * providers to Effect AI's `LanguageModel` service. It builds a model service
4 * from a model id, translates prompts, files, tools, structured output schemas,
5 * and provider-specific options into `OpenAiClient` requests, and maps normal
6 * or streaming chat completion results back into Effect AI response content and
7 * metadata.
8 *
9 * @stability unstable
10 * @since 4.0.0
11 */
12 import * as AiError from "effect/ai/AiError"
13 import * as LanguageModel from "effect/ai/LanguageModel"
14 import * as AiModel from "effect/ai/Model"
15 import { toCodecOpenAI } from "effect/ai/OpenAiStructuredOutput"
16 import * as Prompt from "effect/ai/Prompt"
17 import type * as Response from "effect/ai/Response"
18 import * as Tool from "effect/ai/Tool"
19 import * as Arr from "effect/Array"
20 import * as Context from "effect/Context"
21 import * as DateTime from "effect/DateTime"
22 import * as Effect from "effect/Effect"
23 import * as Base64 from "effect/encoding/Base64"
24 import { dual } from "effect/Function"
25 import type * as HttpClientResponse from "effect/http/HttpClientResponse"
26 import * as Layer from "effect/Layer"
27 import * as Predicate from "effect/Predicate"
28 import * as Rec from "effect/Record"
29 import * as Redactable from "effect/Redactable"
30 import * as Schema from "effect/Schema"
31 import * as AST from "effect/SchemaAST"
32 import * as Stream from "effect/Stream"
33 import type { Span } from "effect/Tracer"
34 import type { Simplify } from "effect/Types"
35 import * as InternalUtilities from "./internal/utilities.ts"
36 import {
37 type Annotation,
38 type ChatCompletionContentPart,
39 type ChatCompletionRequestMessage,
40 type ChatCompletionRequestToolCall,
41 type CreateResponse,
42 type CreateResponse200,
43 type CreateResponse200Sse,
44 type CreateResponseRequestJson,
45 type InputContent,
46 type MessageStatus,
47 OpenAiClient,
48 type TextResponseFormatConfiguration,
49 type Tool as OpenAiClientTool,
50 type UnknownChatCompletionEvent
51 } from "./OpenAiClient.ts"
52 import { addGenAIAnnotations } from "./OpenAiTelemetry.ts"
53
54 /**
55 * Image detail level for vision requests.
56 */
57 type ImageDetail = "auto" | "low" | "high"
58
59 // =============================================================================
60 // Configuration
61 // =============================================================================
62
63 type ConfigOptions = Simplify<
64 & Partial<
65 Omit<CreateResponse, "input" | "tools" | "tool_choice" | "stream" | "text" | "store" | "conversation">
66 >
67 & {
68 /**
69 * File ID prefixes used to identify file IDs in Responses API.
70 * When undefined, all file data is treated as base64 content.
71 *
72 * Examples:
73 * - OpenAI: ['file-'] for IDs like 'file-abc123'
74 * - Azure OpenAI: ['assistant-'] for IDs like 'assistant-abc123'
75 */
76 readonly fileIdPrefixes?: ReadonlyArray<string> | undefined
77 /**
78 * Configuration options for a text response from the model.
79 */
80 readonly text?: {
81 /**
82 * Constrains the verbosity of the model's response. Lower values will
83 * result in more concise responses, while higher values will result in
84 * more verbose responses.
85 *
86 * Defaults to `"medium"`.
87 */
88 readonly verbosity?: "low" | "medium" | "high" | undefined
89 } | undefined
90 /**
91 * Whether to use strict JSON schema validation.
92 *
93 * Defaults to `true`.
94 */
95 readonly strictJsonSchema?: boolean | undefined
96 }
97 >
98 type ModelConfig = Omit<ConfigOptions, "model"> & { readonly [x: string]: unknown }
99
100 /**
101 * Context service for OpenAI language model configuration.
102 *
103 * **When to use**
104 *
105 * Use as the context service for OpenAI-compatible language model request
106 * configuration, especially when a scoped operation should override the defaults
107 * supplied to `model`, `make`, or `layer`.
108 *
109 * @see {@link withConfigOverride} for scoping language model request overrides
110 *
111 * @stability unstable
112 * @category services
113 * @since 4.0.0
114 */
115 export class Config extends Context.Service<
116 Config,
117 ConfigOptions & { readonly [x: string]: unknown }
118 >()("@effect/ai-openai-compat/OpenAiLanguageModel/Config") {}
119
120 // =============================================================================
121 // Provider Options / Metadata
122 // =============================================================================
123
124 declare module "effect/ai/Prompt" {
125 /**
126 * OpenAI-compatible options for file prompt parts.
127 *
128 * @stability unstable
129 * @category models
130 * @since 4.0.0
131 */
132 export interface FilePartOptions extends ProviderOptions {
133 /**
134 * Provider-specific file options for OpenAI-compatible APIs.
135 */
136 readonly "openai-compat"?: {
137 /**
138 * The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`.
139 */
140 readonly imageDetail?: ImageDetail | null
141 } | null
142 }
143
144 /**
145 * OpenAI-compatible options for reasoning prompt parts.
146 *
147 * @stability unstable
148 * @category models
149 * @since 4.0.0
150 */
151 export interface ReasoningPartOptions extends ProviderOptions {
152 /**
153 * Provider-specific reasoning options for OpenAI-compatible APIs.
154 */
155 readonly "openai-compat"?: {
156 /**
157 * The ID of the item to reference.
158 */
159 readonly itemId?: string | null
160 /**
161 * The encrypted content of the reasoning item - populated when a response
162 * is generated with `reasoning.encrypted_content` in the `include`
163 * parameter.
164 */
165 readonly encryptedContent?: string | null
166 /**
167 * The chat message field the reasoning was returned under. Replayed
168 * reasoning is sent back under the same field, defaulting to
169 * `reasoning_content`.
170 */
171 readonly reasoningField?: "reasoning" | "reasoning_content" | null
172 } | null
173 }
174
175 /**
176 * OpenAI-compatible options for assistant tool-call prompt parts.
177 *
178 * @stability unstable
179 * @category models
180 * @since 4.0.0
181 */
182 export interface ToolCallPartOptions extends ProviderOptions {
183 /**
184 * Provider-specific tool-call options for OpenAI-compatible APIs.
185 */
186 readonly "openai-compat"?: {
187 /**
188 * The ID of the item to reference.
189 */
190 readonly itemId?: string | null
191 /**
192 * The status to send for the tool-call item.
193 */
194 readonly status?: MessageStatus | null
195 /**
196 * Provider-specific extra content to echo back with the tool call.
197 */
198 readonly extraContent?: Schema.JsonObject | null
199 } | null
200 }
201
202 /**
203 * OpenAI-compatible options for tool-result prompt parts.
204 *
205 * @stability unstable
206 * @category models
207 * @since 4.0.0
208 */
209 export interface ToolResultPartOptions extends ProviderOptions {
210 /**
211 * Provider-specific tool-result options for OpenAI-compatible APIs.
212 */
213 readonly "openai-compat"?: {
214 /**
215 * The ID of the item to reference.
216 */
217 readonly itemId?: string | null
218 /**
219 * The status to send for the tool-result item.
220 */
221 readonly status?: MessageStatus | null
222 } | null
223 }
224
225 /**
226 * OpenAI-compatible options for text prompt parts.
227 *
228 * @stability unstable
229 * @category models
230 * @since 4.0.0
231 */
232 export interface TextPartOptions extends ProviderOptions {
233 /**
234 * Provider-specific text options for OpenAI-compatible APIs.
235 */
236 readonly "openai-compat"?: {
237 /**
238 * The ID of the item to reference.
239 */
240 readonly itemId?: string | null
241 /**
242 * The status to send for the text item.
243 */
244 readonly status?: MessageStatus | null
245 /**
246 * A list of annotations that apply to the output text.
247 */
248 readonly annotations?: ReadonlyArray<Annotation> | null
249 } | null
250 }
251 }
252
253 declare module "effect/ai/Response" {
254 /**
255 * OpenAI-compatible metadata attached to a complete text response part.
256 *
257 * @stability unstable
258 * @category models
259 * @since 4.0.0
260 */
261 export interface TextPartMetadata extends ProviderMetadata {
262 /**
263 * Provider-specific metadata returned for the text part.
264 */
265 readonly "openai-compat"?: {
266 /**
267 * The OpenAI item ID associated with the text part.
268 */
269 readonly itemId?: string | null
270 /**
271 * If the model emits a refusal content part, the refusal explanation
272 * from the model will be contained in the metadata of an empty text
273 * part.
274 */
275 readonly refusal?: string | null
276 /**
277 * The status returned for the text item.
278 */
279 readonly status?: MessageStatus | null
280 /**
281 * The text content part annotations.
282 */
283 readonly annotations?: ReadonlyArray<Annotation> | null
284 }
285 }
286
287 /**
288 * OpenAI-compatible metadata emitted when a streamed text part starts.
289 *
290 * @stability unstable
291 * @category models
292 * @since 4.0.0
293 */
294 export interface TextStartPartMetadata extends ProviderMetadata {
295 /**
296 * Provider-specific metadata returned for the streamed text start.
297 */
298 readonly "openai-compat"?: {
299 /**
300 * The OpenAI item ID associated with the streamed text part.
301 */
302 readonly itemId?: string | null
303 } | null
304 }
305
306 /**
307 * OpenAI-compatible metadata emitted when a streamed text part ends.
308 *
309 * @stability unstable
310 * @category models
311 * @since 4.0.0
312 */
313 export interface TextEndPartMetadata extends ProviderMetadata {
314 /**
315 * Provider-specific metadata returned for the streamed text end.
316 */
317 readonly "openai-compat"?: {
318 /**
319 * The OpenAI item ID associated with the streamed text part.
320 */
321 readonly itemId?: string | null
322 /**
323 * The annotations collected for the completed streamed text part.
324 */
325 readonly annotations?: ReadonlyArray<Annotation> | null
326 } | null
327 }
328
329 /**
330 * OpenAI-compatible metadata attached to a complete reasoning response part.
331 *
332 * @stability unstable
333 * @category models
334 * @since 4.0.0
335 */
336 export interface ReasoningPartMetadata extends ProviderMetadata {
337 /**
338 * Provider-specific metadata returned for the reasoning part.
339 */
340 readonly "openai-compat"?: {
341 /**
342 * The OpenAI item ID associated with the reasoning part.
343 */
344 readonly itemId?: string | null
345 /**
346 * Encrypted reasoning content that can be sent back in later requests.
347 */
348 readonly encryptedContent?: string | null
349 /**
350 * The chat message field the provider returned the reasoning under.
351 */
352 readonly reasoningField?: "reasoning" | "reasoning_content" | null
353 } | null
354 }
355
356 /**
357 * OpenAI-compatible metadata emitted when a streamed reasoning part starts.
358 *
359 * @stability unstable
360 * @category models
361 * @since 4.0.0
362 */
363 export interface ReasoningStartPartMetadata extends ProviderMetadata {
364 /**
365 * Provider-specific metadata returned for the streamed reasoning start.
366 */
367 readonly "openai-compat"?: {
368 /**
369 * The OpenAI item ID associated with the reasoning part.
370 */
371 readonly itemId?: string | null
372 /**
373 * Encrypted reasoning content that can be sent back in later requests.
374 */
375 readonly encryptedContent?: string | null
376 /**
377 * The chat message field the provider returned the reasoning under.
378 */
379 readonly reasoningField?: "reasoning" | "reasoning_content" | null
380 } | null
381 }
382
383 /**
384 * OpenAI-compatible metadata emitted for a streamed reasoning delta.
385 *
386 * @stability unstable
387 * @category models
388 * @since 4.0.0
389 */
390 export interface ReasoningDeltaPartMetadata extends ProviderMetadata {
391 /**
392 * Provider-specific metadata returned for the streamed reasoning delta.
393 */
394 readonly "openai-compat"?: {
395 /**
396 * The OpenAI item ID associated with the reasoning part.
397 */
398 readonly itemId?: string | null
399 } | null
400 }
401
402 /**
403 * OpenAI-compatible metadata emitted when a streamed reasoning part ends.
404 *
405 * @stability unstable
406 * @category models
407 * @since 4.0.0
408 */
409 export interface ReasoningEndPartMetadata extends ProviderMetadata {
410 /**
411 * Provider-specific metadata returned for the streamed reasoning end.
412 */
413 readonly "openai-compat"?: {
414 /**
415 * The OpenAI item ID associated with the reasoning part.
416 */
417 readonly itemId?: string | null
418 /**
419 * Encrypted reasoning content that can be sent back in later requests.
420 */
421 readonly encryptedContent?: string
422 } | null
423 }
424
425 /**
426 * OpenAI-compatible metadata attached to tool-call response parts.
427 *
428 * @stability unstable
429 * @category models
430 * @since 4.0.0
431 */
432 export interface ToolCallPartMetadata extends ProviderMetadata {
433 /**
434 * Provider-specific metadata returned for the tool call.
435 */
436 readonly "openai-compat"?: {
437 /**
438 * The OpenAI item ID associated with the tool call.
439 */
440 readonly itemId?: string | null
441 /**
442 * Provider-specific extra content returned with the tool call.
443 */
444 readonly extraContent?: Schema.JsonObject | null
445 } | null
446 }
447
448 /**
449 * OpenAI-compatible metadata attached to document source citations.
450 *
451 * @stability unstable
452 * @category models
453 * @since 4.0.0
454 */
455 export interface DocumentSourcePartMetadata extends ProviderMetadata {
456 /**
457 * Provider-specific citation metadata for OpenAI-compatible APIs.
458 */
459 readonly "openai-compat"?:
460 | {
461 /**
462 * Identifies a citation to an uploaded file.
463 */
464 readonly type: "file_citation"
465 /**
466 * The index of the file in the list of files.
467 */
468 readonly index: number
469 /**
470 * The ID of the file.
471 */
472 readonly fileId: string
473 }
474 | {
475 /**
476 * Identifies a citation to a generated file path.
477 */
478 readonly type: "file_path"
479 /**
480 * The index of the file in the list of files.
481 */
482 readonly index: number
483 /**
484 * The ID of the file.
485 */
486 readonly fileId: string
487 }
488 | {
489 /**
490 * Identifies a citation to a file inside a container.
491 */
492 readonly type: "container_file_citation"
493 /**
494 * The ID of the file.
495 */
496 readonly fileId: string
497 /**
498 * The ID of the container file.
499 */
500 readonly containerId: string
501 }
502 | null
503 }
504
505 /**
506 * OpenAI-compatible metadata attached to URL source citations.
507 *
508 * @stability unstable
509 * @category models
510 * @since 4.0.0
511 */
512 export interface UrlSourcePartMetadata extends ProviderMetadata {
513 /**
514 * Provider-specific URL citation metadata for OpenAI-compatible APIs.
515 */
516 readonly "openai-compat"?: {
517 /**
518 * Identifies a citation to a URL.
519 */
520 readonly type: "url_citation"
521 /**
522 * The index of the first character of the URL citation in the message.
523 */
524 readonly startIndex: number
525 /**
526 * The index of the last character of the URL citation in the message.
527 */
528 readonly endIndex: number
529 } | null
530 }
531
532 /**
533 * OpenAI-compatible metadata attached to finish response parts.
534 *
535 * @stability unstable
536 * @category models
537 * @since 4.0.0
538 */
539 export interface FinishPartMetadata extends ProviderMetadata {
540 /**
541 * Provider-specific metadata returned when generation finishes.
542 */
543 readonly "openai-compat"?: {
544 /**
545 * The service tier reported by the OpenAI-compatible provider.
546 */
547 readonly serviceTier?: "default" | "auto" | "flex" | "scale" | "priority" | null
548 } | null
549 }
550 }
551
552 // =============================================================================
553 // Language Model
554 // =============================================================================
555
556 /**
557 * Creates an OpenAI-compatible model descriptor that can be provided with `Effect.provide`.
558 *
559 * **When to use**
560 *
561 * Use when you want an OpenAI-compatible language model value that carries
562 * provider and model metadata and can be supplied directly to an Effect program.
563 *
564 * @see {@link layer} for creating a `LanguageModel.LanguageModel` layer directly
565 * @see {@link make} for constructing the language model service effectfully
566 *
567 * @stability unstable
568 * @category constructors
569 * @since 4.0.0
570 */
571 export const model = (
572 model: string,
573 config?: ModelConfig
574 ): AiModel.Model<"openai", LanguageModel.LanguageModel, OpenAiClient> =>
575 AiModel.make("openai", model, layer({ model, config }))
576
577 // TODO
578 // /**
579 // * @since 4.0.0
580 // * @category constructors
581 // */
582 // export const modelWithTokenizer = (
583 // model: string,
584 // config?: Omit<typeof Config.Service, "model">
585 // ): AiModel.Model<"openai", LanguageModel.LanguageModel | Tokenizer.Tokenizer, OpenAiClient> =>
586 // AiModel.make("openai", model, layerWithTokenizer({ model, config }))
587
588 /**
589 * Creates an OpenAI-compatible `LanguageModel` service from a model identifier and optional request defaults.
590 *
591 * **When to use**
592 *
593 * Use to construct an OpenAI-compatible chat-completions language model service
594 * backed by `OpenAiClient`.
595 *
596 * **Details**
597 *
598 * The returned effect requires `OpenAiClient`. Request defaults from the
599 * `config` option are merged with any `Config` service in the context, with
600 * context values taking precedence. The service supports both `generateText` and
601 * `streamText`.
602 *
603 * @see {@link layer} for providing the service as a `Layer`
604 * @see {@link model} for creating a model descriptor for `AiModel.provide`
605 *
606 * @stability unstable
607 * @category constructors
608 * @since 4.0.0
609 */
610 export const make = Effect.fnUntraced(function*({ model, config: providerConfig }: {
611 readonly model: string
612 readonly config?: ModelConfig | undefined
613 }): Effect.fn.Return<LanguageModel.LanguageModel, never, OpenAiClient> {
614 const client = yield* OpenAiClient
615
616 const makeConfig = Effect.contextWith((services: Context.Context<never>) =>
617 Effect.succeed({ model, ...providerConfig, ...Context.getOrUndefined(services, Config) })
618 )
619
620 const makeRequest = Effect.fnUntraced(
621 function*<Tools extends ReadonlyArray<Tool.Any>>({ config, options, toolNameMapper }: {
622 readonly config: typeof Config.Service
623 readonly options: LanguageModel.ProviderOptions
624 readonly toolNameMapper: Tool.NameMapper<Tools>
625 }): Effect.fn.Return<{
626 readonly request: CreateResponseRequestJson
627 readonly toolCodecs: ToolCodecs
628 }, AiError.AiError> {
629 const messages = yield* prepareMessages({
630 config,
631 options,
632 toolNameMapper
633 })
634 const { toolChoice, toolCodecs, tools } = yield* prepareTools({
635 config,
636 options,
637 toolNameMapper
638 })
639 const responseFormat = yield* prepareResponseFormat({
640 config,
641 options
642 })
643 const { fileIdPrefixes: _fip, strictJsonSchema: _sjs, ...apiConfig } = config
644 const request: CreateResponse = {
645 ...apiConfig,
646 text: {
647 verbosity: config.text?.verbosity ?? null,
648 format: responseFormat
649 },
650 ...(tools !== undefined ? { tools } : undefined),
651 ...(toolChoice !== undefined ? { tool_choice: toolChoice } : undefined)
652 }
653 return { request: toChatCompletionsRequest(request, messages), toolCodecs }
654 }
655 )
656
657 return yield* LanguageModel.make({
658 codecTransformer: toCodecOpenAI,
659 generateText: Effect.fnUntraced(
660 function*(options) {
661 const config = yield* makeConfig
662 const toolNameMapper = new Tool.NameMapper(options.tools)
663 const { request, toolCodecs } = yield* makeRequest({ config, options, toolNameMapper })
664 annotateRequest(options.span, request)
665 const [rawResponse, response] = yield* client.createResponse(request)
666 annotateResponse(options.span, rawResponse)
667 return yield* makeResponse({
668 options,
669 rawResponse,
670 response,
671 toolNameMapper,
672 toolCodecs
673 })
674 }
675 ),
676 streamText: Effect.fnUntraced(
677 function*(options) {
678 const config = yield* makeConfig
679 const toolNameMapper = new Tool.NameMapper(options.tools)
680 const { request, toolCodecs } = yield* makeRequest({ config, options, toolNameMapper })
681 annotateRequest(options.span, request)
682 const [response, stream] = yield* client.createResponseStream(request)
683 return yield* makeStreamResponse({
684 options,
685 stream,
686 response,
687 toolNameMapper,
688 toolCodecs
689 })
690 },
691 (effect, options) =>
692 effect.pipe(
693 Stream.unwrap,
694 Stream.map((response) => {
695 annotateStreamResponse(options.span, response)
696 return response
697 })
698 )
699 )
700 })
701 })
702
703 /**
704 * Creates a layer for the OpenAI-compatible language model.
705 *
706 * **When to use**
707 *
708 * Use when composing application layers and you want OpenAI-compatible APIs to
709 * satisfy `LanguageModel.LanguageModel` while supplying `OpenAiClient` from
710 * another layer.
711 *
712 * @see {@link make} for constructing the language model service effectfully
713 * @see {@link model} for creating an AI model descriptor
714 *
715 * @stability unstable
716 * @category layers
717 * @since 4.0.0
718 */
719 export const layer = (options: {
720 readonly model: string
721 readonly config?: ModelConfig | undefined
722 }): Layer.Layer<LanguageModel.LanguageModel, never, OpenAiClient> =>
723 Layer.effect(LanguageModel.LanguageModel, make(options))
724
725 /**
726 * Provides scoped config overrides for OpenAI-compatible language model operations.
727 *
728 * **When to use**
729 *
730 * Use to override request configuration for a single language model effect
731 * without changing the defaults supplied to `model`, `make`, or `layer`.
732 *
733 * **Details**
734 *
735 * Existing `Config` values from the Effect context are merged with `overrides`,
736 * and the override values take precedence.
737 *
738 * @see {@link Config} for the configuration shape
739 *
740 * @stability unstable
741 * @category configuration
742 * @since 4.0.0
743 */
744 export const withConfigOverride: {
745 (overrides: typeof Config.Service): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>
746 <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service): Effect.Effect<A, E, Exclude<R, Config>>
747 } = dual<
748 (
749 overrides: typeof Config.Service
750 ) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>,
751 <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service) => Effect.Effect<A, E, Exclude<R, Config>>
752 >(2, (self, overrides) =>
753 Effect.flatMap(
754 Effect.serviceOption(Config),
755 (config) =>
756 Effect.provideService(self, Config, {
757 ...(config._tag === "Some" ? config.value : {}),
758 ...overrides
759 })
760 ))
761
762 // =============================================================================
763 // Prompt Conversion
764 // =============================================================================
765
766 const getSystemMessageMode = (model: string): "system" | "developer" =>
767 model.startsWith("o") ||
768 model.startsWith("gpt-5") ||
769 model.startsWith("codex-") ||
770 model.startsWith("computer-use")
771 ? "developer"
772 : "system"
773
774 const prepareMessages = Effect.fnUntraced(
775 function*<Tools extends ReadonlyArray<Tool.Any>>({
776 config,
777 options,
778 toolNameMapper
779 }: {
780 readonly config: typeof Config.Service
781 readonly options: LanguageModel.ProviderOptions
782 readonly toolNameMapper: Tool.NameMapper<Tools>
783 }): Effect.fn.Return<ReadonlyArray<ChatCompletionRequestMessage>, AiError.AiError> {
784 const messages: Array<ChatCompletionRequestMessage> = []
785
786 for (const message of options.prompt.content) {
787 switch (message.role) {
788 case "system": {
789 messages.push({
790 role: getSystemMessageMode(config.model!),
791 content: message.content
792 })
793 break
794 }
795
796 case "user": {
797 const content: Array<InputContent> = []
798
799 for (let index = 0; index < message.content.length; index++) {
800 const part = message.content[index]
801
802 switch (part.type) {
803 case "text": {
804 content.push({ type: "input_text", text: part.text })
805 break
806 }
807
808 case "file": {
809 if (part.mediaType.startsWith("image/")) {
810 const detail = getImageDetail(part)
811 const mediaType = part.mediaType === "image/*" ? "image/jpeg" : part.mediaType
812
813 if (typeof part.data === "string" && isFileId(part.data, config)) {
814 content.push({ type: "input_image", file_id: part.data, detail })
815 } else {
816 const imageUrl = part.data instanceof URL
817 ? part.data.toString()
818 : part.data instanceof Uint8Array
819 ? `data:${mediaType};base64,${Base64.encode(part.data)}`
820 : /^(data:|https?:\/\/)/i.test(part.data)
821 ? part.data
822 : `data:${mediaType};base64,${part.data}`
823 content.push({ type: "input_image", image_url: imageUrl, detail })
824 }
825 } else if (part.mediaType === "application/pdf") {
826 if (typeof part.data === "string" && isFileId(part.data, config)) {
827 content.push({ type: "input_file", file_id: part.data })
828 }
829
830 if (part.data instanceof URL) {
831 content.push({ type: "input_file", file_url: part.data.toString() })
832 }
833
834 if (part.data instanceof Uint8Array) {
835 const base64 = Base64.encode(part.data)
836 const fileName = part.fileName ?? `part-${index}.pdf`
837 const fileData = `data:application/pdf;base64,${base64}`
838 content.push({ type: "input_file", filename: fileName, file_data: fileData })
839 }
840 } else {
841 return yield* AiError.make({
842 module: "OpenAiLanguageModel",
843 method: "prepareMessages",
844 reason: new AiError.InvalidRequestError({
845 description: `Detected unsupported media type for file: '${part.mediaType}'`
846 })
847 })
848 }
849 }
850 }
851 }
852
853 messages.push({ role: "user", content: toChatMessageContent(content) })
854
855 break
856 }
857
858 case "assistant": {
859 let content: string | null = null
860 let reasoning = ""
861 let reasoningField: ReasoningField | undefined
862 const toolCalls: Array<ChatCompletionRequestToolCall> = []
863
864 for (const part of message.content) {
865 switch (part.type) {
866 case "text": {
867 content = (content ?? "") + part.text
868 break
869 }
870
871 case "reasoning": {
872 reasoning += part.text
873 reasoningField ??= part.options["openai-compat"]?.reasoningField ?? undefined
874 break
875 }
876
877 case "tool-call": {
878 if (part.providerExecuted) {
879 break
880 }
881
882 const extraContent = getExtraContent(part)
883
884 toolCalls.push({
885 id: part.id,
886 type: "function",
887 function: {
888 name: toolNameMapper.getProviderName(part.name),
889 arguments: JSON.stringify(part.params)
890 },
891 ...(Predicate.isNotNull(extraContent) ? { extra_content: extraContent } : undefined)
892 })
893 break
894 }
895 }
896 }
897
898 // Text, reasoning and tool calls from one prompt message are sent as a
899 // single chat message so reasoning stays attached to its tool calls
900 if (content !== null || toolCalls.length > 0) {
901 messages.push({
902 role: "assistant",
903 content,
904 ...(reasoning.length > 0 ? { [reasoningField ?? "reasoning_content"]: reasoning } : undefined),
905 ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : undefined)
906 })
907 }
908
909 break
910 }
911
912 case "tool": {
913 for (const part of message.content) {
914 if (part.type === "tool-approval-response") {
915 continue
916 }
917
918 messages.push({
919 role: "tool",
920 tool_call_id: part.id,
921 content: Predicate.isNotUndefined(part.modelOutput)
922 ? Prompt.toolModelOutputToText(part.modelOutput)
923 : typeof part.result === "string"
924 ? part.result
925 : JSON.stringify(part.result)
926 })
927 }
928
929 break
930 }
931 }
932 }
933
934 return messages
935 }
936 )
937
938 // =============================================================================
939 // HTTP Details
940 // =============================================================================
941
942 const buildHttpResponseDetails = (
943 response: HttpClientResponse.HttpClientResponse
944 ): typeof Response.HttpResponseDetails.Type => ({
945 status: response.status,
946 headers: Redactable.redact(response.headers) as Record<string, string>
947 })
948
949 // =============================================================================
950 // Response Conversion
951 // =============================================================================
952
953 type ResponseStreamEvent = CreateResponse200Sse
954
955 const isUnknownChatCompletionEvent = (
956 event: ResponseStreamEvent
957 ): event is UnknownChatCompletionEvent =>
958 typeof event !== "string" && "_tag" in event && event._tag === "UnknownChatCompletionEvent"
959
960 type ActiveToolCall = {
961 readonly id: string
962 name: string
963 arguments: string
964 extraContent: Schema.JsonObject | undefined
965 }
966
967 const makeResponse = Effect.fnUntraced(
968 function*<Tools extends ReadonlyArray<Tool.Any>>({
969 options,
970 rawResponse,
971 response,
972 toolNameMapper,
973 toolCodecs
974 }: {
975 readonly options: LanguageModel.ProviderOptions
976 readonly rawResponse: CreateResponse200
977 readonly response: HttpClientResponse.HttpClientResponse
978 readonly toolNameMapper: Tool.NameMapper<Tools>
979 readonly toolCodecs: ToolCodecs
980 }): Effect.fn.Return<
981 Array<Response.PartEncoded>,
982 AiError.AiError
983 > {
984 let hasToolCalls = false
985 const parts: Array<Response.PartEncoded> = []
986
987 const createdAt = new Date(rawResponse.created * 1000)
988 parts.push({
989 type: "response-metadata",
990 id: rawResponse.id,
991 modelId: rawResponse.model as string,
992 timestamp: DateTime.formatIso(DateTime.fromDateUnsafe(createdAt))
993 })
994
995 const choice = rawResponse.choices[0]
996 const message = choice?.message
997
998 if (message !== undefined) {
999 const reasoningField = getResponseReasoningField(message)
1000 const reasoning = reasoningField !== undefined ? message[reasoningField] : undefined
1001 if (reasoningField !== undefined && Predicate.isNotNullish(reasoning) && reasoning.length > 0) {
1002 parts.push({ type: "reasoning", text: reasoning, metadata: { "openai-compat": { reasoningField } } })
1003 }
1004
1005 if (
1006 message.content !== undefined && Predicate.isNotNull(message.content) && message.content.length > 0
1007 ) {
1008 parts.push({ type: "text", text: message.content })
1009 }
1010
1011 if (message.tool_calls !== undefined) {
1012 for (const [index, toolCall] of message.tool_calls.entries()) {
1013 const toolId = toolCall.id ?? `${rawResponse.id}_tool_${index}`
1014 const toolName = toolNameMapper.getCustomName(toolCall.function?.name ?? "unknown_tool")
1015 const toolParamsJson = toolCall.function?.arguments ?? "{}"
1016 const toolParams = yield* Effect.try({
1017 try: () => Tool.unsafeSecureJsonParse(toolParamsJson),
1018 catch: (cause) =>
1019 AiError.make({
1020 module: "OpenAiLanguageModel",
1021 method: "makeResponse",
1022 reason: new AiError.ToolParameterValidationError({
1023 toolName,
1024 description: `Failed to securely JSON parse tool parameters: ${cause}`
1025 })
1026 })
1027 })
1028 const params = yield* transformToolCallParams(options, toolName, toolParams, toolCodecs)
1029 hasToolCalls = true
1030 parts.push({
1031 type: "tool-call",
1032 id: toolId,
1033 name: toolName,
1034 params,
1035 metadata: {
1036 "openai-compat": {
1037 ...makeItemIdMetadata(toolCall.id),
1038 ...makeExtraContentMetadata(toolCall.extra_content ?? undefined)
1039 }
1040 }
1041 })
1042 }
1043 }
1044 }
1045
1046 const finishReason = InternalUtilities.resolveFinishReason(
1047 choice?.finish_reason,
1048 hasToolCalls
1049 )
1050 const serviceTier = normalizeServiceTier(rawResponse.service_tier)
1051
1052 parts.push({
1053 type: "finish",
1054 reason: finishReason,
1055 usage: getUsage(rawResponse.usage),
1056 response: buildHttpResponseDetails(response),
1057 ...(serviceTier !== undefined && { metadata: { "openai-compat": { serviceTier } } })
1058 })
1059
1060 return parts
1061 }
1062 )
1063
1064 const makeStreamResponse = Effect.fnUntraced(
1065 function*<Tools extends ReadonlyArray<Tool.Any>>({
1066 options,
1067 stream,
1068 response,
1069 toolNameMapper,
1070 toolCodecs
1071 }: {
1072 readonly options: LanguageModel.ProviderOptions
1073 readonly stream: Stream.Stream<ResponseStreamEvent, AiError.AiError>
1074 readonly response: HttpClientResponse.HttpClientResponse
1075 readonly toolNameMapper: Tool.NameMapper<Tools>
1076 readonly toolCodecs: ToolCodecs
1077 }): Effect.fn.Return<
1078 Stream.Stream<Response.StreamPartEncoded, AiError.AiError>,
1079 AiError.AiError
1080 > {
1081 let serviceTier: string | undefined = undefined
1082 let usage: CreateResponse200["usage"] = undefined
1083 let finishReason: string | null | undefined = undefined
1084 let metadataEmitted = false
1085 let textStarted = false
1086 let textId = ""
1087 let reasoningStarted = false
1088 let reasoningId = ""
1089 let hasToolCalls = false
1090 const activeToolCalls: Record<number, ActiveToolCall> = {}
1091
1092 return stream.pipe(
1093 Stream.mapEffect(Effect.fnUntraced(function*(event) {
1094 const parts: Array<Response.StreamPartEncoded> = []
1095
1096 if (event === "[DONE]") {
1097 if (reasoningStarted) {
1098 parts.push({
1099 type: "reasoning-end",
1100 id: reasoningId,
1101 metadata: { "openai-compat": { ...makeItemIdMetadata(reasoningId) } }
1102 })
1103 }
1104
1105 if (textStarted) {
1106 parts.push({
1107 type: "text-end",
1108 id: textId,
1109 metadata: { "openai-compat": { ...makeItemIdMetadata(textId) } }
1110 })
1111 }
1112
1113 for (const toolCall of Object.values(activeToolCalls)) {
1114 const toolParams = toolCall.arguments.length > 0 ? toolCall.arguments : "{}"
1115 const parsedParams = yield* Effect.try({
1116 try: () => Tool.unsafeSecureJsonParse(toolParams),
1117 catch: (cause) =>
1118 AiError.make({
1119 module: "OpenAiLanguageModel",
1120 method: "makeStreamResponse",
1121 reason: new AiError.ToolParameterValidationError({
1122 toolName: toolCall.name,
1123 description: `Failed to securely JSON parse tool parameters: ${cause}`
1124 })
1125 })
1126 })
1127 const params = yield* transformToolCallParams(options, toolCall.name, parsedParams, toolCodecs)
1128 parts.push({ type: "tool-params-end", id: toolCall.id })
1129 parts.push({
1130 type: "tool-call",
1131 id: toolCall.id,
1132 name: toolCall.name,
1133 params,
1134 metadata: {
1135 "openai-compat": {
1136 ...makeItemIdMetadata(toolCall.id),
1137 ...makeExtraContentMetadata(toolCall.extraContent)
1138 }
1139 }
1140 })
1141 hasToolCalls = true
1142 }
1143
1144 const normalizedServiceTier = normalizeServiceTier(serviceTier)
1145 parts.push({
1146 type: "finish",
1147 reason: InternalUtilities.resolveFinishReason(finishReason, hasToolCalls),
1148 usage: getUsage(usage),
1149 response: buildHttpResponseDetails(response),
1150 ...(normalizedServiceTier !== undefined
1151 ? { metadata: { "openai-compat": { serviceTier: normalizedServiceTier } } }
1152 : undefined)
1153 })
1154 return parts
1155 }
1156
1157 // Keep unknown events available to direct client consumers; this layer
1158 // cannot translate provider-specific data into portable stream parts.
1159 if (isUnknownChatCompletionEvent(event)) {
1160 return parts
1161 }
1162
1163 if (event.service_tier !== undefined) {
1164 serviceTier = event.service_tier
1165 }
1166 if (event.usage !== undefined && Predicate.isNotNull(event.usage)) {
1167 usage = event.usage
1168 }
1169
1170 if (!metadataEmitted) {
1171 metadataEmitted = true
1172 textId = `${event.id}_message`
1173 reasoningId = `${event.id}_reasoning`
1174 parts.push({
1175 type: "response-metadata",
1176 id: event.id,
1177 modelId: event.model,
1178 timestamp: DateTime.formatIso(DateTime.fromDateUnsafe(new Date(event.created * 1000)))
1179 })
1180 }
1181
1182 const choice = event.choices[0]
1183 if (Predicate.isUndefined(choice)) {
1184 return parts
1185 }
1186
1187 const reasoningField = Predicate.isNotNullish(choice.delta)
1188 ? getResponseReasoningField(choice.delta)
1189 : undefined
1190 const reasoningDelta = reasoningField !== undefined ? choice.delta?.[reasoningField] : undefined
1191 if (reasoningField !== undefined && Predicate.isNotNullish(reasoningDelta) && reasoningDelta.length > 0) {
1192 if (!reasoningStarted) {
1193 reasoningStarted = true
1194 parts.push({
1195 type: "reasoning-start",
1196 id: reasoningId,
1197 metadata: { "openai-compat": { ...makeItemIdMetadata(reasoningId), reasoningField } }
1198 })
1199 }
1200 parts.push({ type: "reasoning-delta", id: reasoningId, delta: reasoningDelta })
1201 }
1202
1203 if (Predicate.isNotNullish(choice.delta?.content) && choice.delta.content.length > 0) {
1204 if (reasoningStarted) {
1205 reasoningStarted = false
1206 parts.push({
1207 type: "reasoning-end",
1208 id: reasoningId,
1209 metadata: { "openai-compat": { ...makeItemIdMetadata(reasoningId) } }
1210 })
1211 }
1212
1213 if (!textStarted) {
1214 textStarted = true
1215 parts.push({
1216 type: "text-start",
1217 id: textId,
1218 metadata: { "openai-compat": { ...makeItemIdMetadata(textId) } }
1219 })
1220 }
1221 parts.push({ type: "text-delta", id: textId, delta: choice.delta.content })
1222 }
1223
1224 if (Predicate.isNotNullish(choice.delta?.tool_calls)) {
1225 hasToolCalls = hasToolCalls || choice.delta.tool_calls.length > 0
1226 choice.delta.tool_calls.forEach((deltaTool, indexInChunk) => {
1227 const toolIndex = deltaTool.index ?? indexInChunk
1228 const activeToolCall = activeToolCalls[toolIndex]
1229 const toolId = activeToolCall?.id ?? deltaTool.id ?? `${event.id}_tool_${toolIndex}`
1230 const providerToolName = deltaTool.function?.name
1231 const toolName = Predicate.isNotNullish(providerToolName)
1232 ? toolNameMapper.getCustomName(providerToolName)
1233 : activeToolCall?.name ?? toolNameMapper.getCustomName("unknown_tool")
1234 const argumentsDelta = deltaTool.function?.arguments ?? ""
1235
1236 if (Predicate.isUndefined(activeToolCall)) {
1237 activeToolCalls[toolIndex] = {
1238 id: toolId,
1239 name: toolName,
1240 arguments: argumentsDelta,
1241 extraContent: deltaTool.extra_content ?? undefined
1242 }
1243 parts.push({ type: "tool-params-start", id: toolId, name: toolName })
1244 } else {
1245 activeToolCall.name = toolName
1246 activeToolCall.arguments = `${activeToolCall.arguments}${argumentsDelta}`
1247 if (Predicate.isNotNullish(deltaTool.extra_content)) {
1248 activeToolCall.extraContent = deltaTool.extra_content
1249 }
1250 }
1251
1252 if (argumentsDelta.length > 0) {
1253 parts.push({ type: "tool-params-delta", id: toolId, delta: argumentsDelta })
1254 }
1255 })
1256 }
1257
1258 if (choice.finish_reason !== undefined && Predicate.isNotNull(choice.finish_reason)) {
1259 finishReason = choice.finish_reason
1260 }
1261
1262 return parts
1263 })),
1264 Stream.filter(Arr.isArrayNonEmpty),
1265 Stream.flattenArray
1266 )
1267 }
1268 )
1269
1270 // =============================================================================
1271 // Telemetry
1272 // =============================================================================
1273
1274 const annotateRequest = (
1275 span: Span,
1276 request: CreateResponseRequestJson
1277 ): void => {
1278 addGenAIAnnotations(span, {
1279 provider: { name: "openai" },
1280 operation: { name: "chat" },
1281 request: {
1282 model: request.model as string,
1283 temperature: request.temperature as number | undefined,
1284 topP: request.top_p as number | undefined,
1285 maxTokens: request.max_tokens as number | undefined
1286 },
1287 openai: {
1288 request: {
1289 serviceTier: request.service_tier as string | undefined
1290 }
1291 }
1292 })
1293 }
1294
1295 const annotateResponse = (span: Span, response: CreateResponse200): void => {
1296 const finishReason = response.choices[0]?.finish_reason ?? undefined
1297 addGenAIAnnotations(span, {
1298 response: {
1299 id: response.id,
1300 model: response.model as string,
1301 finishReasons: finishReason !== undefined ? [finishReason] : undefined
1302 },
1303 usage: {
1304 inputTokens: response.usage?.prompt_tokens,
1305 outputTokens: response.usage?.completion_tokens
1306 },
1307 openai: {
1308 response: {
1309 serviceTier: response.service_tier as string | undefined
1310 }
1311 }
1312 })
1313 }
1314
1315 const annotateStreamResponse = (span: Span, part: Response.StreamPartEncoded) => {
1316 if (part.type === "response-metadata") {
1317 addGenAIAnnotations(span, {
1318 response: {
1319 id: part.id,
1320 model: part.modelId
1321 }
1322 })
1323 }
1324 if (part.type === "finish") {
1325 const serviceTier = (part.metadata as any)?.["openai-compat"]?.serviceTier as string | undefined
1326 addGenAIAnnotations(span, {
1327 response: {
1328 finishReasons: [part.reason]
1329 },
1330 usage: {
1331 inputTokens: part.usage.inputTokens.total,
1332 outputTokens: part.usage.outputTokens.total
1333 },
1334 openai: {
1335 response: { serviceTier }
1336 }
1337 })
1338 }
1339 }
1340
1341 // =============================================================================
1342 // Tool Conversion
1343 // =============================================================================
1344
1345 type OpenAiToolChoice = CreateResponse["tool_choice"]
1346
1347 const unsupportedSchemaError = (error: unknown, method: string): AiError.AiError =>
1348 AiError.make({
1349 module: "OpenAiLanguageModel",
1350 method,
1351 reason: new AiError.UnsupportedSchemaError({
1352 description: error instanceof Error ? error.message : String(error)
1353 })
1354 })
1355
1356 const tryCodecTransform = <S extends Schema.Constraint>(schema: S, method: string) =>
1357 Effect.try({
1358 try: () => toCodecOpenAI(schema),
1359 catch: (error) => unsupportedSchemaError(error, method)
1360 })
1361
1362 const tryJsonSchema = <S extends Schema.Constraint>(schema: S, method: string) =>
1363 Effect.try({
1364 try: () => Tool.getJsonSchemaFromSchema(schema, { transformer: toCodecOpenAI }),
1365 catch: (error) => unsupportedSchemaError(error, method)
1366 })
1367
1368 const toolParametersError = (tool: Tool.Any, error: unknown, method: string): AiError.AiError =>
1369 unsupportedSchemaError(
1370 `Tool "${tool.name}" parameters: ${error instanceof Error ? error.message : String(error)}. ` +
1371 "For a tool without parameters, omit `parameters` or use `Tool.EmptyParams`",
1372 method
1373 )
1374
1375 type ToolCodec = ReturnType<typeof toCodecOpenAI>["codec"]
1376 type ToolCodecs = ReadonlyMap<Tool.Any, ToolCodec>
1377
1378 const transformToolCallParams = Effect.fnUntraced(function*(
1379 options: LanguageModel.ProviderOptions,
1380 toolName: string,
1381 toolParams: unknown,
1382 toolCodecs: ToolCodecs
1383 ): Effect.fn.Return<unknown, AiError.AiError> {
1384 const tool = options.tools.find((tool) => tool.name === toolName)
1385
1386 if (Predicate.isUndefined(tool)) {
1387 if (options.toolCallValidation === "deferred") {
1388 return toolParams
1389 }
1390 return yield* AiError.make({
1391 module: "OpenAiLanguageModel",
1392 method: "makeResponse",
1393 reason: new AiError.ToolNotFoundError({
1394 toolName,
1395 availableTools: options.tools.map((tool) => tool.name)
1396 })
1397 })
1398 }
1399
1400 if (Tool.isDynamic(tool) && tool.jsonSchema !== undefined) {
1401 return toolParams
1402 }
1403
1404 const codec = toolCodecs.get(tool) ?? (yield* tryCodecTransform(tool.parametersSchema, "makeResponse")).codec
1405
1406 // Normalize valid parameters; leave invalid ones for Toolkit.
1407 return yield* (
1408 Schema.decodeEffect(codec)(toolParams) as Effect.Effect<unknown, Schema.SchemaError>
1409 ).pipe(
1410 Effect.flatMap((decoded) =>
1411 Schema.encodeUnknownEffect(tool.parametersSchema)(decoded) as Effect.Effect<unknown, Schema.SchemaError>
1412 ),
1413 Effect.orElseSucceed(() => toolParams)
1414 )
1415 })
1416
1417 const prepareTools = Effect.fnUntraced(function*<Tools extends ReadonlyArray<Tool.Any>>({
1418 config,
1419 options,
1420 toolNameMapper
1421 }: {
1422 readonly config: typeof Config.Service
1423 readonly options: LanguageModel.ProviderOptions
1424 readonly toolNameMapper: Tool.NameMapper<Tools>
1425 }): Effect.fn.Return<{
1426 readonly tools: ReadonlyArray<OpenAiClientTool> | undefined
1427 readonly toolChoice: OpenAiToolChoice | undefined
1428 readonly toolCodecs: ToolCodecs
1429 }, AiError.AiError> {
1430 const toolCodecs = new Map<Tool.Any, ToolCodec>()
1431
1432 // Return immediately if no tools are in the toolkit
1433 if (options.tools.length === 0) {
1434 return { tools: undefined, toolChoice: undefined, toolCodecs }
1435 }
1436
1437 const tools: Array<OpenAiClientTool> = []
1438 let toolChoice: OpenAiToolChoice | undefined = undefined
1439
1440 // Filter the incoming tools down to the set of allowed tools as indicated by
1441 // the tool choice. This must be done here given that there is no tool name
1442 // in OpenAI's provider-defined tools, so there would be no way to perform
1443 // this filter otherwise
1444 let allowedTools = options.tools
1445 if (typeof options.toolChoice === "object" && "oneOf" in options.toolChoice) {
1446 const allowedToolNames = new Set(options.toolChoice.oneOf)
1447 allowedTools = options.tools.filter((tool) => allowedToolNames.has(tool.name))
1448 toolChoice = options.toolChoice.mode === "required" ? "required" : "auto"
1449 }
1450
1451 // Convert the tools in the toolkit to the provider-defined format
1452 for (const tool of allowedTools) {
1453 if (Tool.isUserDefined(tool) || Tool.isDynamic(tool)) {
1454 const strict = Tool.getStrictMode(tool) ?? config.strictJsonSchema ?? true
1455 let parameters: ReturnType<typeof Tool.getJsonSchema>
1456 if (Tool.isDynamic(tool) && tool.jsonSchema !== undefined) {
1457 parameters = tool.jsonSchema
1458 } else {
1459 const prepared = yield* Effect.try({
1460 try: () => toCodecOpenAI(tool.parametersSchema),
1461 catch: (error) => toolParametersError(tool, error, "prepareTools")
1462 })
1463 parameters = prepared.jsonSchema
1464 // Reused to normalize this tool's calls in the response.
1465 toolCodecs.set(tool, prepared.codec)
1466 }
1467 tools.push({
1468 type: "function",
1469 name: tool.name,
1470 description: Tool.getDescription(tool) ?? null,
1471 parameters: parameters as { readonly [x: string]: Schema.Json },
1472 strict
1473 })
1474 }
1475
1476 if (Tool.isProviderDefined(tool)) {
1477 tools.push({
1478 type: "function",
1479 name: tool.providerName,
1480 description: Tool.getDescription(tool) ?? null,
1481 parameters: Tool.getJsonSchema(tool) as { readonly [x: string]: Schema.Json },
1482 strict: config.strictJsonSchema ?? true
1483 })
1484 }
1485 }
1486
1487 if (options.toolChoice === "auto" || options.toolChoice === "none" || options.toolChoice === "required") {
1488 toolChoice = options.toolChoice
1489 }
1490
1491 if (typeof options.toolChoice === "object" && "tool" in options.toolChoice) {
1492 const toolName = toolNameMapper.getProviderName(options.toolChoice.tool)
1493 const providerNames = toolNameMapper.providerNames
1494 if (providerNames.includes(toolName)) {
1495 toolChoice = { type: "function", name: toolName }
1496 } else {
1497 toolChoice = { type: "function", name: options.toolChoice.tool }
1498 }
1499 }
1500
1501 return { tools, toolChoice, toolCodecs }
1502 })
1503
1504 const toChatCompletionsRequest = (
1505 payload: CreateResponse,
1506 messages: ReadonlyArray<ChatCompletionRequestMessage>
1507 ): CreateResponseRequestJson => {
1508 const responseFormat = toChatResponseFormat(payload.text?.format)
1509 const tools = payload.tools !== undefined
1510 ? payload.tools.map(toChatTool).filter((tool): tool is NonNullable<ReturnType<typeof toChatTool>> =>
1511 tool !== undefined
1512 )
1513 : []
1514 const toolChoice = toChatToolChoice(payload.tool_choice)
1515
1516 return {
1517 ...extractCustomRequestProperties(payload),
1518 model: payload.model ?? "",
1519 messages: messages.length > 0 ? messages : [{ role: "user", content: "" }],
1520 ...(payload.temperature !== undefined ? { temperature: payload.temperature } : undefined),
1521 ...(payload.top_p !== undefined ? { top_p: payload.top_p } : undefined),
1522 ...(payload.max_output_tokens !== undefined ? { max_tokens: payload.max_output_tokens } : undefined),
1523 ...(payload.user !== undefined ? { user: payload.user } : undefined),
1524 ...(payload.seed !== undefined ? { seed: payload.seed } : undefined),
1525 ...(payload.parallel_tool_calls !== undefined
1526 ? { parallel_tool_calls: payload.parallel_tool_calls }
1527 : undefined),
1528 ...(payload.service_tier !== undefined ? { service_tier: payload.service_tier } : undefined),
1529 ...(payload.reasoning !== undefined ? { reasoning: payload.reasoning } : undefined),
1530 ...(responseFormat !== undefined ? { response_format: responseFormat } : undefined),
1531 ...(tools.length > 0 ? { tools } : undefined),
1532 ...(toolChoice !== undefined ? { tool_choice: toolChoice } : undefined)
1533 }
1534 }
1535
1536 const createResponseKnownProperties = new Set<string>([
1537 "metadata",
1538 "top_logprobs",
1539 "temperature",
1540 "top_p",
1541 "user",
1542 "safety_identifier",
1543 "prompt_cache_key",
1544 "service_tier",
1545 "prompt_cache_retention",
1546 "previous_response_id",
1547 "model",
1548 "reasoning",
1549 "background",
1550 "max_output_tokens",
1551 "max_tool_calls",
1552 "text",
1553 "tools",
1554 "tool_choice",
1555 "truncation",
1556 "input",
1557 "include",
1558 "parallel_tool_calls",
1559 "store",
1560 "instructions",
1561 "stream",
1562 "conversation",
1563 "modalities",
1564 "seed"
1565 ])
1566
1567 const extractCustomRequestProperties = (payload: CreateResponse): Record<string, unknown> => {
1568 const customProperties: Record<string, unknown> = {}
1569 for (const [key, value] of Object.entries(payload)) {
1570 if (!createResponseKnownProperties.has(key)) {
1571 Rec.assignProperty(customProperties, key, value)
1572 }
1573 }
1574 return customProperties
1575 }
1576
1577 const toChatResponseFormat = (
1578 format: TextResponseFormatConfiguration | undefined
1579 ): CreateResponseRequestJson["response_format"] | undefined => {
1580 if (Predicate.isUndefined(format) || Predicate.isNull(format)) {
1581 return undefined
1582 }
1583
1584 switch (format.type) {
1585 case "json_object": {
1586 return { type: "json_object" }
1587 }
1588 case "json_schema": {
1589 return {
1590 type: "json_schema",
1591 json_schema: {
1592 name: format.name,
1593 schema: format.schema,
1594 ...(format.description !== undefined ? { description: format.description } : undefined),
1595 ...(Predicate.isNotNullish(format.strict) ? { strict: format.strict } : undefined)
1596 }
1597 }
1598 }
1599 default: {
1600 return undefined
1601 }
1602 }
1603 }
1604
1605 const toChatToolChoice = (
1606 toolChoice: OpenAiToolChoice
1607 ): CreateResponseRequestJson["tool_choice"] | undefined => {
1608 if (Predicate.isUndefined(toolChoice)) {
1609 return undefined
1610 }
1611
1612 if (typeof toolChoice === "string") {
1613 return toolChoice
1614 }
1615
1616 if (toolChoice.type === "allowed_tools") {
1617 return toolChoice.mode
1618 }
1619
1620 if (toolChoice.type === "function") {
1621 return {
1622 type: "function",
1623 function: {
1624 name: toolChoice.name
1625 }
1626 }
1627 }
1628
1629 const functionName = Predicate.hasProperty(toolChoice, "name") && typeof toolChoice.name === "string"
1630 ? toolChoice.name
1631 : toolChoice.type
1632
1633 return {
1634 type: "function",
1635 function: {
1636 name: functionName
1637 }
1638 }
1639 }
1640
1641 const toChatTool = (
1642 tool: OpenAiClientTool
1643 ): NonNullable<CreateResponseRequestJson["tools"]>[number] | undefined => {
1644 if (tool.type === "function") {
1645 return {
1646 type: "function",
1647 function: {
1648 name: tool.name,
1649 ...(tool.description !== undefined ? { description: tool.description } : undefined),
1650 ...(Predicate.isNotNullish(tool.parameters) ? { parameters: tool.parameters } : undefined),
1651 ...(Predicate.isNotNullish(tool.strict) ? { strict: tool.strict } : undefined)
1652 }
1653 }
1654 }
1655
1656 if (tool.type === "custom") {
1657 return {
1658 type: "function",
1659 function: {
1660 name: tool.name,
1661 parameters: { type: "object", additionalProperties: true }
1662 }
1663 }
1664 }
1665
1666 return undefined
1667 }
1668
1669 const toChatMessageContent = (
1670 content: string | ReadonlyArray<InputContent>
1671 ): string | ReadonlyArray<ChatCompletionContentPart> => {
1672 if (typeof content === "string") {
1673 return content
1674 }
1675
1676 if (content.length === 1 && content[0].type === "input_text") {
1677 return content[0].text
1678 }
1679
1680 const parts: Array<ChatCompletionContentPart> = []
1681
1682 for (const part of content) {
1683 switch (part.type) {
1684 case "input_text": {
1685 parts.push({ type: "text", text: part.text })
1686 break
1687 }
1688 case "input_image": {
1689 const imageUrl = part.image_url !== undefined
1690 ? part.image_url
1691 : part.file_id !== undefined
1692 ? `openai://file/${part.file_id}`
1693 : undefined
1694
1695 if (imageUrl !== undefined && Predicate.isNotNull(imageUrl)) {
1696 parts.push({
1697 type: "image_url",
1698 image_url: {
1699 url: imageUrl,
1700 ...(Predicate.isNotNullish(part.detail) ? { detail: part.detail } : undefined)
1701 }
1702 })
1703 }
1704 break
1705 }
1706 case "input_file": {
1707 if (part.file_url !== undefined) {
1708 parts.push({ type: "text", text: part.file_url })
1709 } else if (part.file_data !== undefined) {
1710 parts.push({ type: "text", text: part.file_data })
1711 } else if (part.file_id !== undefined) {
1712 parts.push({ type: "text", text: `openai://file/${part.file_id}` })
1713 }
1714 break
1715 }
1716 }
1717 }
1718
1719 if (parts.length === 0) {
1720 return ""
1721 }
1722
1723 if (parts.every((part) => part.type === "text")) {
1724 return parts.map((part) => part.text).join("\n")
1725 }
1726
1727 return parts
1728 }
1729
1730 // =============================================================================
1731 // Utilities
1732 // =============================================================================
1733
1734 const isFileId = (data: string, config: typeof Config.Service): boolean =>
1735 config.fileIdPrefixes != null && config.fileIdPrefixes.some((prefix) => data.startsWith(prefix))
1736
1737 const getExtraContent = (
1738 part: Prompt.ToolCallPart
1739 ): Schema.JsonObject | null => part.options["openai-compat"]?.extraContent ?? null
1740
1741 /**
1742 * The chat message field carrying reasoning text. Providers differ: DeepSeek,
1743 * Kimi and GLM use `reasoning_content`, while Groq uses `reasoning` and
1744 * rejects `reasoning_content` on request messages.
1745 */
1746 type ReasoningField = "reasoning" | "reasoning_content"
1747
1748 const getResponseReasoningField = (message: {
1749 readonly reasoning?: string | null | undefined
1750 readonly reasoning_content?: string | null | undefined
1751 }): ReasoningField | undefined =>
1752 Predicate.isNotNullish(message.reasoning)
1753 ? "reasoning"
1754 : Predicate.isNotNullish(message.reasoning_content)
1755 ? "reasoning_content"
1756 : undefined
1757
1758 const getImageDetail = (part: Prompt.FilePart): ImageDetail => part.options["openai-compat"]?.imageDetail ?? "auto"
1759
1760 const makeItemIdMetadata = (itemId: string | undefined) => itemId !== undefined ? { itemId } : undefined
1761
1762 const makeExtraContentMetadata = (extraContent: Schema.JsonObject | undefined) =>
1763 extraContent !== undefined ? { extraContent } : undefined
1764
1765 const normalizeServiceTier = (
1766 serviceTier: string | undefined
1767 ): "default" | "auto" | "flex" | "scale" | "priority" | null | undefined => {
1768 switch (serviceTier) {
1769 case undefined:
1770 return undefined
1771 case "default":
1772 case "auto":
1773 case "flex":
1774 case "scale":
1775 case "priority":
1776 return serviceTier
1777 default:
1778 return null
1779 }
1780 }
1781
1782 const prepareResponseFormat = Effect.fnUntraced(function*({ config, options }: {
1783 readonly config: typeof Config.Service
1784 readonly options: LanguageModel.ProviderOptions
1785 }): Effect.fn.Return<TextResponseFormatConfiguration, AiError.AiError> {
1786 if (options.responseFormat.type === "json") {
1787 const name = options.responseFormat.objectName
1788 const schema = options.responseFormat.schema
1789 const jsonSchema = yield* tryJsonSchema(schema, "prepareResponseFormat")
1790 return {
1791 type: "json_schema",
1792 name,
1793 description: AST.resolveDescription(schema.ast) ?? "Response with a JSON object",
1794 schema: jsonSchema as any,
1795 strict: config.strictJsonSchema ?? true
1796 }
1797 }
1798 return { type: "text" }
1799 })
1800
1801 const getUsage = (usage: CreateResponse200["usage"]): Response.Usage => {
1802 if (Predicate.isNullish(usage)) {
1803 return {
1804 inputTokens: {
1805 uncached: undefined,
1806 total: undefined,
1807 cacheRead: undefined,
1808 cacheWrite: undefined
1809 },
1810 outputTokens: {
1811 total: undefined,
1812 text: undefined,
1813 reasoning: undefined
1814 }
1815 }
1816 }
1817
1818 const inputTokens = usage.prompt_tokens
1819 const outputTokens = usage.completion_tokens
1820 const cachedTokens = getUsageDetailNumber(usage.prompt_tokens_details, "cached_tokens") ?? 0
1821 const reasoningTokens = getUsageDetailNumber(usage.completion_tokens_details, "reasoning_tokens") ?? 0
1822
1823 return {
1824 inputTokens: {
1825 uncached: inputTokens - cachedTokens,
1826 total: inputTokens,
1827 cacheRead: cachedTokens,
1828 cacheWrite: undefined
1829 },
1830 outputTokens: {
1831 total: outputTokens,
1832 text: outputTokens - reasoningTokens,
1833 reasoning: reasoningTokens
1834 }
1835 }
1836 }
1837
1838 const getUsageDetailNumber = (
1839 details: unknown,
1840 field: string
1841 ): number | undefined => {
1842 if (typeof details !== "object" || details === null) {
1843 return undefined
1844 }
1845
1846 const value = (details as Record<string, unknown>)[field]
1847 return typeof value === "number" ? value : undefined
1848 }