sailfork / t3code-github / .repos/ effect/ packages/ ai/ openai-compat/ src/ OpenAiLanguageModel.ts

/**
 * The `OpenAiLanguageModel` module adapts OpenAI-compatible chat completions
 * providers to Effect AI's `LanguageModel` service. It builds a model service
 * from a model id, translates prompts, files, tools, structured output schemas,
 * and provider-specific options into `OpenAiClient` requests, and maps normal
 * or streaming chat completion results back into Effect AI response content and
 * metadata.
 *
 * @stability unstable
 * @since 4.0.0
 */
import * as AiError from "effect/ai/AiError"
import * as LanguageModel from "effect/ai/LanguageModel"
import * as AiModel from "effect/ai/Model"
import { toCodecOpenAI } from "effect/ai/OpenAiStructuredOutput"
import * as Prompt from "effect/ai/Prompt"
import type * as Response from "effect/ai/Response"
import * as Tool from "effect/ai/Tool"
import * as Arr from "effect/Array"
import * as Context from "effect/Context"
import * as DateTime from "effect/DateTime"
import * as Effect from "effect/Effect"
import * as Base64 from "effect/encoding/Base64"
import { dual } from "effect/Function"
import type * as HttpClientResponse from "effect/http/HttpClientResponse"
import * as Layer from "effect/Layer"
import * as Predicate from "effect/Predicate"
import * as Rec from "effect/Record"
import * as Redactable from "effect/Redactable"
import * as Schema from "effect/Schema"
import * as AST from "effect/SchemaAST"
import * as Stream from "effect/Stream"
import type { Span } from "effect/Tracer"
import type { Simplify } from "effect/Types"
import * as InternalUtilities from "./internal/utilities.ts"
import {
  type Annotation,
  type ChatCompletionContentPart,
  type ChatCompletionRequestMessage,
  type ChatCompletionRequestToolCall,
  type CreateResponse,
  type CreateResponse200,
  type CreateResponse200Sse,
  type CreateResponseRequestJson,
  type InputContent,
  type MessageStatus,
  OpenAiClient,
  type TextResponseFormatConfiguration,
  type Tool as OpenAiClientTool,
  type UnknownChatCompletionEvent
} from "./OpenAiClient.ts"
import { addGenAIAnnotations } from "./OpenAiTelemetry.ts"

/**
 * Image detail level for vision requests.
 */
type ImageDetail = "auto" | "low" | "high"

// =============================================================================
// Configuration
// =============================================================================

type ConfigOptions = Simplify<
  & Partial<
    Omit<CreateResponse, "input" | "tools" | "tool_choice" | "stream" | "text" | "store" | "conversation">
  >
  & {
    /**
     * File ID prefixes used to identify file IDs in Responses API.
     * When undefined, all file data is treated as base64 content.
     *
     * Examples:
     * - OpenAI: ['file-'] for IDs like 'file-abc123'
     * - Azure OpenAI: ['assistant-'] for IDs like 'assistant-abc123'
     */
    readonly fileIdPrefixes?: ReadonlyArray<string> | undefined
    /**
     * Configuration options for a text response from the model.
     */
    readonly text?: {
      /**
       * Constrains the verbosity of the model's response. Lower values will
       * result in more concise responses, while higher values will result in
       * more verbose responses.
       *
       * Defaults to `"medium"`.
       */
      readonly verbosity?: "low" | "medium" | "high" | undefined
    } | undefined
    /**
     * Whether to use strict JSON schema validation.
     *
     * Defaults to `true`.
     */
    readonly strictJsonSchema?: boolean | undefined
  }
>
type ModelConfig = Omit<ConfigOptions, "model"> & { readonly [x: string]: unknown }

/**
 * Context service for OpenAI language model configuration.
 *
 * **When to use**
 *
 * Use as the context service for OpenAI-compatible language model request
 * configuration, especially when a scoped operation should override the defaults
 * supplied to `model`, `make`, or `layer`.
 *
 * @see {@link withConfigOverride} for scoping language model request overrides
 *
 * @stability unstable
 * @category services
 * @since 4.0.0
 */
export class Config extends Context.Service<
  Config,
  ConfigOptions & { readonly [x: string]: unknown }
>()("@effect/ai-openai-compat/OpenAiLanguageModel/Config") {}

// =============================================================================
// Provider Options / Metadata
// =============================================================================

declare module "effect/ai/Prompt" {
  /**
   * OpenAI-compatible options for file prompt parts.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface FilePartOptions extends ProviderOptions {
    /**
     * Provider-specific file options for OpenAI-compatible APIs.
     */
    readonly "openai-compat"?: {
      /**
       * The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`.
       */
      readonly imageDetail?: ImageDetail | null
    } | null
  }

  /**
   * OpenAI-compatible options for reasoning prompt parts.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ReasoningPartOptions extends ProviderOptions {
    /**
     * Provider-specific reasoning options for OpenAI-compatible APIs.
     */
    readonly "openai-compat"?: {
      /**
       * The ID of the item to reference.
       */
      readonly itemId?: string | null
      /**
       * The encrypted content of the reasoning item - populated when a response
       * is generated with `reasoning.encrypted_content` in the `include`
       * parameter.
       */
      readonly encryptedContent?: string | null
      /**
       * The chat message field the reasoning was returned under. Replayed
       * reasoning is sent back under the same field, defaulting to
       * `reasoning_content`.
       */
      readonly reasoningField?: "reasoning" | "reasoning_content" | null
    } | null
  }

  /**
   * OpenAI-compatible options for assistant tool-call prompt parts.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ToolCallPartOptions extends ProviderOptions {
    /**
     * Provider-specific tool-call options for OpenAI-compatible APIs.
     */
    readonly "openai-compat"?: {
      /**
       * The ID of the item to reference.
       */
      readonly itemId?: string | null
      /**
       * The status to send for the tool-call item.
       */
      readonly status?: MessageStatus | null
      /**
       * Provider-specific extra content to echo back with the tool call.
       */
      readonly extraContent?: Schema.JsonObject | null
    } | null
  }

  /**
   * OpenAI-compatible options for tool-result prompt parts.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ToolResultPartOptions extends ProviderOptions {
    /**
     * Provider-specific tool-result options for OpenAI-compatible APIs.
     */
    readonly "openai-compat"?: {
      /**
       * The ID of the item to reference.
       */
      readonly itemId?: string | null
      /**
       * The status to send for the tool-result item.
       */
      readonly status?: MessageStatus | null
    } | null
  }

  /**
   * OpenAI-compatible options for text prompt parts.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface TextPartOptions extends ProviderOptions {
    /**
     * Provider-specific text options for OpenAI-compatible APIs.
     */
    readonly "openai-compat"?: {
      /**
       * The ID of the item to reference.
       */
      readonly itemId?: string | null
      /**
       * The status to send for the text item.
       */
      readonly status?: MessageStatus | null
      /**
       * A list of annotations that apply to the output text.
       */
      readonly annotations?: ReadonlyArray<Annotation> | null
    } | null
  }
}

declare module "effect/ai/Response" {
  /**
   * OpenAI-compatible metadata attached to a complete text response part.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface TextPartMetadata extends ProviderMetadata {
    /**
     * Provider-specific metadata returned for the text part.
     */
    readonly "openai-compat"?: {
      /**
       * The OpenAI item ID associated with the text part.
       */
      readonly itemId?: string | null
      /**
       * If the model emits a refusal content part, the refusal explanation
       * from the model will be contained in the metadata of an empty text
       * part.
       */
      readonly refusal?: string | null
      /**
       * The status returned for the text item.
       */
      readonly status?: MessageStatus | null
      /**
       * The text content part annotations.
       */
      readonly annotations?: ReadonlyArray<Annotation> | null
    }
  }

  /**
   * OpenAI-compatible metadata emitted when a streamed text part starts.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface TextStartPartMetadata extends ProviderMetadata {
    /**
     * Provider-specific metadata returned for the streamed text start.
     */
    readonly "openai-compat"?: {
      /**
       * The OpenAI item ID associated with the streamed text part.
       */
      readonly itemId?: string | null
    } | null
  }

  /**
   * OpenAI-compatible metadata emitted when a streamed text part ends.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface TextEndPartMetadata extends ProviderMetadata {
    /**
     * Provider-specific metadata returned for the streamed text end.
     */
    readonly "openai-compat"?: {
      /**
       * The OpenAI item ID associated with the streamed text part.
       */
      readonly itemId?: string | null
      /**
       * The annotations collected for the completed streamed text part.
       */
      readonly annotations?: ReadonlyArray<Annotation> | null
    } | null
  }

  /**
   * OpenAI-compatible metadata attached to a complete reasoning response part.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ReasoningPartMetadata extends ProviderMetadata {
    /**
     * Provider-specific metadata returned for the reasoning part.
     */
    readonly "openai-compat"?: {
      /**
       * The OpenAI item ID associated with the reasoning part.
       */
      readonly itemId?: string | null
      /**
       * Encrypted reasoning content that can be sent back in later requests.
       */
      readonly encryptedContent?: string | null
      /**
       * The chat message field the provider returned the reasoning under.
       */
      readonly reasoningField?: "reasoning" | "reasoning_content" | null
    } | null
  }

  /**
   * OpenAI-compatible metadata emitted when a streamed reasoning part starts.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ReasoningStartPartMetadata extends ProviderMetadata {
    /**
     * Provider-specific metadata returned for the streamed reasoning start.
     */
    readonly "openai-compat"?: {
      /**
       * The OpenAI item ID associated with the reasoning part.
       */
      readonly itemId?: string | null
      /**
       * Encrypted reasoning content that can be sent back in later requests.
       */
      readonly encryptedContent?: string | null
      /**
       * The chat message field the provider returned the reasoning under.
       */
      readonly reasoningField?: "reasoning" | "reasoning_content" | null
    } | null
  }

  /**
   * OpenAI-compatible metadata emitted for a streamed reasoning delta.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ReasoningDeltaPartMetadata extends ProviderMetadata {
    /**
     * Provider-specific metadata returned for the streamed reasoning delta.
     */
    readonly "openai-compat"?: {
      /**
       * The OpenAI item ID associated with the reasoning part.
       */
      readonly itemId?: string | null
    } | null
  }

  /**
   * OpenAI-compatible metadata emitted when a streamed reasoning part ends.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ReasoningEndPartMetadata extends ProviderMetadata {
    /**
     * Provider-specific metadata returned for the streamed reasoning end.
     */
    readonly "openai-compat"?: {
      /**
       * The OpenAI item ID associated with the reasoning part.
       */
      readonly itemId?: string | null
      /**
       * Encrypted reasoning content that can be sent back in later requests.
       */
      readonly encryptedContent?: string
    } | null
  }

  /**
   * OpenAI-compatible metadata attached to tool-call response parts.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ToolCallPartMetadata extends ProviderMetadata {
    /**
     * Provider-specific metadata returned for the tool call.
     */
    readonly "openai-compat"?: {
      /**
       * The OpenAI item ID associated with the tool call.
       */
      readonly itemId?: string | null
      /**
       * Provider-specific extra content returned with the tool call.
       */
      readonly extraContent?: Schema.JsonObject | null
    } | null
  }

  /**
   * OpenAI-compatible metadata attached to document source citations.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface DocumentSourcePartMetadata extends ProviderMetadata {
    /**
     * Provider-specific citation metadata for OpenAI-compatible APIs.
     */
    readonly "openai-compat"?:
      | {
        /**
         * Identifies a citation to an uploaded file.
         */
        readonly type: "file_citation"
        /**
         * The index of the file in the list of files.
         */
        readonly index: number
        /**
         * The ID of the file.
         */
        readonly fileId: string
      }
      | {
        /**
         * Identifies a citation to a generated file path.
         */
        readonly type: "file_path"
        /**
         * The index of the file in the list of files.
         */
        readonly index: number
        /**
         * The ID of the file.
         */
        readonly fileId: string
      }
      | {
        /**
         * Identifies a citation to a file inside a container.
         */
        readonly type: "container_file_citation"
        /**
         * The ID of the file.
         */
        readonly fileId: string
        /**
         * The ID of the container file.
         */
        readonly containerId: string
      }
      | null
  }

  /**
   * OpenAI-compatible metadata attached to URL source citations.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface UrlSourcePartMetadata extends ProviderMetadata {
    /**
     * Provider-specific URL citation metadata for OpenAI-compatible APIs.
     */
    readonly "openai-compat"?: {
      /**
       * Identifies a citation to a URL.
       */
      readonly type: "url_citation"
      /**
       * The index of the first character of the URL citation in the message.
       */
      readonly startIndex: number
      /**
       * The index of the last character of the URL citation in the message.
       */
      readonly endIndex: number
    } | null
  }

  /**
   * OpenAI-compatible metadata attached to finish response parts.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface FinishPartMetadata extends ProviderMetadata {
    /**
     * Provider-specific metadata returned when generation finishes.
     */
    readonly "openai-compat"?: {
      /**
       * The service tier reported by the OpenAI-compatible provider.
       */
      readonly serviceTier?: "default" | "auto" | "flex" | "scale" | "priority" | null
    } | null
  }
}

// =============================================================================
// Language Model
// =============================================================================

/**
 * Creates an OpenAI-compatible model descriptor that can be provided with `Effect.provide`.
 *
 * **When to use**
 *
 * Use when you want an OpenAI-compatible language model value that carries
 * provider and model metadata and can be supplied directly to an Effect program.
 *
 * @see {@link layer} for creating a `LanguageModel.LanguageModel` layer directly
 * @see {@link make} for constructing the language model service effectfully
 *
 * @stability unstable
 * @category constructors
 * @since 4.0.0
 */
export const model = (
  model: string,
  config?: ModelConfig
): AiModel.Model<"openai", LanguageModel.LanguageModel, OpenAiClient> =>
  AiModel.make("openai", model, layer({ model, config }))

// TODO
// /**
//  * @since 4.0.0
//  * @category constructors
//  */
// export const modelWithTokenizer = (
//   model: string,
//   config?: Omit<typeof Config.Service, "model">
// ): AiModel.Model<"openai", LanguageModel.LanguageModel | Tokenizer.Tokenizer, OpenAiClient> =>
//   AiModel.make("openai", model, layerWithTokenizer({ model, config }))

/**
 * Creates an OpenAI-compatible `LanguageModel` service from a model identifier and optional request defaults.
 *
 * **When to use**
 *
 * Use to construct an OpenAI-compatible chat-completions language model service
 * backed by `OpenAiClient`.
 *
 * **Details**
 *
 * The returned effect requires `OpenAiClient`. Request defaults from the
 * `config` option are merged with any `Config` service in the context, with
 * context values taking precedence. The service supports both `generateText` and
 * `streamText`.
 *
 * @see {@link layer} for providing the service as a `Layer`
 * @see {@link model} for creating a model descriptor for `AiModel.provide`
 *
 * @stability unstable
 * @category constructors
 * @since 4.0.0
 */
export const make = Effect.fnUntraced(function*({ model, config: providerConfig }: {
  readonly model: string
  readonly config?: ModelConfig | undefined
}): Effect.fn.Return<LanguageModel.LanguageModel, never, OpenAiClient> {
  const client = yield* OpenAiClient

  const makeConfig = Effect.contextWith((services: Context.Context<never>) =>
    Effect.succeed({ model, ...providerConfig, ...Context.getOrUndefined(services, Config) })
  )

  const makeRequest = Effect.fnUntraced(
    function*<Tools extends ReadonlyArray<Tool.Any>>({ config, options, toolNameMapper }: {
      readonly config: typeof Config.Service
      readonly options: LanguageModel.ProviderOptions
      readonly toolNameMapper: Tool.NameMapper<Tools>
    }): Effect.fn.Return<{
      readonly request: CreateResponseRequestJson
      readonly toolCodecs: ToolCodecs
    }, AiError.AiError> {
      const messages = yield* prepareMessages({
        config,
        options,
        toolNameMapper
      })
      const { toolChoice, toolCodecs, tools } = yield* prepareTools({
        config,
        options,
        toolNameMapper
      })
      const responseFormat = yield* prepareResponseFormat({
        config,
        options
      })
      const { fileIdPrefixes: _fip, strictJsonSchema: _sjs, ...apiConfig } = config
      const request: CreateResponse = {
        ...apiConfig,
        text: {
          verbosity: config.text?.verbosity ?? null,
          format: responseFormat
        },
        ...(tools !== undefined ? { tools } : undefined),
        ...(toolChoice !== undefined ? { tool_choice: toolChoice } : undefined)
      }
      return { request: toChatCompletionsRequest(request, messages), toolCodecs }
    }
  )

  return yield* LanguageModel.make({
    codecTransformer: toCodecOpenAI,
    generateText: Effect.fnUntraced(
      function*(options) {
        const config = yield* makeConfig
        const toolNameMapper = new Tool.NameMapper(options.tools)
        const { request, toolCodecs } = yield* makeRequest({ config, options, toolNameMapper })
        annotateRequest(options.span, request)
        const [rawResponse, response] = yield* client.createResponse(request)
        annotateResponse(options.span, rawResponse)
        return yield* makeResponse({
          options,
          rawResponse,
          response,
          toolNameMapper,
          toolCodecs
        })
      }
    ),
    streamText: Effect.fnUntraced(
      function*(options) {
        const config = yield* makeConfig
        const toolNameMapper = new Tool.NameMapper(options.tools)
        const { request, toolCodecs } = yield* makeRequest({ config, options, toolNameMapper })
        annotateRequest(options.span, request)
        const [response, stream] = yield* client.createResponseStream(request)
        return yield* makeStreamResponse({
          options,
          stream,
          response,
          toolNameMapper,
          toolCodecs
        })
      },
      (effect, options) =>
        effect.pipe(
          Stream.unwrap,
          Stream.map((response) => {
            annotateStreamResponse(options.span, response)
            return response
          })
        )
    )
  })
})

/**
 * Creates a layer for the OpenAI-compatible language model.
 *
 * **When to use**
 *
 * Use when composing application layers and you want OpenAI-compatible APIs to
 * satisfy `LanguageModel.LanguageModel` while supplying `OpenAiClient` from
 * another layer.
 *
 * @see {@link make} for constructing the language model service effectfully
 * @see {@link model} for creating an AI model descriptor
 *
 * @stability unstable
 * @category layers
 * @since 4.0.0
 */
export const layer = (options: {
  readonly model: string
  readonly config?: ModelConfig | undefined
}): Layer.Layer<LanguageModel.LanguageModel, never, OpenAiClient> =>
  Layer.effect(LanguageModel.LanguageModel, make(options))

/**
 * Provides scoped config overrides for OpenAI-compatible language model operations.
 *
 * **When to use**
 *
 * Use to override request configuration for a single language model effect
 * without changing the defaults supplied to `model`, `make`, or `layer`.
 *
 * **Details**
 *
 * Existing `Config` values from the Effect context are merged with `overrides`,
 * and the override values take precedence.
 *
 * @see {@link Config} for the configuration shape
 *
 * @stability unstable
 * @category configuration
 * @since 4.0.0
 */
export const withConfigOverride: {
  (overrides: typeof Config.Service): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>
  <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service): Effect.Effect<A, E, Exclude<R, Config>>
} = dual<
  (
    overrides: typeof Config.Service
  ) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>,
  <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service) => Effect.Effect<A, E, Exclude<R, Config>>
>(2, (self, overrides) =>
  Effect.flatMap(
    Effect.serviceOption(Config),
    (config) =>
      Effect.provideService(self, Config, {
        ...(config._tag === "Some" ? config.value : {}),
        ...overrides
      })
  ))

// =============================================================================
// Prompt Conversion
// =============================================================================

const getSystemMessageMode = (model: string): "system" | "developer" =>
  model.startsWith("o") ||
    model.startsWith("gpt-5") ||
    model.startsWith("codex-") ||
    model.startsWith("computer-use")
    ? "developer"
    : "system"

const prepareMessages = Effect.fnUntraced(
  function*<Tools extends ReadonlyArray<Tool.Any>>({
    config,
    options,
    toolNameMapper
  }: {
    readonly config: typeof Config.Service
    readonly options: LanguageModel.ProviderOptions
    readonly toolNameMapper: Tool.NameMapper<Tools>
  }): Effect.fn.Return<ReadonlyArray<ChatCompletionRequestMessage>, AiError.AiError> {
    const messages: Array<ChatCompletionRequestMessage> = []

    for (const message of options.prompt.content) {
      switch (message.role) {
        case "system": {
          messages.push({
            role: getSystemMessageMode(config.model!),
            content: message.content
          })
          break
        }

        case "user": {
          const content: Array<InputContent> = []

          for (let index = 0; index < message.content.length; index++) {
            const part = message.content[index]

            switch (part.type) {
              case "text": {
                content.push({ type: "input_text", text: part.text })
                break
              }

              case "file": {
                if (part.mediaType.startsWith("image/")) {
                  const detail = getImageDetail(part)
                  const mediaType = part.mediaType === "image/*" ? "image/jpeg" : part.mediaType

                  if (typeof part.data === "string" && isFileId(part.data, config)) {
                    content.push({ type: "input_image", file_id: part.data, detail })
                  } else {
                    const imageUrl = part.data instanceof URL
                      ? part.data.toString()
                      : part.data instanceof Uint8Array
                      ? `data:${mediaType};base64,${Base64.encode(part.data)}`
                      : /^(data:|https?:\/\/)/i.test(part.data)
                      ? part.data
                      : `data:${mediaType};base64,${part.data}`
                    content.push({ type: "input_image", image_url: imageUrl, detail })
                  }
                } else if (part.mediaType === "application/pdf") {
                  if (typeof part.data === "string" && isFileId(part.data, config)) {
                    content.push({ type: "input_file", file_id: part.data })
                  }

                  if (part.data instanceof URL) {
                    content.push({ type: "input_file", file_url: part.data.toString() })
                  }

                  if (part.data instanceof Uint8Array) {
                    const base64 = Base64.encode(part.data)
                    const fileName = part.fileName ?? `part-${index}.pdf`
                    const fileData = `data:application/pdf;base64,${base64}`
                    content.push({ type: "input_file", filename: fileName, file_data: fileData })
                  }
                } else {
                  return yield* AiError.make({
                    module: "OpenAiLanguageModel",
                    method: "prepareMessages",
                    reason: new AiError.InvalidRequestError({
                      description: `Detected unsupported media type for file: '${part.mediaType}'`
                    })
                  })
                }
              }
            }
          }

          messages.push({ role: "user", content: toChatMessageContent(content) })

          break
        }

        case "assistant": {
          let content: string | null = null
          let reasoning = ""
          let reasoningField: ReasoningField | undefined
          const toolCalls: Array<ChatCompletionRequestToolCall> = []

          for (const part of message.content) {
            switch (part.type) {
              case "text": {
                content = (content ?? "") + part.text
                break
              }

              case "reasoning": {
                reasoning += part.text
                reasoningField ??= part.options["openai-compat"]?.reasoningField ?? undefined
                break
              }

              case "tool-call": {
                if (part.providerExecuted) {
                  break
                }

                const extraContent = getExtraContent(part)

                toolCalls.push({
                  id: part.id,
                  type: "function",
                  function: {
                    name: toolNameMapper.getProviderName(part.name),
                    arguments: JSON.stringify(part.params)
                  },
                  ...(Predicate.isNotNull(extraContent) ? { extra_content: extraContent } : undefined)
                })
                break
              }
            }
          }

          // Text, reasoning and tool calls from one prompt message are sent as a
          // single chat message so reasoning stays attached to its tool calls
          if (content !== null || toolCalls.length > 0) {
            messages.push({
              role: "assistant",
              content,
              ...(reasoning.length > 0 ? { [reasoningField ?? "reasoning_content"]: reasoning } : undefined),
              ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : undefined)
            })
          }

          break
        }

        case "tool": {
          for (const part of message.content) {
            if (part.type === "tool-approval-response") {
              continue
            }

            messages.push({
              role: "tool",
              tool_call_id: part.id,
              content: Predicate.isNotUndefined(part.modelOutput)
                ? Prompt.toolModelOutputToText(part.modelOutput)
                : typeof part.result === "string"
                ? part.result
                : JSON.stringify(part.result)
            })
          }

          break
        }
      }
    }

    return messages
  }
)

// =============================================================================
// HTTP Details
// =============================================================================

const buildHttpResponseDetails = (
  response: HttpClientResponse.HttpClientResponse
): typeof Response.HttpResponseDetails.Type => ({
  status: response.status,
  headers: Redactable.redact(response.headers) as Record<string, string>
})

// =============================================================================
// Response Conversion
// =============================================================================

type ResponseStreamEvent = CreateResponse200Sse

const isUnknownChatCompletionEvent = (
  event: ResponseStreamEvent
): event is UnknownChatCompletionEvent =>
  typeof event !== "string" && "_tag" in event && event._tag === "UnknownChatCompletionEvent"

type ActiveToolCall = {
  readonly id: string
  name: string
  arguments: string
  extraContent: Schema.JsonObject | undefined
}

const makeResponse = Effect.fnUntraced(
  function*<Tools extends ReadonlyArray<Tool.Any>>({
    options,
    rawResponse,
    response,
    toolNameMapper,
    toolCodecs
  }: {
    readonly options: LanguageModel.ProviderOptions
    readonly rawResponse: CreateResponse200
    readonly response: HttpClientResponse.HttpClientResponse
    readonly toolNameMapper: Tool.NameMapper<Tools>
    readonly toolCodecs: ToolCodecs
  }): Effect.fn.Return<
    Array<Response.PartEncoded>,
    AiError.AiError
  > {
    let hasToolCalls = false
    const parts: Array<Response.PartEncoded> = []

    const createdAt = new Date(rawResponse.created * 1000)
    parts.push({
      type: "response-metadata",
      id: rawResponse.id,
      modelId: rawResponse.model as string,
      timestamp: DateTime.formatIso(DateTime.fromDateUnsafe(createdAt))
    })

    const choice = rawResponse.choices[0]
    const message = choice?.message

    if (message !== undefined) {
      const reasoningField = getResponseReasoningField(message)
      const reasoning = reasoningField !== undefined ? message[reasoningField] : undefined
      if (reasoningField !== undefined && Predicate.isNotNullish(reasoning) && reasoning.length > 0) {
        parts.push({ type: "reasoning", text: reasoning, metadata: { "openai-compat": { reasoningField } } })
      }

      if (
        message.content !== undefined && Predicate.isNotNull(message.content) && message.content.length > 0
      ) {
        parts.push({ type: "text", text: message.content })
      }

      if (message.tool_calls !== undefined) {
        for (const [index, toolCall] of message.tool_calls.entries()) {
          const toolId = toolCall.id ?? `${rawResponse.id}_tool_${index}`
          const toolName = toolNameMapper.getCustomName(toolCall.function?.name ?? "unknown_tool")
          const toolParamsJson = toolCall.function?.arguments ?? "{}"
          const toolParams = yield* Effect.try({
            try: () => Tool.unsafeSecureJsonParse(toolParamsJson),
            catch: (cause) =>
              AiError.make({
                module: "OpenAiLanguageModel",
                method: "makeResponse",
                reason: new AiError.ToolParameterValidationError({
                  toolName,
                  description: `Failed to securely JSON parse tool parameters: ${cause}`
                })
              })
          })
          const params = yield* transformToolCallParams(options, toolName, toolParams, toolCodecs)
          hasToolCalls = true
          parts.push({
            type: "tool-call",
            id: toolId,
            name: toolName,
            params,
            metadata: {
              "openai-compat": {
                ...makeItemIdMetadata(toolCall.id),
                ...makeExtraContentMetadata(toolCall.extra_content ?? undefined)
              }
            }
          })
        }
      }
    }

    const finishReason = InternalUtilities.resolveFinishReason(
      choice?.finish_reason,
      hasToolCalls
    )
    const serviceTier = normalizeServiceTier(rawResponse.service_tier)

    parts.push({
      type: "finish",
      reason: finishReason,
      usage: getUsage(rawResponse.usage),
      response: buildHttpResponseDetails(response),
      ...(serviceTier !== undefined && { metadata: { "openai-compat": { serviceTier } } })
    })

    return parts
  }
)

const makeStreamResponse = Effect.fnUntraced(
  function*<Tools extends ReadonlyArray<Tool.Any>>({
    options,
    stream,
    response,
    toolNameMapper,
    toolCodecs
  }: {
    readonly options: LanguageModel.ProviderOptions
    readonly stream: Stream.Stream<ResponseStreamEvent, AiError.AiError>
    readonly response: HttpClientResponse.HttpClientResponse
    readonly toolNameMapper: Tool.NameMapper<Tools>
    readonly toolCodecs: ToolCodecs
  }): Effect.fn.Return<
    Stream.Stream<Response.StreamPartEncoded, AiError.AiError>,
    AiError.AiError
  > {
    let serviceTier: string | undefined = undefined
    let usage: CreateResponse200["usage"] = undefined
    let finishReason: string | null | undefined = undefined
    let metadataEmitted = false
    let textStarted = false
    let textId = ""
    let reasoningStarted = false
    let reasoningId = ""
    let hasToolCalls = false
    const activeToolCalls: Record<number, ActiveToolCall> = {}

    return stream.pipe(
      Stream.mapEffect(Effect.fnUntraced(function*(event) {
        const parts: Array<Response.StreamPartEncoded> = []

        if (event === "[DONE]") {
          if (reasoningStarted) {
            parts.push({
              type: "reasoning-end",
              id: reasoningId,
              metadata: { "openai-compat": { ...makeItemIdMetadata(reasoningId) } }
            })
          }

          if (textStarted) {
            parts.push({
              type: "text-end",
              id: textId,
              metadata: { "openai-compat": { ...makeItemIdMetadata(textId) } }
            })
          }

          for (const toolCall of Object.values(activeToolCalls)) {
            const toolParams = toolCall.arguments.length > 0 ? toolCall.arguments : "{}"
            const parsedParams = yield* Effect.try({
              try: () => Tool.unsafeSecureJsonParse(toolParams),
              catch: (cause) =>
                AiError.make({
                  module: "OpenAiLanguageModel",
                  method: "makeStreamResponse",
                  reason: new AiError.ToolParameterValidationError({
                    toolName: toolCall.name,
                    description: `Failed to securely JSON parse tool parameters: ${cause}`
                  })
                })
            })
            const params = yield* transformToolCallParams(options, toolCall.name, parsedParams, toolCodecs)
            parts.push({ type: "tool-params-end", id: toolCall.id })
            parts.push({
              type: "tool-call",
              id: toolCall.id,
              name: toolCall.name,
              params,
              metadata: {
                "openai-compat": {
                  ...makeItemIdMetadata(toolCall.id),
                  ...makeExtraContentMetadata(toolCall.extraContent)
                }
              }
            })
            hasToolCalls = true
          }

          const normalizedServiceTier = normalizeServiceTier(serviceTier)
          parts.push({
            type: "finish",
            reason: InternalUtilities.resolveFinishReason(finishReason, hasToolCalls),
            usage: getUsage(usage),
            response: buildHttpResponseDetails(response),
            ...(normalizedServiceTier !== undefined
              ? { metadata: { "openai-compat": { serviceTier: normalizedServiceTier } } }
              : undefined)
          })
          return parts
        }

        // Keep unknown events available to direct client consumers; this layer
        // cannot translate provider-specific data into portable stream parts.
        if (isUnknownChatCompletionEvent(event)) {
          return parts
        }

        if (event.service_tier !== undefined) {
          serviceTier = event.service_tier
        }
        if (event.usage !== undefined && Predicate.isNotNull(event.usage)) {
          usage = event.usage
        }

        if (!metadataEmitted) {
          metadataEmitted = true
          textId = `${event.id}_message`
          reasoningId = `${event.id}_reasoning`
          parts.push({
            type: "response-metadata",
            id: event.id,
            modelId: event.model,
            timestamp: DateTime.formatIso(DateTime.fromDateUnsafe(new Date(event.created * 1000)))
          })
        }

        const choice = event.choices[0]
        if (Predicate.isUndefined(choice)) {
          return parts
        }

        const reasoningField = Predicate.isNotNullish(choice.delta)
          ? getResponseReasoningField(choice.delta)
          : undefined
        const reasoningDelta = reasoningField !== undefined ? choice.delta?.[reasoningField] : undefined
        if (reasoningField !== undefined && Predicate.isNotNullish(reasoningDelta) && reasoningDelta.length > 0) {
          if (!reasoningStarted) {
            reasoningStarted = true
            parts.push({
              type: "reasoning-start",
              id: reasoningId,
              metadata: { "openai-compat": { ...makeItemIdMetadata(reasoningId), reasoningField } }
            })
          }
          parts.push({ type: "reasoning-delta", id: reasoningId, delta: reasoningDelta })
        }

        if (Predicate.isNotNullish(choice.delta?.content) && choice.delta.content.length > 0) {
          if (reasoningStarted) {
            reasoningStarted = false
            parts.push({
              type: "reasoning-end",
              id: reasoningId,
              metadata: { "openai-compat": { ...makeItemIdMetadata(reasoningId) } }
            })
          }

          if (!textStarted) {
            textStarted = true
            parts.push({
              type: "text-start",
              id: textId,
              metadata: { "openai-compat": { ...makeItemIdMetadata(textId) } }
            })
          }
          parts.push({ type: "text-delta", id: textId, delta: choice.delta.content })
        }

        if (Predicate.isNotNullish(choice.delta?.tool_calls)) {
          hasToolCalls = hasToolCalls || choice.delta.tool_calls.length > 0
          choice.delta.tool_calls.forEach((deltaTool, indexInChunk) => {
            const toolIndex = deltaTool.index ?? indexInChunk
            const activeToolCall = activeToolCalls[toolIndex]
            const toolId = activeToolCall?.id ?? deltaTool.id ?? `${event.id}_tool_${toolIndex}`
            const providerToolName = deltaTool.function?.name
            const toolName = Predicate.isNotNullish(providerToolName)
              ? toolNameMapper.getCustomName(providerToolName)
              : activeToolCall?.name ?? toolNameMapper.getCustomName("unknown_tool")
            const argumentsDelta = deltaTool.function?.arguments ?? ""

            if (Predicate.isUndefined(activeToolCall)) {
              activeToolCalls[toolIndex] = {
                id: toolId,
                name: toolName,
                arguments: argumentsDelta,
                extraContent: deltaTool.extra_content ?? undefined
              }
              parts.push({ type: "tool-params-start", id: toolId, name: toolName })
            } else {
              activeToolCall.name = toolName
              activeToolCall.arguments = `${activeToolCall.arguments}${argumentsDelta}`
              if (Predicate.isNotNullish(deltaTool.extra_content)) {
                activeToolCall.extraContent = deltaTool.extra_content
              }
            }

            if (argumentsDelta.length > 0) {
              parts.push({ type: "tool-params-delta", id: toolId, delta: argumentsDelta })
            }
          })
        }

        if (choice.finish_reason !== undefined && Predicate.isNotNull(choice.finish_reason)) {
          finishReason = choice.finish_reason
        }

        return parts
      })),
      Stream.filter(Arr.isArrayNonEmpty),
      Stream.flattenArray
    )
  }
)

// =============================================================================
// Telemetry
// =============================================================================

const annotateRequest = (
  span: Span,
  request: CreateResponseRequestJson
): void => {
  addGenAIAnnotations(span, {
    provider: { name: "openai" },
    operation: { name: "chat" },
    request: {
      model: request.model as string,
      temperature: request.temperature as number | undefined,
      topP: request.top_p as number | undefined,
      maxTokens: request.max_tokens as number | undefined
    },
    openai: {
      request: {
        serviceTier: request.service_tier as string | undefined
      }
    }
  })
}

const annotateResponse = (span: Span, response: CreateResponse200): void => {
  const finishReason = response.choices[0]?.finish_reason ?? undefined
  addGenAIAnnotations(span, {
    response: {
      id: response.id,
      model: response.model as string,
      finishReasons: finishReason !== undefined ? [finishReason] : undefined
    },
    usage: {
      inputTokens: response.usage?.prompt_tokens,
      outputTokens: response.usage?.completion_tokens
    },
    openai: {
      response: {
        serviceTier: response.service_tier as string | undefined
      }
    }
  })
}

const annotateStreamResponse = (span: Span, part: Response.StreamPartEncoded) => {
  if (part.type === "response-metadata") {
    addGenAIAnnotations(span, {
      response: {
        id: part.id,
        model: part.modelId
      }
    })
  }
  if (part.type === "finish") {
    const serviceTier = (part.metadata as any)?.["openai-compat"]?.serviceTier as string | undefined
    addGenAIAnnotations(span, {
      response: {
        finishReasons: [part.reason]
      },
      usage: {
        inputTokens: part.usage.inputTokens.total,
        outputTokens: part.usage.outputTokens.total
      },
      openai: {
        response: { serviceTier }
      }
    })
  }
}

// =============================================================================
// Tool Conversion
// =============================================================================

type OpenAiToolChoice = CreateResponse["tool_choice"]

const unsupportedSchemaError = (error: unknown, method: string): AiError.AiError =>
  AiError.make({
    module: "OpenAiLanguageModel",
    method,
    reason: new AiError.UnsupportedSchemaError({
      description: error instanceof Error ? error.message : String(error)
    })
  })

const tryCodecTransform = <S extends Schema.Constraint>(schema: S, method: string) =>
  Effect.try({
    try: () => toCodecOpenAI(schema),
    catch: (error) => unsupportedSchemaError(error, method)
  })

const tryJsonSchema = <S extends Schema.Constraint>(schema: S, method: string) =>
  Effect.try({
    try: () => Tool.getJsonSchemaFromSchema(schema, { transformer: toCodecOpenAI }),
    catch: (error) => unsupportedSchemaError(error, method)
  })

const toolParametersError = (tool: Tool.Any, error: unknown, method: string): AiError.AiError =>
  unsupportedSchemaError(
    `Tool "${tool.name}" parameters: ${error instanceof Error ? error.message : String(error)}. ` +
      "For a tool without parameters, omit `parameters` or use `Tool.EmptyParams`",
    method
  )

type ToolCodec = ReturnType<typeof toCodecOpenAI>["codec"]
type ToolCodecs = ReadonlyMap<Tool.Any, ToolCodec>

const transformToolCallParams = Effect.fnUntraced(function*(
  options: LanguageModel.ProviderOptions,
  toolName: string,
  toolParams: unknown,
  toolCodecs: ToolCodecs
): Effect.fn.Return<unknown, AiError.AiError> {
  const tool = options.tools.find((tool) => tool.name === toolName)

  if (Predicate.isUndefined(tool)) {
    if (options.toolCallValidation === "deferred") {
      return toolParams
    }
    return yield* AiError.make({
      module: "OpenAiLanguageModel",
      method: "makeResponse",
      reason: new AiError.ToolNotFoundError({
        toolName,
        availableTools: options.tools.map((tool) => tool.name)
      })
    })
  }

  if (Tool.isDynamic(tool) && tool.jsonSchema !== undefined) {
    return toolParams
  }

  const codec = toolCodecs.get(tool) ?? (yield* tryCodecTransform(tool.parametersSchema, "makeResponse")).codec

  // Normalize valid parameters; leave invalid ones for Toolkit.
  return yield* (
    Schema.decodeEffect(codec)(toolParams) as Effect.Effect<unknown, Schema.SchemaError>
  ).pipe(
    Effect.flatMap((decoded) =>
      Schema.encodeUnknownEffect(tool.parametersSchema)(decoded) as Effect.Effect<unknown, Schema.SchemaError>
    ),
    Effect.orElseSucceed(() => toolParams)
  )
})

const prepareTools = Effect.fnUntraced(function*<Tools extends ReadonlyArray<Tool.Any>>({
  config,
  options,
  toolNameMapper
}: {
  readonly config: typeof Config.Service
  readonly options: LanguageModel.ProviderOptions
  readonly toolNameMapper: Tool.NameMapper<Tools>
}): Effect.fn.Return<{
  readonly tools: ReadonlyArray<OpenAiClientTool> | undefined
  readonly toolChoice: OpenAiToolChoice | undefined
  readonly toolCodecs: ToolCodecs
}, AiError.AiError> {
  const toolCodecs = new Map<Tool.Any, ToolCodec>()

  // Return immediately if no tools are in the toolkit
  if (options.tools.length === 0) {
    return { tools: undefined, toolChoice: undefined, toolCodecs }
  }

  const tools: Array<OpenAiClientTool> = []
  let toolChoice: OpenAiToolChoice | undefined = undefined

  // Filter the incoming tools down to the set of allowed tools as indicated by
  // the tool choice. This must be done here given that there is no tool name
  // in OpenAI's provider-defined tools, so there would be no way to perform
  // this filter otherwise
  let allowedTools = options.tools
  if (typeof options.toolChoice === "object" && "oneOf" in options.toolChoice) {
    const allowedToolNames = new Set(options.toolChoice.oneOf)
    allowedTools = options.tools.filter((tool) => allowedToolNames.has(tool.name))
    toolChoice = options.toolChoice.mode === "required" ? "required" : "auto"
  }

  // Convert the tools in the toolkit to the provider-defined format
  for (const tool of allowedTools) {
    if (Tool.isUserDefined(tool) || Tool.isDynamic(tool)) {
      const strict = Tool.getStrictMode(tool) ?? config.strictJsonSchema ?? true
      let parameters: ReturnType<typeof Tool.getJsonSchema>
      if (Tool.isDynamic(tool) && tool.jsonSchema !== undefined) {
        parameters = tool.jsonSchema
      } else {
        const prepared = yield* Effect.try({
          try: () => toCodecOpenAI(tool.parametersSchema),
          catch: (error) => toolParametersError(tool, error, "prepareTools")
        })
        parameters = prepared.jsonSchema
        // Reused to normalize this tool's calls in the response.
        toolCodecs.set(tool, prepared.codec)
      }
      tools.push({
        type: "function",
        name: tool.name,
        description: Tool.getDescription(tool) ?? null,
        parameters: parameters as { readonly [x: string]: Schema.Json },
        strict
      })
    }

    if (Tool.isProviderDefined(tool)) {
      tools.push({
        type: "function",
        name: tool.providerName,
        description: Tool.getDescription(tool) ?? null,
        parameters: Tool.getJsonSchema(tool) as { readonly [x: string]: Schema.Json },
        strict: config.strictJsonSchema ?? true
      })
    }
  }

  if (options.toolChoice === "auto" || options.toolChoice === "none" || options.toolChoice === "required") {
    toolChoice = options.toolChoice
  }

  if (typeof options.toolChoice === "object" && "tool" in options.toolChoice) {
    const toolName = toolNameMapper.getProviderName(options.toolChoice.tool)
    const providerNames = toolNameMapper.providerNames
    if (providerNames.includes(toolName)) {
      toolChoice = { type: "function", name: toolName }
    } else {
      toolChoice = { type: "function", name: options.toolChoice.tool }
    }
  }

  return { tools, toolChoice, toolCodecs }
})

const toChatCompletionsRequest = (
  payload: CreateResponse,
  messages: ReadonlyArray<ChatCompletionRequestMessage>
): CreateResponseRequestJson => {
  const responseFormat = toChatResponseFormat(payload.text?.format)
  const tools = payload.tools !== undefined
    ? payload.tools.map(toChatTool).filter((tool): tool is NonNullable<ReturnType<typeof toChatTool>> =>
      tool !== undefined
    )
    : []
  const toolChoice = toChatToolChoice(payload.tool_choice)

  return {
    ...extractCustomRequestProperties(payload),
    model: payload.model ?? "",
    messages: messages.length > 0 ? messages : [{ role: "user", content: "" }],
    ...(payload.temperature !== undefined ? { temperature: payload.temperature } : undefined),
    ...(payload.top_p !== undefined ? { top_p: payload.top_p } : undefined),
    ...(payload.max_output_tokens !== undefined ? { max_tokens: payload.max_output_tokens } : undefined),
    ...(payload.user !== undefined ? { user: payload.user } : undefined),
    ...(payload.seed !== undefined ? { seed: payload.seed } : undefined),
    ...(payload.parallel_tool_calls !== undefined
      ? { parallel_tool_calls: payload.parallel_tool_calls }
      : undefined),
    ...(payload.service_tier !== undefined ? { service_tier: payload.service_tier } : undefined),
    ...(payload.reasoning !== undefined ? { reasoning: payload.reasoning } : undefined),
    ...(responseFormat !== undefined ? { response_format: responseFormat } : undefined),
    ...(tools.length > 0 ? { tools } : undefined),
    ...(toolChoice !== undefined ? { tool_choice: toolChoice } : undefined)
  }
}

const createResponseKnownProperties = new Set<string>([
  "metadata",
  "top_logprobs",
  "temperature",
  "top_p",
  "user",
  "safety_identifier",
  "prompt_cache_key",
  "service_tier",
  "prompt_cache_retention",
  "previous_response_id",
  "model",
  "reasoning",
  "background",
  "max_output_tokens",
  "max_tool_calls",
  "text",
  "tools",
  "tool_choice",
  "truncation",
  "input",
  "include",
  "parallel_tool_calls",
  "store",
  "instructions",
  "stream",
  "conversation",
  "modalities",
  "seed"
])

const extractCustomRequestProperties = (payload: CreateResponse): Record<string, unknown> => {
  const customProperties: Record<string, unknown> = {}
  for (const [key, value] of Object.entries(payload)) {
    if (!createResponseKnownProperties.has(key)) {
      Rec.assignProperty(customProperties, key, value)
    }
  }
  return customProperties
}

const toChatResponseFormat = (
  format: TextResponseFormatConfiguration | undefined
): CreateResponseRequestJson["response_format"] | undefined => {
  if (Predicate.isUndefined(format) || Predicate.isNull(format)) {
    return undefined
  }

  switch (format.type) {
    case "json_object": {
      return { type: "json_object" }
    }
    case "json_schema": {
      return {
        type: "json_schema",
        json_schema: {
          name: format.name,
          schema: format.schema,
          ...(format.description !== undefined ? { description: format.description } : undefined),
          ...(Predicate.isNotNullish(format.strict) ? { strict: format.strict } : undefined)
        }
      }
    }
    default: {
      return undefined
    }
  }
}

const toChatToolChoice = (
  toolChoice: OpenAiToolChoice
): CreateResponseRequestJson["tool_choice"] | undefined => {
  if (Predicate.isUndefined(toolChoice)) {
    return undefined
  }

  if (typeof toolChoice === "string") {
    return toolChoice
  }

  if (toolChoice.type === "allowed_tools") {
    return toolChoice.mode
  }

  if (toolChoice.type === "function") {
    return {
      type: "function",
      function: {
        name: toolChoice.name
      }
    }
  }

  const functionName = Predicate.hasProperty(toolChoice, "name") && typeof toolChoice.name === "string"
    ? toolChoice.name
    : toolChoice.type

  return {
    type: "function",
    function: {
      name: functionName
    }
  }
}

const toChatTool = (
  tool: OpenAiClientTool
): NonNullable<CreateResponseRequestJson["tools"]>[number] | undefined => {
  if (tool.type === "function") {
    return {
      type: "function",
      function: {
        name: tool.name,
        ...(tool.description !== undefined ? { description: tool.description } : undefined),
        ...(Predicate.isNotNullish(tool.parameters) ? { parameters: tool.parameters } : undefined),
        ...(Predicate.isNotNullish(tool.strict) ? { strict: tool.strict } : undefined)
      }
    }
  }

  if (tool.type === "custom") {
    return {
      type: "function",
      function: {
        name: tool.name,
        parameters: { type: "object", additionalProperties: true }
      }
    }
  }

  return undefined
}

const toChatMessageContent = (
  content: string | ReadonlyArray<InputContent>
): string | ReadonlyArray<ChatCompletionContentPart> => {
  if (typeof content === "string") {
    return content
  }

  if (content.length === 1 && content[0].type === "input_text") {
    return content[0].text
  }

  const parts: Array<ChatCompletionContentPart> = []

  for (const part of content) {
    switch (part.type) {
      case "input_text": {
        parts.push({ type: "text", text: part.text })
        break
      }
      case "input_image": {
        const imageUrl = part.image_url !== undefined
          ? part.image_url
          : part.file_id !== undefined
          ? `openai://file/${part.file_id}`
          : undefined

        if (imageUrl !== undefined && Predicate.isNotNull(imageUrl)) {
          parts.push({
            type: "image_url",
            image_url: {
              url: imageUrl,
              ...(Predicate.isNotNullish(part.detail) ? { detail: part.detail } : undefined)
            }
          })
        }
        break
      }
      case "input_file": {
        if (part.file_url !== undefined) {
          parts.push({ type: "text", text: part.file_url })
        } else if (part.file_data !== undefined) {
          parts.push({ type: "text", text: part.file_data })
        } else if (part.file_id !== undefined) {
          parts.push({ type: "text", text: `openai://file/${part.file_id}` })
        }
        break
      }
    }
  }

  if (parts.length === 0) {
    return ""
  }

  if (parts.every((part) => part.type === "text")) {
    return parts.map((part) => part.text).join("\n")
  }

  return parts
}

// =============================================================================
// Utilities
// =============================================================================

const isFileId = (data: string, config: typeof Config.Service): boolean =>
  config.fileIdPrefixes != null && config.fileIdPrefixes.some((prefix) => data.startsWith(prefix))

const getExtraContent = (
  part: Prompt.ToolCallPart
): Schema.JsonObject | null => part.options["openai-compat"]?.extraContent ?? null

/**
 * The chat message field carrying reasoning text. Providers differ: DeepSeek,
 * Kimi and GLM use `reasoning_content`, while Groq uses `reasoning` and
 * rejects `reasoning_content` on request messages.
 */
type ReasoningField = "reasoning" | "reasoning_content"

const getResponseReasoningField = (message: {
  readonly reasoning?: string | null | undefined
  readonly reasoning_content?: string | null | undefined
}): ReasoningField | undefined =>
  Predicate.isNotNullish(message.reasoning)
    ? "reasoning"
    : Predicate.isNotNullish(message.reasoning_content)
    ? "reasoning_content"
    : undefined

const getImageDetail = (part: Prompt.FilePart): ImageDetail => part.options["openai-compat"]?.imageDetail ?? "auto"

const makeItemIdMetadata = (itemId: string | undefined) => itemId !== undefined ? { itemId } : undefined

const makeExtraContentMetadata = (extraContent: Schema.JsonObject | undefined) =>
  extraContent !== undefined ? { extraContent } : undefined

const normalizeServiceTier = (
  serviceTier: string | undefined
): "default" | "auto" | "flex" | "scale" | "priority" | null | undefined => {
  switch (serviceTier) {
    case undefined:
      return undefined
    case "default":
    case "auto":
    case "flex":
    case "scale":
    case "priority":
      return serviceTier
    default:
      return null
  }
}

const prepareResponseFormat = Effect.fnUntraced(function*({ config, options }: {
  readonly config: typeof Config.Service
  readonly options: LanguageModel.ProviderOptions
}): Effect.fn.Return<TextResponseFormatConfiguration, AiError.AiError> {
  if (options.responseFormat.type === "json") {
    const name = options.responseFormat.objectName
    const schema = options.responseFormat.schema
    const jsonSchema = yield* tryJsonSchema(schema, "prepareResponseFormat")
    return {
      type: "json_schema",
      name,
      description: AST.resolveDescription(schema.ast) ?? "Response with a JSON object",
      schema: jsonSchema as any,
      strict: config.strictJsonSchema ?? true
    }
  }
  return { type: "text" }
})

const getUsage = (usage: CreateResponse200["usage"]): Response.Usage => {
  if (Predicate.isNullish(usage)) {
    return {
      inputTokens: {
        uncached: undefined,
        total: undefined,
        cacheRead: undefined,
        cacheWrite: undefined
      },
      outputTokens: {
        total: undefined,
        text: undefined,
        reasoning: undefined
      }
    }
  }

  const inputTokens = usage.prompt_tokens
  const outputTokens = usage.completion_tokens
  const cachedTokens = getUsageDetailNumber(usage.prompt_tokens_details, "cached_tokens") ?? 0
  const reasoningTokens = getUsageDetailNumber(usage.completion_tokens_details, "reasoning_tokens") ?? 0

  return {
    inputTokens: {
      uncached: inputTokens - cachedTokens,
      total: inputTokens,
      cacheRead: cachedTokens,
      cacheWrite: undefined
    },
    outputTokens: {
      total: outputTokens,
      text: outputTokens - reasoningTokens,
      reasoning: reasoningTokens
    }
  }
}

const getUsageDetailNumber = (
  details: unknown,
  field: string
): number | undefined => {
  if (typeof details !== "object" || details === null) {
    return undefined
  }

  const value = (details as Record<string, unknown>)[field]
  return typeof value === "number" ? value : undefined
}