@effect/ai-openai-compat 4.0.0-beta.7 → 4.0.0-beta.71

package/src/OpenAiLanguageModel.ts

@@ -1,21 +1,48 @@
 /**
- * OpenAI Language Model implementation.
+ * The `OpenAiLanguageModel` module adapts OpenAI-compatible chat-completions
+ * providers to the shared Effect AI `LanguageModel` interface. It translates
+ * provider-neutral prompts, tools, structured output schemas, and streaming
+ * responses into the request and response shapes used by `OpenAiClient`.
  *
- * Provides a LanguageModel implementation for OpenAI's chat completions API,
- * supporting text generation, structured output, tool calling, and streaming.
+ * Use this module when an application wants to talk to OpenAI-compatible
+ * endpoints through Effect AI abstractions rather than constructing provider
+ * payloads directly. The exported constructors build a language model service
+ * from a model id, while `Config` and {@link withConfigOverride} provide scoped
+ * defaults for request fields such as temperature, reasoning options, text
+ * format, and provider-specific file handling.
  *
- * @since 1.0.0
+ * **Common tasks**
+ *
+ * - Create a model descriptor with {@link model}
+ * - Build or provide the `LanguageModel` service with {@link make} or
+ *   {@link layer}
+ * - Scope request defaults with {@link Config} and {@link withConfigOverride}
+ * - Send tool calls, structured output schemas, images, files, and reasoning
+ *   metadata through the provider-neutral Effect AI prompt types
+ *
+ * **Gotchas**
+ *
+ * - The module requires an `OpenAiClient` service; configure authentication,
+ *   base URL, and HTTP behavior through that client layer.
+ * - Compatibility depends on the provider supporting the OpenAI request fields
+ *   being used. Optional capabilities such as strict JSON schemas, reasoning
+ *   metadata, and tool status fields may vary across providers.
+ * - `fileIdPrefixes` tells the prompt conversion which file references are
+ *   provider file IDs instead of base64 file contents.
+ *
+ * @since 4.0.0
  */
+import * as Context from "effect/Context"
 import * as DateTime from "effect/DateTime"
 import * as Effect from "effect/Effect"
 import * as Encoding from "effect/Encoding"
 import { dual } from "effect/Function"
 import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
 import * as Predicate from "effect/Predicate"
 import * as Redactable from "effect/Redactable"
 import type * as Schema from "effect/Schema"
 import * as AST from "effect/SchemaAST"
-import * as ServiceMap from "effect/ServiceMap"
 import * as Stream from "effect/Stream"
 import type { Span } from "effect/Tracer"
 import type { DeepMutable, Simplify } from "effect/Types"
@@ -60,10 +87,18 @@ type ImageDetail = "auto" | "low" | "high"
 /**
  * Service definition for OpenAI language model configuration.
  *
- * @since 1.0.0
+ * **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
+ *
  * @category context
+ * @since 4.0.0
  */
-export class Config extends ServiceMap.Service<
+export class Config extends Context.Service<
   Config,
   Simplify<
     & Partial<
@@ -101,6 +136,7 @@ export class Config extends ServiceMap.Service<
        * Defaults to `true`.
        */
       readonly strictJsonSchema?: boolean | undefined
+      readonly [x: string]: unknown
     }
   >
 >()("@effect/ai-openai-compat/OpenAiLanguageModel/Config") {}
@@ -110,7 +146,16 @@ export class Config extends ServiceMap.Service<
 // =============================================================================
 
 declare module "effect/unstable/ai/Prompt" {
+  /**
+   * OpenAI-compatible options for file prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface FilePartOptions extends ProviderOptions {
+    /**
+     * Provider-specific file options for OpenAI-compatible APIs.
+     */
     readonly openai?: {
       /**
        * The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`.
@@ -119,7 +164,16 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenAI-compatible options for reasoning prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ReasoningPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific reasoning options for OpenAI-compatible APIs.
+     */
     readonly openai?: {
       /**
        * The ID of the item to reference.
@@ -134,40 +188,67 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenAI-compatible options for assistant tool-call prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolCallPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific tool-call options for OpenAI-compatible APIs.
+     */
     readonly openai?: {
       /**
        * The ID of the item to reference.
        */
       readonly itemId?: string | null
       /**
-       * The status of item.
+       * The status to send for the tool-call item.
        */
       readonly status?: MessageStatus | null
     } | null
   }
 
+  /**
+   * OpenAI-compatible options for tool-result prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolResultPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific tool-result options for OpenAI-compatible APIs.
+     */
     readonly openai?: {
       /**
        * The ID of the item to reference.
        */
       readonly itemId?: string | null
       /**
-       * The status of item.
+       * The status to send for the tool-result item.
        */
       readonly status?: MessageStatus | null
     } | null
   }
 
+  /**
+   * OpenAI-compatible options for text prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface TextPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific text options for OpenAI-compatible APIs.
+     */
     readonly openai?: {
       /**
        * The ID of the item to reference.
        */
       readonly itemId?: string | null
       /**
-       * The status of item.
+       * The status to send for the text item.
        */
       readonly status?: MessageStatus | null
       /**
@@ -179,8 +260,20 @@ declare module "effect/unstable/ai/Prompt" {
 }
 
 declare module "effect/unstable/ai/Response" {
+  /**
+   * OpenAI-compatible metadata attached to a complete text response part.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface TextPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the text part.
+     */
     readonly openai?: {
+      /**
+       * The OpenAI item ID associated with the text part.
+       */
       readonly itemId?: string | null
       /**
        * If the model emits a refusal content part, the refusal explanation
@@ -189,7 +282,7 @@ declare module "effect/unstable/ai/Response" {
        */
       readonly refusal?: string | null
       /**
-       * The status of item.
+       * The status returned for the text item.
        */
       readonly status?: MessageStatus | null
       /**
@@ -199,55 +292,163 @@ declare module "effect/unstable/ai/Response" {
     }
   }
 
+  /**
+   * OpenAI-compatible metadata emitted when a streamed text part starts.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface TextStartPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the streamed text start.
+     */
     readonly openai?: {
+      /**
+       * 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.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface TextEndPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the streamed text end.
+     */
     readonly openai?: {
+      /**
+       * 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.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the reasoning part.
+     */
     readonly openai?: {
+      /**
+       * 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
     } | null
   }
 
+  /**
+   * OpenAI-compatible metadata emitted when a streamed reasoning part starts.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningStartPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the streamed reasoning start.
+     */
     readonly openai?: {
+      /**
+       * 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
     } | null
   }
 
+  /**
+   * OpenAI-compatible metadata emitted for a streamed reasoning delta.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningDeltaPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the streamed reasoning delta.
+     */
     readonly openai?: {
+      /**
+       * The OpenAI item ID associated with the reasoning part.
+       */
       readonly itemId?: string | null
     } | null
   }
 
+  /**
+   * OpenAI-compatible metadata emitted when a streamed reasoning part ends.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningEndPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the streamed reasoning end.
+     */
     readonly openai?: {
+      /**
+       * 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.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ToolCallPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the tool call.
+     */
     readonly openai?: {
+      /**
+       * The OpenAI item ID associated with the tool call.
+       */
       readonly itemId?: string | null
     } | null
   }
 
+  /**
+   * OpenAI-compatible metadata attached to document source citations.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface DocumentSourcePartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific citation metadata for OpenAI-compatible APIs.
+     */
     readonly openai?:
       | {
+        /**
+         * Identifies a citation to an uploaded file.
+         */
         readonly type: "file_citation"
         /**
          * The index of the file in the list of files.
@@ -259,6 +460,9 @@ declare module "effect/unstable/ai/Response" {
         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.
@@ -270,6 +474,9 @@ declare module "effect/unstable/ai/Response" {
         readonly fileId: string
       }
       | {
+        /**
+         * Identifies a citation to a file inside a container.
+         */
         readonly type: "container_file_citation"
         /**
          * The ID of the file.
@@ -283,8 +490,20 @@ declare module "effect/unstable/ai/Response" {
       | null
   }
 
+  /**
+   * OpenAI-compatible metadata attached to URL source citations.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface UrlSourcePartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific URL citation metadata for OpenAI-compatible APIs.
+     */
     readonly openai?: {
+      /**
+       * Identifies a citation to a URL.
+       */
       readonly type: "url_citation"
       /**
        * The index of the first character of the URL citation in the message.
@@ -297,8 +516,20 @@ declare module "effect/unstable/ai/Response" {
     } | null
   }
 
+  /**
+   * OpenAI-compatible metadata attached to finish response parts.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface FinishPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned when generation finishes.
+     */
     readonly openai?: {
+      /**
+       * The service tier reported by the OpenAI-compatible provider.
+       */
       readonly serviceTier?: "default" | "auto" | "flex" | "scale" | "priority" | null
     } | null
   }
@@ -309,31 +540,56 @@ declare module "effect/unstable/ai/Response" {
 // =============================================================================
 
 /**
- * @since 1.0.0
+ * 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
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const model = (
   model: string,
   config?: Omit<typeof Config.Service, "model">
 ): AiModel.Model<"openai", LanguageModel.LanguageModel, OpenAiClient> =>
-  AiModel.make("openai", layer({ model, config }))
+  AiModel.make("openai", model, layer({ model, config }))
 
 // TODO
 // /**
-//  * @since 1.0.0
+//  * @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", layerWithTokenizer({ model, config }))
+//   AiModel.make("openai", model, layerWithTokenizer({ model, config }))
 
 /**
- * Creates an OpenAI language model service.
+ * Creates an OpenAI-compatible `LanguageModel` service from a model identifier and optional request defaults.
+ *
+ * **When to use**
+ *
+ * Use when an Effect needs to construct a `LanguageModel.Service` value 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`
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.fnUntraced(function*({ model, config: providerConfig }: {
   readonly model: string
@@ -342,7 +598,7 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
   const client = yield* OpenAiClient
 
   const makeConfig = Effect.gen(function*() {
-    const services = yield* Effect.services<never>()
+    const services = yield* Effect.context<never>()
     return { model, ...providerConfig, ...services.mapUnsafe.get(Config.key) }
   })
 
@@ -370,8 +626,9 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
         config,
         options
       })
+      const { fileIdPrefixes: _fip, strictJsonSchema: _sjs, ...apiConfig } = config
       const request: CreateResponse = {
-        ...config,
+        ...apiConfig,
         input: messages,
         include: include.size > 0 ? Array.from(include) : null,
         text: {
@@ -386,6 +643,7 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
   )
 
   return yield* LanguageModel.make({
+    codecTransformer: toCodecOpenAI,
     generateText: Effect.fnUntraced(
       function*(options) {
         const config = yield* makeConfig
@@ -423,17 +681,23 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
           })
         )
     )
-  }).pipe(Effect.provideService(
-    LanguageModel.CurrentCodecTransformer,
-    toCodecOpenAI
-  ))
+  })
 })
 
 /**
- * Creates a layer for the OpenAI language model.
+ * 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
  *
- * @since 1.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (options: {
   readonly model: string
@@ -442,39 +706,99 @@ export const layer = (options: {
   Layer.effect(LanguageModel.LanguageModel, make(options))
 
 /**
- * Provides config overrides for OpenAI language model operations.
+ * 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
  *
- * @since 1.0.0
  * @category configuration
+ * @since 4.0.0
  */
 export const withConfigOverride: {
   /**
-   * Provides config overrides for OpenAI language model operations.
+   * 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
    *
-   * @since 1.0.0
    * @category configuration
+   * @since 4.0.0
    */
   (overrides: typeof Config.Service): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>
   /**
-   * Provides config overrides for OpenAI language model operations.
+   * 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
    *
-   * @since 1.0.0
    * @category configuration
+   * @since 4.0.0
    */
   <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service): Effect.Effect<A, E, Exclude<R, Config>>
 } = dual<
   /**
-   * Provides config overrides for OpenAI language model operations.
+   * 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
    *
-   * @since 1.0.0
    * @category configuration
+   * @since 4.0.0
    */
   (overrides: typeof Config.Service) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>,
   /**
-   * Provides config overrides for OpenAI language model operations.
+   * 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
    *
-   * @since 1.0.0
    * @category configuration
+   * @since 4.0.0
    */
   <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service) => Effect.Effect<A, E, Exclude<R, Config>>
 >(2, (self, overrides) =>
@@ -782,7 +1106,7 @@ const buildHttpRequestDetails = (
   method: request.method,
   url: request.url,
   urlParams: Array.from(request.urlParams),
-  hash: request.hash,
+  hash: Option.getOrUndefined(request.hash),
   headers: Redactable.redact(request.headers) as Record<string, string>
 })
 
@@ -1002,11 +1326,13 @@ const makeStreamResponse = Effect.fnUntraced(
           hasToolCalls = hasToolCalls || choice.delta.tool_calls.length > 0
           choice.delta.tool_calls.forEach((deltaTool, indexInChunk) => {
             const toolIndex = deltaTool.index ?? indexInChunk
-            const toolId = deltaTool.id ?? `${event.id}_tool_${toolIndex}`
+            const activeToolCall = activeToolCalls[toolIndex]
+            const toolId = activeToolCall?.id ?? deltaTool.id ?? `${event.id}_tool_${toolIndex}`
             const providerToolName = deltaTool.function?.name
-            const toolName = toolNameMapper.getCustomName(providerToolName ?? "unknown_tool")
+            const toolName = providerToolName !== undefined
+              ? toolNameMapper.getCustomName(providerToolName)
+              : activeToolCall?.name ?? toolNameMapper.getCustomName("unknown_tool")
             const argumentsDelta = deltaTool.function?.arguments ?? ""
-            const activeToolCall = activeToolCalls[toolIndex]
 
             if (Predicate.isUndefined(activeToolCall)) {
               activeToolCalls[toolIndex] = {
@@ -1169,7 +1495,7 @@ const prepareTools = Effect.fnUntraced(function*<Tools extends ReadonlyArray<Too
 
   // Convert the tools in the toolkit to the provider-defined format
   for (const tool of allowedTools) {
-    if (Tool.isUserDefined(tool)) {
+    if (Tool.isUserDefined(tool) || Tool.isDynamic(tool)) {
       const strict = Tool.getStrictMode(tool) ?? config.strictJsonSchema ?? true
       const parameters = yield* tryToolJsonSchema(tool, "prepareTools")
       tools.push({
@@ -1220,6 +1546,7 @@ const toChatCompletionsRequest = (payload: CreateResponse): CreateResponseReques
   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),
@@ -1231,12 +1558,54 @@ const toChatCompletionsRequest = (payload: CreateResponse): CreateResponseReques
       ? { 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)) {
+      customProperties[key] = value
+    }
+  }
+  return customProperties
+}
+
 const toChatResponseFormat = (
   format: TextResponseFormatConfiguration | undefined
 ): CreateResponseRequestJson["response_format"] | undefined => {