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

package/dist/OpenAiLanguageModel.d.ts

@@ -1,62 +1,88 @@
+/**
+ * The `OpenAiLanguageModel` module provides the OpenAI Responses API
+ * implementation of Effect AI's `LanguageModel` service. It translates Effect
+ * AI prompts, files, tools, structured output requests, reasoning metadata, and
+ * provider options into OpenAI response requests, then converts OpenAI
+ * responses and streams back into Effect AI response parts.
+ *
+ * **Mental model**
+ *
+ * `OpenAiClient` owns HTTP transport and provider calls. This module owns
+ * protocol translation: request assembly, tool choice conversion, structured
+ * output codecs, streaming event handling, response metadata, and GenAI
+ * telemetry annotations. {@link model}, {@link layer}, and {@link make} all
+ * build the same OpenAI-backed `LanguageModel.LanguageModel` service from a
+ * model id and optional request defaults.
+ *
+ * **Common tasks**
+ *
+ * - Provide an OpenAI-backed `LanguageModel.LanguageModel` from an existing
+ *   `OpenAiClient`
+ * - Generate text or stream text through Effect AI's provider-neutral language
+ *   model API
+ * - Use OpenAI provider metadata for files, reasoning items, tool calls, and
+ *   response parts
+ * - Scope Responses API defaults with {@link Config} and
+ *   {@link withConfigOverride}
+ *
+ * **Gotchas**
+ *
+ * - Some OpenAI model families receive system instructions as developer
+ *   messages because the Responses API treats them differently.
+ * - File prompt parts are sent either as provider file ids or as base64
+ *   content, depending on `fileIdPrefixes`.
+ * - Structured output and tool-call behavior depends on both Effect AI tool
+ *   definitions and OpenAI model capabilities.
+ *
+ * @since 4.0.0
+ */
+import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Schema from "effect/Schema";
-import * as ServiceMap from "effect/ServiceMap";
 import * as LanguageModel from "effect/unstable/ai/LanguageModel";
 import * as AiModel from "effect/unstable/ai/Model";
-import * as Generated from "./Generated.ts";
 import { OpenAiClient } from "./OpenAiClient.ts";
+import type * as OpenAiSchema from "./OpenAiSchema.ts";
 declare const ResponseModelIds: Schema.Literals<readonly ["o1-pro", "o1-pro-2025-03-19", "o3-pro", "o3-pro-2025-06-10", "o3-deep-research", "o3-deep-research-2025-06-26", "o4-mini-deep-research", "o4-mini-deep-research-2025-06-26", "computer-use-preview", "computer-use-preview-2025-03-11", "gpt-5-codex", "gpt-5-pro", "gpt-5-pro-2025-10-06", "gpt-5.1-codex-max"]>;
-declare const SharedModelIds: Schema.Literals<readonly ["gpt-5.2", "gpt-5.2-2025-12-11", "gpt-5.2-chat-latest", "gpt-5.2-pro", "gpt-5.2-pro-2025-12-11", "gpt-5.1", "gpt-5.1-2025-11-13", "gpt-5.1-codex", "gpt-5.1-mini", "gpt-5.1-chat-latest", "gpt-5", "gpt-5-mini", "gpt-5-nano", "gpt-5-2025-08-07", "gpt-5-mini-2025-08-07", "gpt-5-nano-2025-08-07", "gpt-5-chat-latest", "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "gpt-4.1-2025-04-14", "gpt-4.1-mini-2025-04-14", "gpt-4.1-nano-2025-04-14", "o4-mini", "o4-mini-2025-04-16", "o3", "o3-2025-04-16", "o3-mini", "o3-mini-2025-01-31", "o1", "o1-2024-12-17", "o1-preview", "o1-preview-2024-09-12", "o1-mini", "o1-mini-2024-09-12", "gpt-4o", "gpt-4o-2024-11-20", "gpt-4o-2024-08-06", "gpt-4o-2024-05-13", "gpt-4o-audio-preview", "gpt-4o-audio-preview-2024-10-01", "gpt-4o-audio-preview-2024-12-17", "gpt-4o-audio-preview-2025-06-03", "gpt-4o-mini-audio-preview", "gpt-4o-mini-audio-preview-2024-12-17", "gpt-4o-search-preview", "gpt-4o-mini-search-preview", "gpt-4o-search-preview-2025-03-11", "gpt-4o-mini-search-preview-2025-03-11", "chatgpt-4o-latest", "codex-mini-latest", "gpt-4o-mini", "gpt-4o-mini-2024-07-18", "gpt-4-turbo", "gpt-4-turbo-2024-04-09", "gpt-4-0125-preview", "gpt-4-turbo-preview", "gpt-4-1106-preview", "gpt-4-vision-preview", "gpt-4", "gpt-4-0314", "gpt-4-0613", "gpt-4-32k", "gpt-4-32k-0314", "gpt-4-32k-0613", "gpt-3.5-turbo", "gpt-3.5-turbo-16k", "gpt-3.5-turbo-0301", "gpt-3.5-turbo-0613", "gpt-3.5-turbo-1106", "gpt-3.5-turbo-0125", "gpt-3.5-turbo-16k-0613"]>;
+declare const SharedModelIds: Schema.Literals<readonly ["gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.4-mini-2026-03-17", "gpt-5.4-nano-2026-03-17", "gpt-5.3-chat-latest", "gpt-5.2", "gpt-5.2-2025-12-11", "gpt-5.2-chat-latest", "gpt-5.2-pro", "gpt-5.2-pro-2025-12-11", "gpt-5.1", "gpt-5.1-2025-11-13", "gpt-5.1-codex", "gpt-5.1-mini", "gpt-5.1-chat-latest", "gpt-5", "gpt-5-mini", "gpt-5-nano", "gpt-5-2025-08-07", "gpt-5-mini-2025-08-07", "gpt-5-nano-2025-08-07", "gpt-5-chat-latest", "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "gpt-4.1-2025-04-14", "gpt-4.1-mini-2025-04-14", "gpt-4.1-nano-2025-04-14", "o4-mini", "o4-mini-2025-04-16", "o3", "o3-2025-04-16", "o3-mini", "o3-mini-2025-01-31", "o1", "o1-2024-12-17", "o1-preview", "o1-preview-2024-09-12", "o1-mini", "o1-mini-2024-09-12", "gpt-4o", "gpt-4o-2024-11-20", "gpt-4o-2024-08-06", "gpt-4o-2024-05-13", "gpt-4o-audio-preview", "gpt-4o-audio-preview-2024-10-01", "gpt-4o-audio-preview-2024-12-17", "gpt-4o-audio-preview-2025-06-03", "gpt-4o-mini-audio-preview", "gpt-4o-mini-audio-preview-2024-12-17", "gpt-4o-search-preview", "gpt-4o-mini-search-preview", "gpt-4o-search-preview-2025-03-11", "gpt-4o-mini-search-preview-2025-03-11", "chatgpt-4o-latest", "codex-mini-latest", "gpt-4o-mini", "gpt-4o-mini-2024-07-18", "gpt-4-turbo", "gpt-4-turbo-2024-04-09", "gpt-4-0125-preview", "gpt-4-turbo-preview", "gpt-4-1106-preview", "gpt-4-vision-preview", "gpt-4", "gpt-4-0314", "gpt-4-0613", "gpt-4-32k", "gpt-4-32k-0314", "gpt-4-32k-0613", "gpt-3.5-turbo", "gpt-3.5-turbo-16k", "gpt-3.5-turbo-0301", "gpt-3.5-turbo-0613", "gpt-3.5-turbo-1106", "gpt-3.5-turbo-0125", "gpt-3.5-turbo-16k-0613"]>;
 /**
- * @since 1.0.0
+ * OpenAI model identifiers supported by the Responses API language model.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Model = typeof ResponseModelIds.Encoded | typeof SharedModelIds.Encoded;
 /**
  * Image detail level for vision requests.
  */
 type ImageDetail = "auto" | "low" | "high";
-declare const Config_base: ServiceMap.ServiceClass<Config, "@effect/ai-openai/OpenAiLanguageModel/Config", {
-    readonly metadata?: {} | null;
-    readonly top_logprobs?: number;
-    readonly user?: string | null;
-    readonly model?: string;
-    readonly instructions?: string | null;
-    readonly prompt?: {
-        readonly id: string;
-        readonly version?: string | null;
-        readonly variables?: {} | null;
-    } | null;
-    readonly temperature?: number | null;
-    readonly top_p?: number | null;
-    readonly background?: boolean | null;
-    readonly conversation?: string | {
-        readonly id: string;
-    } | null;
-    readonly service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null;
-    readonly include?: readonly ("file_search_call.results" | "web_search_call.results" | "web_search_call.action.sources" | "message.input_image.image_url" | "computer_call_output.output.image_url" | "code_interpreter_call.outputs" | "reasoning.encrypted_content" | "message.output_text.logprobs")[] | null;
-    readonly stream_options?: {
-        readonly include_obfuscation?: boolean;
-    } | null;
-    readonly max_output_tokens?: number | null;
+declare const Config_base: Context.ServiceClass<Config, "@effect/ai-openai/OpenAiLanguageModel/Config", {
+    readonly metadata?: {
+        readonly [x: string]: string;
+    } | undefined;
+    readonly top_logprobs?: number | undefined;
+    readonly user?: string | undefined;
+    readonly model?: string | undefined;
+    readonly temperature?: number | undefined;
+    readonly top_p?: number | undefined;
+    readonly background?: boolean | undefined;
+    readonly conversation?: string | undefined;
+    readonly modalities?: readonly ("text" | "audio")[] | undefined;
+    readonly service_tier?: string | undefined;
+    readonly seed?: number | undefined;
+    readonly include?: readonly ("web_search_call.action.sources" | "message.input_image.image_url" | "code_interpreter_call.outputs" | "reasoning.encrypted_content" | "message.output_text.logprobs")[] | undefined;
+    readonly instructions?: string | undefined;
+    readonly max_output_tokens?: number | undefined;
     readonly reasoning?: {
-        readonly summary?: "auto" | "concise" | "detailed" | null;
-        readonly effort?: "low" | "high" | "none" | "minimal" | "medium" | "xhigh" | null;
-        readonly generate_summary?: "auto" | "concise" | "detailed" | null;
-    } | null;
-    readonly truncation?: "auto" | "disabled" | null;
-    readonly parallel_tool_calls?: boolean | null;
-    readonly safety_identifier?: string | null;
-    readonly prompt_cache_key?: string | null;
-    readonly prompt_cache_retention?: "in-memory" | "24h" | null;
-    readonly store?: boolean | null;
-    readonly previous_response_id?: string | null;
-    readonly max_tool_calls?: number | null;
-    readonly context_management?: readonly {
-        readonly type: string;
-        readonly compact_threshold?: number | null;
-    }[] | null;
+        readonly effort?: "low" | "high" | "none" | "minimal" | "medium" | "xhigh" | undefined;
+        readonly summary?: "auto" | "concise" | "detailed" | undefined;
+        readonly generate_summary?: "auto" | "concise" | "detailed" | undefined;
+    } | undefined;
+    readonly truncation?: "auto" | "disabled" | undefined;
+    readonly store?: boolean | undefined;
+    readonly previous_response_id?: string | undefined;
+    readonly max_tool_calls?: number | undefined;
     readonly fileIdPrefixes?: readonly string[] | undefined;
     readonly text?: {
         /**
@@ -79,13 +105,34 @@ declare const Config_base: ServiceMap.ServiceClass<Config, "@effect/ai-openai/Op
 /**
  * Service definition for OpenAI language model configuration.
  *
- * @since 1.0.0
+ * **When to use**
+ *
+ * Use when you need to provide OpenAI Responses API request defaults through
+ * Effect context for language model operations.
+ *
+ * **Details**
+ *
+ * Config values are merged with the config object passed to `model`, `make`, or
+ * `layer`, with scoped context values taking precedence.
+ *
+ * @see {@link withConfigOverride} for scoping language model request overrides
+ *
  * @category services
+ * @since 4.0.0
  */
 export declare class Config extends Config_base {
 }
 declare module "effect/unstable/ai/Prompt" {
+    /**
+     * OpenAI-specific options for file prompt parts.
+     *
+     * @category request
+     * @since 4.0.0
+     */
     interface FilePartOptions extends ProviderOptions {
+        /**
+         * Provider-specific file options for the OpenAI Responses API.
+         */
         readonly openai?: {
             /**
              * The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`.
@@ -93,7 +140,16 @@ declare module "effect/unstable/ai/Prompt" {
             readonly imageDetail?: ImageDetail | null;
         } | null;
     }
+    /**
+     * OpenAI-specific options for reasoning prompt parts.
+     *
+     * @category request
+     * @since 4.0.0
+     */
     interface ReasoningPartOptions extends ProviderOptions {
+        /**
+         * Provider-specific reasoning options for the OpenAI Responses API.
+         */
         readonly openai?: {
             /**
              * The ID of the item to reference.
@@ -107,7 +163,16 @@ declare module "effect/unstable/ai/Prompt" {
             readonly encryptedContent?: string | null;
         } | null;
     }
+    /**
+     * OpenAI-specific options for assistant tool-call prompt parts.
+     *
+     * @category request
+     * @since 4.0.0
+     */
     interface ToolCallPartOptions extends ProviderOptions {
+        /**
+         * Provider-specific tool-call options for the OpenAI Responses API.
+         */
         readonly openai?: {
             /**
              * The ID of the item to reference.
@@ -116,14 +181,23 @@ declare module "effect/unstable/ai/Prompt" {
             /**
              * The status of item.
              */
-            readonly status?: typeof Generated.Message.Encoded["status"] | null;
+            readonly status?: typeof OpenAiSchema.MessageStatus.Encoded | null;
             /**
              * The ID of the approval request.
              */
             readonly approvalRequestId?: string | null;
         } | null;
     }
+    /**
+     * OpenAI-specific options for tool-result prompt parts.
+     *
+     * @category request
+     * @since 4.0.0
+     */
     interface ToolResultPartOptions extends ProviderOptions {
+        /**
+         * Provider-specific tool-result options for the OpenAI Responses API.
+         */
         readonly openai?: {
             /**
              * The ID of the item to reference.
@@ -132,14 +206,23 @@ declare module "effect/unstable/ai/Prompt" {
             /**
              * The status of item.
              */
-            readonly status?: typeof Generated.Message.Encoded["status"] | null;
+            readonly status?: typeof OpenAiSchema.MessageStatus.Encoded | null;
             /**
              * The ID of the approval request.
              */
             readonly approvalId?: string | null;
         } | null;
     }
+    /**
+     * OpenAI-specific options for text prompt parts.
+     *
+     * @category request
+     * @since 4.0.0
+     */
     interface TextPartOptions extends ProviderOptions {
+        /**
+         * Provider-specific text options for the OpenAI Responses API.
+         */
         readonly openai?: {
             /**
              * The ID of the item to reference.
@@ -148,17 +231,29 @@ declare module "effect/unstable/ai/Prompt" {
             /**
              * The status of item.
              */
-            readonly status?: typeof Generated.Message.Encoded["status"] | null;
+            readonly status?: typeof OpenAiSchema.MessageStatus.Encoded | null;
             /**
              * A list of annotations that apply to the output text.
              */
-            readonly annotations?: ReadonlyArray<typeof Generated.Annotation.Encoded> | null;
+            readonly annotations?: ReadonlyArray<typeof OpenAiSchema.Annotation.Encoded> | null;
         } | null;
     }
 }
 declare module "effect/unstable/ai/Response" {
+    /**
+     * OpenAI metadata attached to a complete text response part.
+     *
+     * @category response
+     * @since 4.0.0
+     */
     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
@@ -169,54 +264,162 @@ declare module "effect/unstable/ai/Response" {
             /**
              * The status of item.
              */
-            readonly status?: typeof Generated.Message.Encoded["status"] | null;
+            readonly status?: typeof OpenAiSchema.MessageStatus.Encoded | null;
             /**
              * The text content part annotations.
              */
-            readonly annotations?: ReadonlyArray<typeof Generated.Annotation.Encoded> | null;
+            readonly annotations?: ReadonlyArray<typeof OpenAiSchema.Annotation.Encoded> | null;
         };
     }
+    /**
+     * OpenAI metadata emitted when a streamed text part starts.
+     *
+     * @category response
+     * @since 4.0.0
+     */
     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 metadata emitted when a streamed text part ends.
+     *
+     * @category response
+     * @since 4.0.0
+     */
     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;
-            readonly annotations?: ReadonlyArray<typeof Generated.Annotation.Encoded> | null;
+            /**
+             * The annotations collected for the completed streamed text part.
+             */
+            readonly annotations?: ReadonlyArray<typeof OpenAiSchema.Annotation.Encoded> | null;
         } | null;
     }
+    /**
+     * OpenAI metadata attached to a complete reasoning response part.
+     *
+     * @category response
+     * @since 4.0.0
+     */
     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 metadata emitted when a streamed reasoning part starts.
+     *
+     * @category response
+     * @since 4.0.0
+     */
     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 metadata emitted for a streamed reasoning delta.
+     *
+     * @category response
+     * @since 4.0.0
+     */
     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 metadata emitted when a streamed reasoning part ends.
+     *
+     * @category response
+     * @since 4.0.0
+     */
     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 metadata attached to tool-call response parts.
+     *
+     * @category response
+     * @since 4.0.0
+     */
     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 metadata attached to document source citations.
+     *
+     * @category response
+     * @since 4.0.0
+     */
     interface DocumentSourcePartMetadata extends ProviderMetadata {
+        /**
+         * Provider-specific citation metadata for the OpenAI Responses API.
+         */
         readonly openai?: {
+            /**
+             * Identifies a citation to an uploaded file.
+             */
             readonly type: "file_citation";
             /**
              * The index of the file in the list of files.
@@ -227,6 +430,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.
@@ -237,6 +443,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.
@@ -248,8 +457,20 @@ declare module "effect/unstable/ai/Response" {
             readonly containerId: string;
         } | null;
     }
+    /**
+     * OpenAI metadata attached to URL source citations.
+     *
+     * @category response
+     * @since 4.0.0
+     */
     interface UrlSourcePartMetadata extends ProviderMetadata {
+        /**
+         * Provider-specific URL citation metadata for the OpenAI Responses API.
+         */
         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.
@@ -261,56 +482,157 @@ declare module "effect/unstable/ai/Response" {
             readonly endIndex: number;
         } | null;
     }
+    /**
+     * OpenAI metadata attached to finish response parts.
+     *
+     * @category response
+     * @since 4.0.0
+     */
     interface FinishPartMetadata extends ProviderMetadata {
+        /**
+         * Provider-specific metadata returned when generation finishes.
+         */
         readonly openai?: {
+            /**
+             * The service tier reported by OpenAI for the response.
+             */
             readonly serviceTier?: "default" | "auto" | "flex" | "scale" | "priority" | null;
         } | null;
     }
 }
 /**
- * @since 1.0.0
+ * Creates an OpenAI model descriptor that can be provided with
+ * `Effect.provide`.
+ *
+ * **When to use**
+ *
+ * Use when you want an OpenAI 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 declare const model: (model: (string & {}) | Model, config?: Omit<typeof Config.Service, "model">) => AiModel.Model<"openai", LanguageModel.LanguageModel, OpenAiClient>;
 /**
- * Creates an OpenAI language model service.
+ * Creates an OpenAI `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 `Effect.provide`
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const make: (args_0: {
     readonly model: (string & {}) | Model;
     readonly config?: Omit<typeof Config.Service, "model"> | undefined;
 }) => Effect.Effect<LanguageModel.Service, never, OpenAiClient>;
 /**
- * Creates a layer for the OpenAI language model.
+ * Creates a layer that provides the OpenAI `LanguageModel.LanguageModel`
+ * service.
+ *
+ * **When to use**
+ *
+ * Use when composing application layers and you want OpenAI to satisfy
+ * `LanguageModel.LanguageModel` while supplying `OpenAiClient` from another
+ * layer.
+ *
+ * **Details**
+ *
+ * The `config` option supplies request defaults for the selected model. Scoped
+ * values from `withConfigOverride` are merged when each request is built and
+ * take precedence over these defaults.
+ *
+ * @see {@link make} for constructing the language model service effectfully
+ * @see {@link model} for creating a model descriptor for `Effect.provide`
+ * @see {@link withConfigOverride} for scoped request configuration overrides
  *
- * @since 1.0.0
  * @category layers
+ * @since 4.0.0
  */
 export declare const layer: (options: {
     readonly model: (string & {}) | Model;
     readonly config?: Omit<typeof Config.Service, "model"> | undefined;
 }) => Layer.Layer<LanguageModel.LanguageModel, never, OpenAiClient>;
 /**
- * Provides config overrides for OpenAI language model operations.
+ * Provides scoped config overrides for OpenAI language model operations.
+ *
+ * **When to use**
+ *
+ * Use to apply OpenAI Responses API config overrides around one or more
+ * language model operations without changing the defaults passed to `model`,
+ * `make`, or `layer`.
+ *
+ * **Details**
+ *
+ * The override is dual, so it can be used in pipe form or as
+ * `withConfigOverride(effect, overrides)`. Overrides are merged with any
+ * existing `Config` service in the current context, and the override values take
+ * precedence.
+ *
+ * @see {@link Config} for the scoped configuration service consumed by this function
  *
- * @since 1.0.0
  * @category configuration
+ * @since 4.0.0
  */
 export declare const withConfigOverride: {
     /**
-     * Provides config overrides for OpenAI language model operations.
+     * Provides scoped config overrides for OpenAI language model operations.
+     *
+     * **When to use**
+     *
+     * Use to apply OpenAI Responses API config overrides around one or more
+     * language model operations without changing the defaults passed to `model`,
+     * `make`, or `layer`.
+     *
+     * **Details**
+     *
+     * The override is dual, so it can be used in pipe form or as
+     * `withConfigOverride(effect, overrides)`. Overrides are merged with any
+     * existing `Config` service in the current context, and the override values take
+     * precedence.
+     *
+     * @see {@link Config} for the scoped configuration service consumed by this function
      *
-     * @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 language model operations.
+     *
+     * **When to use**
+     *
+     * Use to apply OpenAI Responses API config overrides around one or more
+     * language model operations without changing the defaults passed to `model`,
+     * `make`, or `layer`.
+     *
+     * **Details**
+     *
+     * The override is dual, so it can be used in pipe form or as
+     * `withConfigOverride(effect, overrides)`. Overrides are merged with any
+     * existing `Config` service in the current context, and the override values take
+     * precedence.
+     *
+     * @see {@link Config} for the scoped configuration service consumed by this function
      *
-     * @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>>;
 };