@effect/ai-openai 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/index.js

@@ -1,9 +1,9 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 // @barrel: Auto-generated exports. Do not edit manually.
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as Generated from "./Generated.js";
 /**
@@ -12,15 +12,31 @@ export * as Generated from "./Generated.js";
  * Provides a type-safe, Effect-based client for OpenAI operations including
  * completions, embeddings, and streaming responses.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenAiClient from "./OpenAiClient.js";
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenAiClientGenerated from "./OpenAiClientGenerated.js";
 /**
- * @since 1.0.0
+ * The `OpenAiConfig` module provides contextual configuration for the
+ * `@effect/ai-openai` integration. It is used to customize how OpenAI clients
+ * are built and interpreted without threading configuration through every API
+ * call manually.
+ *
+ * The primary use case is installing an HTTP client transform with
+ * {@link withClientTransform}. This lets applications adapt the underlying
+ * OpenAI HTTP client for cross-cutting concerns such as custom middleware,
+ * instrumentation, proxying, or request policy changes while keeping the
+ * OpenAI service APIs unchanged.
+ *
+ * Configuration is scoped through Effect's context, so transforms only apply to
+ * the effect they are provided to and anything evaluated inside that scope.
+ * When multiple transforms are needed, compose them into a single
+ * `HttpClient => HttpClient` function before providing the configuration.
+ *
+ * @since 4.0.0
  */
 export * as OpenAiConfig from "./OpenAiConfig.js";
 /**
@@ -28,7 +44,7 @@ export * as OpenAiConfig from "./OpenAiConfig.js";
  *
  * Provides an EmbeddingModel implementation for OpenAI's embeddings API.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenAiEmbeddingModel from "./OpenAiEmbeddingModel.js";
 /**
@@ -37,7 +53,7 @@ export * as OpenAiEmbeddingModel from "./OpenAiEmbeddingModel.js";
  * Provides OpenAI-specific metadata fields for AI error types through module
  * augmentation, enabling typed access to OpenAI error details.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenAiError from "./OpenAiError.js";
 /**
@@ -46,13 +62,13 @@ export * as OpenAiError from "./OpenAiError.js";
  * Provides a LanguageModel implementation for OpenAI's responses API,
  * supporting text generation, structured output, tool calling, and streaming.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenAiLanguageModel from "./OpenAiLanguageModel.js";
 /**
  * Minimal local OpenAI schemas used by the handwritten Responses client path.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenAiSchema from "./OpenAiSchema.js";
 /**
@@ -62,7 +78,7 @@ export * as OpenAiSchema from "./OpenAiSchema.js";
  * semantic conventions, extending the base GenAI attributes with OpenAI-specific
  * request and response metadata.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenAiTelemetry from "./OpenAiTelemetry.js";
 /**
@@ -71,7 +87,7 @@ export * as OpenAiTelemetry from "./OpenAiTelemetry.js";
  * Provides tools that are natively supported by OpenAI's API, including
  * code interpreter, file search, and web search functionality.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenAiTool from "./OpenAiTool.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["Generated","OpenAiClient","OpenAiClientGenerated","OpenAiConfig","OpenAiEmbeddingModel","OpenAiError","OpenAiLanguageModel","OpenAiSchema","OpenAiTelemetry","OpenAiTool"],"sources":["../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAIA;AAEA;;;AAGA,OAAO,KAAKA,SAAS,MAAM,gBAAgB;AAE3C;;;;;;;;AAQA,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AAEjD;;;AAGA,OAAO,KAAKC,qBAAqB,MAAM,4BAA4B;AAEnE;;;AAGA,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AAEjD;;;;;;;AAOA,OAAO,KAAKC,oBAAoB,MAAM,2BAA2B;AAEjE;;;;;;;;AAQA,OAAO,KAAKC,WAAW,MAAM,kBAAkB;AAE/C;;;;;;;;AAQA,OAAO,KAAKC,mBAAmB,MAAM,0BAA0B;AAE/D;;;;;AAKA,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AAEjD;;;;;;;;;AASA,OAAO,KAAKC,eAAe,MAAM,sBAAsB;AAEvD;;;;;;;;AAQA,OAAO,KAAKC,UAAU,MAAM,iBAAiB","ignoreList":[]}
+{"version":3,"file":"index.js","names":["Generated","OpenAiClient","OpenAiClientGenerated","OpenAiConfig","OpenAiEmbeddingModel","OpenAiError","OpenAiLanguageModel","OpenAiSchema","OpenAiTelemetry","OpenAiTool"],"sources":["../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAIA;AAEA;;;AAGA,OAAO,KAAKA,SAAS,MAAM,gBAAgB;AAE3C;;;;;;;;AAQA,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AAEjD;;;AAGA,OAAO,KAAKC,qBAAqB,MAAM,4BAA4B;AAEnE;;;;;;;;;;;;;;;;;;;AAmBA,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AAEjD;;;;;;;AAOA,OAAO,KAAKC,oBAAoB,MAAM,2BAA2B;AAEjE;;;;;;;;AAQA,OAAO,KAAKC,WAAW,MAAM,kBAAkB;AAE/C;;;;;;;;AAQA,OAAO,KAAKC,mBAAmB,MAAM,0BAA0B;AAE/D;;;;;AAKA,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AAEjD;;;;;;;;;AASA,OAAO,KAAKC,eAAe,MAAM,sBAAsB;AAEvD;;;;;;;;AAQA,OAAO,KAAKC,UAAU,MAAM,iBAAiB","ignoreList":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect/ai-openai",
-  "version": "4.0.0-beta.66",
+  "version": "4.0.0-beta.68",
   "type": "module",
   "license": "MIT",
   "description": "An OpenAI provider integration for Effect AI SDK",
@@ -43,10 +43,10 @@
     "provenance": true
   },
   "devDependencies": {
-    "effect": "^4.0.0-beta.66"
+    "effect": "^4.0.0-beta.68"
   },
   "peerDependencies": {
-    "effect": "^4.0.0-beta.66"
+    "effect": "^4.0.0-beta.68"
   },
   "scripts": {
     "codegen": "effect-utils codegen",

package/src/Generated.ts

@@ -1,5 +1,5 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 import * as Data from "effect/Data"

package/src/OpenAiClient.ts

@@ -4,7 +4,7 @@
  * Provides a type-safe, Effect-based client for OpenAI operations including
  * completions, embeddings, and streaming responses.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 import * as Array from "effect/Array"
 import type * as Config from "effect/Config"
@@ -39,10 +39,13 @@ import * as OpenAiSchema from "./OpenAiSchema.ts"
 // =============================================================================
 
 /**
- * The OpenAI client interface.
+ * Effect service interface for the handwritten OpenAI client.
+ *
+ * **Details**
+ * Provides the configured HTTP client plus helpers for Responses API calls, streaming Responses events, and embeddings. Transport and schema decoding failures are mapped to `AiError`.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Service {
   /**
@@ -88,8 +91,8 @@ export interface Service {
 /**
  * Service identifier for the OpenAI client.
  *
- * @since 1.0.0
- * @category service
+ * @category services
+ * @since 4.0.0
  */
 export class OpenAiClient extends Context.Service<OpenAiClient, Service>()(
   "@effect/ai-openai/OpenAiClient"
@@ -102,8 +105,8 @@ export class OpenAiClient extends Context.Service<OpenAiClient, Service>()(
 /**
  * Options for configuring the OpenAI client.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type Options = {
   /**
@@ -146,8 +149,8 @@ const RedactedOpenAiHeaders = {
 /**
  * Creates an OpenAI client service with the given options.
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.fnUntraced(
   function*(
@@ -298,8 +301,8 @@ export const make = Effect.fnUntraced(
 /**
  * Creates a layer for the OpenAI client with the given options.
  *
- * @since 1.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (options: Options): Layer.Layer<OpenAiClient, never, HttpClient.HttpClient> =>
   Layer.effect(OpenAiClient, make(options))
@@ -308,8 +311,8 @@ export const layer = (options: Options): Layer.Layer<OpenAiClient, never, HttpCl
  * Creates a layer for the OpenAI client, loading the requisite configuration
  * via Effect's `Config` module.
  *
- * @since 1.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layerConfig = (options?: {
   /**
@@ -367,14 +370,18 @@ export const layerConfig = (options?: {
 // =============================================================================
 
 /**
- * @since 1.0.0
+ * Response stream event emitted by the OpenAI Responses API.
+ *
  * @category Events
+ * @since 4.0.0
  */
 export type ResponseStreamEvent = typeof OpenAiSchema.ResponseStreamEvent.Type
 
 /**
- * @since 1.0.0
+ * Service for creating OpenAI response streams over a WebSocket connection.
+ *
  * @category Websocket mode
+ * @since 4.0.0
  */
 export class OpenAiSocket extends Context.Service<OpenAiSocket, {
   /**
@@ -587,8 +594,8 @@ const decodeEvent = Schema.decodeUnknownSync(Schema.fromJsonString(AllEvents))
  * This is because it needs to use non-standard options for setting the
  * Authorization header.
  *
- * @since 1.0.0
  * @category Websocket mode
+ * @since 4.0.0
  */
 export const withWebSocketMode = <A, E, R>(
   effect: Effect.Effect<A, E, R>
@@ -615,8 +622,8 @@ export const withWebSocketMode = <A, E, R>(
  * This is because it needs to use non-standard options for setting the
  * Authorization header.
  *
- * @since 1.0.0
  * @category Websocket mode
+ * @since 4.0.0
  */
 export const layerWebSocketMode: Layer.Layer<
   OpenAiSocket | ResponseIdTracker.ResponseIdTracker,

package/src/OpenAiClientGenerated.ts

@@ -1,5 +1,5 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 import * as Array from "effect/Array"
 import type * as Config from "effect/Config"
@@ -23,7 +23,7 @@ import { OpenAiConfig } from "./OpenAiConfig.ts"
 /**
  * Service identifier for the generated OpenAI client.
  *
- * @since 1.0.0
+ * @since 4.0.0
  * @category service
  */
 export class OpenAiClientGenerated extends Context.Service<OpenAiClientGenerated, Generated.OpenAiClient>()(
@@ -37,7 +37,7 @@ export class OpenAiClientGenerated extends Context.Service<OpenAiClientGenerated
 /**
  * Options for configuring the generated OpenAI client.
  *
- * @since 1.0.0
+ * @since 4.0.0
  * @category models
  */
 export type Options = {
@@ -81,7 +81,7 @@ const RedactedOpenAiHeaders = {
 /**
  * Creates a generated OpenAI client service with the given options.
  *
- * @since 1.0.0
+ * @since 4.0.0
  * @category constructors
  */
 export const make = Effect.fnUntraced(
@@ -137,7 +137,7 @@ export const make = Effect.fnUntraced(
 /**
  * Creates a layer for the generated OpenAI client with the given options.
  *
- * @since 1.0.0
+ * @since 4.0.0
  * @category layers
  */
 export const layer = (options: Options): Layer.Layer<OpenAiClientGenerated, never, HttpClient.HttpClient> =>
@@ -147,7 +147,7 @@ export const layer = (options: Options): Layer.Layer<OpenAiClientGenerated, neve
  * Creates a layer for the generated OpenAI client, loading the requisite
  * configuration via Effect's `Config` module.
  *
- * @since 1.0.0
+ * @since 4.0.0
  * @category layers
  */
 export const layerConfig = (options?: {

package/src/OpenAiConfig.ts

@@ -1,5 +1,21 @@
 /**
- * @since 1.0.0
+ * The `OpenAiConfig` module provides contextual configuration for the
+ * `@effect/ai-openai` integration. It is used to customize how OpenAI clients
+ * are built and interpreted without threading configuration through every API
+ * call manually.
+ *
+ * The primary use case is installing an HTTP client transform with
+ * {@link withClientTransform}. This lets applications adapt the underlying
+ * OpenAI HTTP client for cross-cutting concerns such as custom middleware,
+ * instrumentation, proxying, or request policy changes while keeping the
+ * OpenAI service APIs unchanged.
+ *
+ * Configuration is scoped through Effect's context, so transforms only apply to
+ * the effect they are provided to and anything evaluated inside that scope.
+ * When multiple transforms are needed, compose them into a single
+ * `HttpClient => HttpClient` function before providing the configuration.
+ *
+ * @since 4.0.0
  */
 import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
@@ -7,15 +23,20 @@ import { dual } from "effect/Function"
 import type { HttpClient } from "effect/unstable/http/HttpClient"
 
 /**
- * @since 1.0.0
+ * Context service carrying scoped OpenAI configuration for provider
+ * operations.
+ *
  * @category services
+ * @since 4.0.0
  */
 export class OpenAiConfig extends Context.Service<
   OpenAiConfig,
   OpenAiConfig.Service
 >()("@effect/ai-openai/OpenAiConfig") {
   /**
-   * @since 1.0.0
+   * Gets the configured OpenAI service from the current context when present.
+   *
+   * @since 4.0.0
    */
   static readonly getOrUndefined: Effect.Effect<typeof OpenAiConfig.Service | undefined> = Effect.map(
     Effect.context<never>(),
@@ -24,12 +45,17 @@ export class OpenAiConfig extends Context.Service<
 }
 
 /**
- * @since 1.0.0
+ * Types used by the `OpenAiConfig` context service.
+ *
+ * @since 4.0.0
  */
 export declare namespace OpenAiConfig {
   /**
-   * @since 1.0.
+   * Configuration values read by OpenAI provider operations when executing
+   * requests.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface Service {
     readonly transformClient?: ((client: HttpClient) => HttpClient) | undefined
@@ -37,18 +63,27 @@ export declare namespace OpenAiConfig {
 }
 
 /**
- * @since 1.0.0
+ * Provides a scoped transform for the OpenAI HTTP client used by provider
+ * operations.
+ *
  * @category configuration
+ * @since 4.0.0
  */
 export const withClientTransform: {
   /**
-   * @since 1.0.0
+   * Provides a scoped transform for the OpenAI HTTP client used by provider
+   * operations.
+   *
    * @category configuration
+   * @since 4.0.0
    */
   (transform: (client: HttpClient) => HttpClient): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
   /**
-   * @since 1.0.0
+   * Provides a scoped transform for the OpenAI HTTP client used by provider
+   * operations.
+   *
    * @category configuration
+   * @since 4.0.0
    */
   <A, E, R>(
     self: Effect.Effect<A, E, R>,

package/src/OpenAiEmbeddingModel.ts

@@ -3,7 +3,7 @@
  *
  * Provides an EmbeddingModel implementation for OpenAI's embeddings API.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
@@ -17,16 +17,18 @@ import { OpenAiClient } from "./OpenAiClient.ts"
 import type * as OpenAiSchema from "./OpenAiSchema.ts"
 
 /**
- * @since 1.0.0
+ * Model identifiers supported by OpenAI's embeddings API.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Model = "text-embedding-ada-002" | "text-embedding-3-small" | "text-embedding-3-large"
 
 /**
  * Service definition for OpenAI embedding model configuration.
  *
- * @since 1.0.0
  * @category services
+ * @since 4.0.0
  */
 export class Config extends Context.Service<
   Config,
@@ -44,8 +46,10 @@ export class Config extends Context.Service<
 >()("@effect/ai-openai/OpenAiEmbeddingModel/Config") {}
 
 /**
- * @since 1.0.0
+ * Creates an `AiModel` for an OpenAI embedding model with its configured vector dimensions.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const model = (
   model: (string & {}) | Model,
@@ -72,8 +76,8 @@ export const model = (
 /**
  * Creates an OpenAI embedding model service.
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.fnUntraced(function*({ model, config: providerConfig }: {
   readonly model: (string & {}) | Model
@@ -98,8 +102,8 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
 /**
  * Creates a layer for the OpenAI embedding model.
  *
- * @since 1.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (options: {
   readonly model: (string & {}) | Model
@@ -110,37 +114,37 @@ export const layer = (options: {
 /**
  * Provides config overrides for OpenAI embedding model operations.
  *
- * @since 1.0.0
  * @category configuration
+ * @since 4.0.0
  */
 export const withConfigOverride: {
   /**
    * Provides config overrides for OpenAI embedding model operations.
    *
-   * @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 embedding model operations.
    *
-   * @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 embedding model operations.
    *
-   * @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 embedding model operations.
    *
-   * @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) =>

package/src/OpenAiError.ts

@@ -4,14 +4,14 @@
  * Provides OpenAI-specific metadata fields for AI error types through module
  * augmentation, enabling typed access to OpenAI error details.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 /**
  * OpenAI-specific error metadata fields.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type OpenAiErrorMetadata = {
   /**
@@ -34,8 +34,8 @@ export type OpenAiErrorMetadata = {
  * Extends base error metadata with rate limit specific information from
  * OpenAI's rate limit headers.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type OpenAiRateLimitMetadata = OpenAiErrorMetadata & {
   /**
@@ -57,43 +57,164 @@ export type OpenAiRateLimitMetadata = OpenAiErrorMetadata & {
 }
 
 declare module "effect/unstable/ai/AiError" {
+  /**
+   * OpenAI metadata attached to `RateLimitError` values.
+   *
+   * Captures OpenAI error details together with rate limit header information
+   * from responses where the provider rejected the request because a limit was
+   * reached.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface RateLimitErrorMetadata {
+    /**
+     * OpenAI-specific details for the rate limit response.
+     */
     readonly openai?: OpenAiRateLimitMetadata | null
   }
 
+  /**
+   * OpenAI metadata attached to `QuotaExhaustedError` values.
+   *
+   * Preserves provider error details for failures caused by exhausted account,
+   * billing, or usage quota.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface QuotaExhaustedErrorMetadata {
+    /**
+     * OpenAI-specific details for the quota exhaustion response.
+     */
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * OpenAI metadata attached to `AuthenticationError` values.
+   *
+   * Preserves provider error details for failed API key, authorization, or
+   * permission checks.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface AuthenticationErrorMetadata {
+    /**
+     * OpenAI-specific details for the authentication failure.
+     */
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * OpenAI metadata attached to `ContentPolicyError` values.
+   *
+   * Preserves provider error details when OpenAI rejects input or output because
+   * it violates a content policy.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface ContentPolicyErrorMetadata {
+    /**
+     * OpenAI-specific details for the content policy response.
+     */
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * OpenAI metadata attached to `InvalidRequestError` values.
+   *
+   * Preserves provider error details for malformed requests, unsupported
+   * parameters, or other request validation failures reported by OpenAI.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface InvalidRequestErrorMetadata {
+    /**
+     * OpenAI-specific details for the invalid request response.
+     */
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * OpenAI metadata attached to `InternalProviderError` values.
+   *
+   * Preserves provider error details for OpenAI-side failures such as transient
+   * server errors.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface InternalProviderErrorMetadata {
+    /**
+     * OpenAI-specific details for the internal provider response.
+     */
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * OpenAI metadata attached to `InvalidOutputError` values.
+   *
+   * Preserves provider error details when an OpenAI response cannot be parsed or
+   * validated as the expected output.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface InvalidOutputErrorMetadata {
+    /**
+     * OpenAI-specific details for the invalid output response.
+     */
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * OpenAI metadata attached to `StructuredOutputError` values.
+   *
+   * Preserves provider error details when OpenAI returns content that does not
+   * satisfy the requested structured output schema.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface StructuredOutputErrorMetadata {
+    /**
+     * OpenAI-specific details for the structured output failure.
+     */
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * OpenAI metadata attached to `UnsupportedSchemaError` values.
+   *
+   * Preserves provider error details when an unsupported schema failure is
+   * associated with an OpenAI response.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface UnsupportedSchemaErrorMetadata {
+    /**
+     * OpenAI-specific details for the unsupported schema failure.
+     */
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * OpenAI metadata attached to `UnknownError` values.
+   *
+   * Preserves provider error details for OpenAI failures that do not map cleanly
+   * to a more specific AI error category.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
   export interface UnknownErrorMetadata {
+    /**
+     * OpenAI-specific details for the unclassified provider failure.
+     */
     readonly openai?: OpenAiErrorMetadata | null
   }
 }