@effect/ai-openai 4.0.0-beta.70 → 4.0.0-beta.72

package/dist/index.js

@@ -3,15 +3,10 @@
  */
 // @barrel: Auto-generated exports. Do not edit manually.
 /**
- * @since 4.0.0
+ * @since 1.0.0
  */
 export * as Generated from "./Generated.js";
 /**
- * OpenAI Client module for interacting with OpenAI's API.
- *
- * Provides a type-safe, Effect-based client for OpenAI operations including
- * completions, embeddings, and streaming responses.
- *
  * @since 4.0.0
  */
 export * as OpenAiClient from "./OpenAiClient.js";
@@ -20,73 +15,30 @@ export * as OpenAiClient from "./OpenAiClient.js";
  */
 export * as OpenAiClientGenerated from "./OpenAiClientGenerated.js";
 /**
- * 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";
 /**
- * OpenAI Embedding Model implementation.
- *
- * Provides an EmbeddingModel implementation for OpenAI's embeddings API.
- *
  * @since 4.0.0
  */
 export * as OpenAiEmbeddingModel from "./OpenAiEmbeddingModel.js";
 /**
- * OpenAI error metadata augmentation.
- *
- * Provides OpenAI-specific metadata fields for AI error types through module
- * augmentation, enabling typed access to OpenAI error details.
- *
  * @since 4.0.0
  */
 export * as OpenAiError from "./OpenAiError.js";
 /**
- * OpenAI Language Model implementation.
- *
- * Provides a LanguageModel implementation for OpenAI's responses API,
- * supporting text generation, structured output, tool calling, and streaming.
- *
  * @since 4.0.0
  */
 export * as OpenAiLanguageModel from "./OpenAiLanguageModel.js";
 /**
- * Minimal local OpenAI schemas used by the handwritten Responses client path.
- *
  * @since 4.0.0
  */
 export * as OpenAiSchema from "./OpenAiSchema.js";
 /**
- * OpenAI telemetry attributes for OpenTelemetry integration.
- *
- * Provides OpenAI-specific GenAI telemetry attributes following OpenTelemetry
- * semantic conventions, extending the base GenAI attributes with OpenAI-specific
- * request and response metadata.
- *
  * @since 4.0.0
  */
 export * as OpenAiTelemetry from "./OpenAiTelemetry.js";
 /**
- * OpenAI provider-defined tools for use with the LanguageModel.
- *
- * Provides tools that are natively supported by OpenAI's API, including
- * code interpreter, file search, and web search functionality.
- *
  * @since 4.0.0
  */
 export * as OpenAiTool from "./OpenAiTool.js";

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;;;;;;;;;;;;;;;;;;;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":[]}
+{"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;;;AAGA,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AAEjD;;;AAGA,OAAO,KAAKC,qBAAqB,MAAM,4BAA4B;AAEnE;;;AAGA,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AAEjD;;;AAGA,OAAO,KAAKC,oBAAoB,MAAM,2BAA2B;AAEjE;;;AAGA,OAAO,KAAKC,WAAW,MAAM,kBAAkB;AAE/C;;;AAGA,OAAO,KAAKC,mBAAmB,MAAM,0BAA0B;AAE/D;;;AAGA,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AAEjD;;;AAGA,OAAO,KAAKC,eAAe,MAAM,sBAAsB;AAEvD;;;AAGA,OAAO,KAAKC,UAAU,MAAM,iBAAiB","ignoreList":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect/ai-openai",
-  "version": "4.0.0-beta.70",
+  "version": "4.0.0-beta.72",
   "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.70"
+    "effect": "^4.0.0-beta.72"
   },
   "peerDependencies": {
-    "effect": "^4.0.0-beta.70"
+    "effect": "^4.0.0-beta.72"
   },
   "scripts": {
     "codegen": "effect-utils codegen",

package/src/OpenAiClient.ts

@@ -1,8 +1,36 @@
 /**
- * OpenAI Client module for interacting with OpenAI's API.
+ * The `OpenAiClient` module provides the handwritten Effect service used by
+ * the OpenAI integration for Responses API and embedding requests. It builds on
+ * the Effect HTTP client, applies OpenAI authentication and organization or
+ * project headers, decodes the minimal schemas needed by higher-level modules,
+ * and maps transport or decoding failures into `AiError`.
  *
- * Provides a type-safe, Effect-based client for OpenAI operations including
- * completions, embeddings, and streaming responses.
+ * The service exposes a configured HTTP client plus helpers for non-streaming
+ * responses, server-sent event response streams, and embeddings. It also
+ * includes WebSocket mode for response streams when an application wants to use
+ * OpenAI's WebSocket transport instead of the default SSE path.
+ *
+ * **Common tasks**
+ *
+ * - Construct the service directly with {@link make}
+ * - Provide the service with {@link layer} or load settings from `Config` with
+ *   {@link layerConfig}
+ * - Call `createResponse`, `createResponseStream`, or `createEmbedding` from
+ *   code that depends on the `OpenAiClient` service
+ * - Enable WebSocket streaming around an effect with {@link withWebSocketMode}
+ *   or through layers with {@link layerWebSocketMode}
+ *
+ * **Gotchas**
+ *
+ * - The default base URL is `https://api.openai.com/v1`; set `apiUrl` for
+ *   proxies, local gateways, or compatible deployments.
+ * - A constructor `transformClient` is applied when the service is built, while
+ *   scoped `OpenAiConfig` transforms are applied by request helpers when they
+ *   run.
+ * - WebSocket mode requires a supported `Socket.WebSocketConstructor` layer and
+ *   serializes response streams through the shared socket service.
+ * - This module is intentionally narrower than the generated OpenAI client; use
+ *   `OpenAiClientGenerated` for direct access to generated endpoint helpers.
  *
  * @since 4.0.0
  */
@@ -90,7 +118,16 @@ export interface Service {
 // =============================================================================
 
 /**
- * Service identifier for the OpenAI client.
+ * Service tag for the OpenAI client.
+ *
+ * **When to use**
+ *
+ * Use when accessing or providing the OpenAI client service through Effect's
+ * context.
+ *
+ * @see {@link make} for constructing an OpenAI client effectfully
+ * @see {@link layer} for providing a client from explicit options
+ * @see {@link layerConfig} for providing a client from `Config`
  *
  * @category services
  * @since 4.0.0
@@ -150,6 +187,26 @@ const RedactedOpenAiHeaders = {
 /**
  * Creates an OpenAI client service with the given options.
  *
+ * **When to use**
+ *
+ * Use to construct the OpenAI client service inside an effect when you need the
+ * service value directly.
+ *
+ * **Details**
+ *
+ * The returned service uses the current `HttpClient`, prepends `apiUrl` or
+ * `https://api.openai.com/v1`, adds the bearer token and optional OpenAI
+ * organization/project headers, accepts JSON responses, filters for successful
+ * HTTP statuses, and applies `transformClient` when provided.
+ *
+ * **Gotchas**
+ *
+ * A scoped `OpenAiConfig.withClientTransform` is applied when request helpers
+ * run, after the `transformClient` option supplied to `make`.
+ *
+ * @see {@link layer} for providing this client from explicit options
+ * @see {@link layerConfig} for loading client settings from `Config`
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -302,6 +359,14 @@ export const make = Effect.fnUntraced(
 /**
  * Creates a layer for the OpenAI client with the given options.
  *
+ * **When to use**
+ *
+ * Use when you already have explicit `Options` values, such as an API key or
+ * custom API URL, and want to provide `OpenAiClient` as a `Layer`.
+ *
+ * @see {@link make} for constructing the client service effectfully
+ * @see {@link layerConfig} for loading client settings from `Config`
+ *
  * @category layers
  * @since 4.0.0
  */
@@ -309,8 +374,21 @@ export const layer = (options: Options): Layer.Layer<OpenAiClient, never, HttpCl
   Layer.effect(OpenAiClient, make(options))
 
 /**
- * Creates a layer for the OpenAI client, loading the requisite configuration
- * via Effect's `Config` module.
+ * Creates a layer for the OpenAI client from provided `Config` values.
+ *
+ * **When to use**
+ *
+ * Use when client settings should be read from Effect `Config` values while
+ * providing `OpenAiClient` as a `Layer`.
+ *
+ * **Details**
+ *
+ * Only config values supplied in `options` are loaded. Omitted fields are
+ * passed to `make` as `undefined`, and `transformClient` is forwarded as a
+ * plain option.
+ *
+ * @see {@link make} for constructing the client service effectfully
+ * @see {@link layer} for providing the client from already-resolved options
  *
  * @category layers
  * @since 4.0.0
@@ -381,6 +459,25 @@ export type ResponseStreamEvent = typeof OpenAiSchema.ResponseStreamEvent.Type
 /**
  * Service for creating OpenAI response streams over a WebSocket connection.
  *
+ * **When to use**
+ *
+ * Use when code needs direct access to the WebSocket-backed response streaming
+ * service rather than wrapping an effect with WebSocket mode.
+ *
+ * **Details**
+ *
+ * `createResponseStream` sends a `response.create` message over the WebSocket
+ * connection and returns an HTTP response together with a stream of
+ * `ResponseStreamEvent` values.
+ *
+ * **Gotchas**
+ *
+ * WebSocket response streams are serialized to one request at a time by the
+ * shared socket service.
+ *
+ * @see {@link withWebSocketMode} for enabling WebSocket mode for one effect
+ * @see {@link layerWebSocketMode} for providing WebSocket mode through a layer
+ *
  * @category Websocket mode
  * @since 4.0.0
  */
@@ -470,7 +567,7 @@ const makeSocket = Effect.gen(function*() {
           const event = decodeEvent(text)
           if (event.type === "error" && "status" in event) {
             const status = Number(event.status)
-            const error = "error" in event ? event.error : event
+            const error = "error" in event ? event.error as typeof ErrorEvent.Type.error : event
             const json = JSON.stringify(error)
             return Effect.fail(
               AiError.make({
@@ -478,7 +575,7 @@ const makeSocket = Effect.gen(function*() {
                 method: "createResponseStream",
                 reason: AiError.reasonFromHttpStatus({
                   description: json,
-                  status: isNaN(status) ? 500 : status,
+                  status: isNaN(status) ? errorTypeToStatus[error.type] ?? 500 : status,
                   metadata: error as any,
                   http: {
                     body: json,
@@ -581,11 +678,24 @@ const ErrorEvent = Schema.Struct({
   })
 })
 
+const errorTypeToStatus: Record<string, number> = {
+  invalid_request_error: 400,
+  invalid_api_key_error: 401,
+  insufficient_quota_error: 429,
+  rate_limit_error: 429,
+  service_unavailable_error: 503
+}
+
 const AllEvents = Schema.Union([ErrorEvent, OpenAiSchema.ResponseStreamEvent])
 const decodeEvent = Schema.decodeUnknownSync(Schema.fromJsonString(AllEvents))
 
 /**
- * Uses OpenAI's websocket mode for all responses within the provided effect.
+ * Uses OpenAI's WebSocket mode for response streams within the provided effect.
+ *
+ * **When to use**
+ *
+ * Use to enable WebSocket mode around one effect that creates OpenAI response
+ * streams.
  *
  * **Gotchas**
  *
@@ -596,6 +706,9 @@ const decodeEvent = Schema.decodeUnknownSync(Schema.fromJsonString(AllEvents))
  *
  * This is because it needs to use non-standard options for setting the Authorization header.
  *
+ * @see {@link layerWebSocketMode} for providing WebSocket mode through a layer
+ * @see {@link OpenAiSocket} for direct access to the WebSocket-backed streaming service
+ *
  * @category Websocket mode
  * @since 4.0.0
  */
@@ -616,6 +729,11 @@ export const withWebSocketMode = <A, E, R>(
 /**
  * Uses OpenAI's websocket mode for all responses that use the Layer.
  *
+ * **When to use**
+ *
+ * Use to provide WebSocket mode through layer composition for effects that use
+ * OpenAI response streaming.
+ *
  * **Gotchas**
  *
  * This only works with the following WebSocket constructor layers:
@@ -625,6 +743,8 @@ export const withWebSocketMode = <A, E, R>(
  *
  * This is because it needs to use non-standard options for setting the Authorization header.
  *
+ * @see {@link withWebSocketMode} for enabling WebSocket mode around a single effect
+ *
  * @category Websocket mode
  * @since 4.0.0
  */

package/src/OpenAiConfig.ts

@@ -1,19 +1,33 @@
 /**
- * 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.
+ * The `OpenAiConfig` module carries request-time configuration for the
+ * `@effect/ai-openai` package through Effect's context. It currently exposes a
+ * scoped HTTP client transform used by OpenAI request helpers when they execute
+ * provider calls.
+ *
+ * **Mental model**
+ *
+ * Client constructors set the baseline HTTP client for an OpenAI service.
+ * `OpenAiConfig` is for narrower dynamic scopes: wrap an effect with
+ * {@link withClientTransform} and OpenAI requests evaluated inside that effect
+ * see the transformed `HttpClient`. Leaving the scope restores the previous
+ * configuration.
+ *
+ * **Common tasks**
+ *
+ * - Add request middleware, tracing, retry policy, proxy routing, or test
+ *   interception around a group of OpenAI calls.
+ * - Apply a temporary HTTP client transform without rebuilding the OpenAI
+ *   service layer.
+ * - Share one transform across all OpenAI helpers executed inside the same
+ *   Effect scope.
+ *
+ * **Gotchas**
+ *
+ * - Only one `transformClient` value is stored in the scoped config. Compose
+ *   transforms into a single `HttpClient => HttpClient` function when multiple
+ *   behaviors should apply.
+ * - The transform affects OpenAI requests that read this contextual config; it
+ *   does not mutate an already constructed HTTP client globally.
  *
  * @since 4.0.0
  */
@@ -23,8 +37,14 @@ import { dual } from "effect/Function"
 import type { HttpClient } from "effect/unstable/http/HttpClient"
 
 /**
- * Context service carrying scoped OpenAI configuration for provider
- * operations.
+ * Context service for scoped OpenAI configuration used by provider operations.
+ *
+ * **When to use**
+ *
+ * Use to provide scoped OpenAI client configuration, such as an HTTP client
+ * transform, to OpenAI provider operations without passing it through each call.
+ *
+ * @see {@link withClientTransform} for scoping an HTTP client transformation
  *
  * @category services
  * @since 4.0.0
@@ -66,6 +86,22 @@ export declare namespace OpenAiConfig {
  * Provides a scoped transform for the OpenAI HTTP client used by provider
  * operations.
  *
+ * **When to use**
+ *
+ * Use when a single effect or workflow needs temporary OpenAI HTTP client
+ * customization without rebuilding the client layer.
+ *
+ * **Details**
+ *
+ * Supports both data-first and data-last forms. The transform is stored in the
+ * scoped `OpenAiConfig` service and read by OpenAI provider operations while
+ * running the supplied effect.
+ *
+ * **Gotchas**
+ *
+ * If a transform is already present in the scoped config, this helper replaces
+ * it. Compose transforms manually when both should apply.
+ *
  * @category configuration
  * @since 4.0.0
  */
@@ -74,6 +110,22 @@ export const withClientTransform: {
    * Provides a scoped transform for the OpenAI HTTP client used by provider
    * operations.
    *
+   * **When to use**
+   *
+   * Use when a single effect or workflow needs temporary OpenAI HTTP client
+   * customization without rebuilding the client layer.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. The transform is stored in the
+   * scoped `OpenAiConfig` service and read by OpenAI provider operations while
+   * running the supplied effect.
+   *
+   * **Gotchas**
+   *
+   * If a transform is already present in the scoped config, this helper replaces
+   * it. Compose transforms manually when both should apply.
+   *
    * @category configuration
    * @since 4.0.0
    */
@@ -82,6 +134,22 @@ export const withClientTransform: {
    * Provides a scoped transform for the OpenAI HTTP client used by provider
    * operations.
    *
+   * **When to use**
+   *
+   * Use when a single effect or workflow needs temporary OpenAI HTTP client
+   * customization without rebuilding the client layer.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. The transform is stored in the
+   * scoped `OpenAiConfig` service and read by OpenAI provider operations while
+   * running the supplied effect.
+   *
+   * **Gotchas**
+   *
+   * If a transform is already present in the scoped config, this helper replaces
+   * it. Compose transforms manually when both should apply.
+   *
    * @category configuration
    * @since 4.0.0
    */

package/src/OpenAiEmbeddingModel.ts

@@ -1,7 +1,33 @@
 /**
- * OpenAI Embedding Model implementation.
+ * The `OpenAiEmbeddingModel` module provides the OpenAI implementation of
+ * Effect AI's `EmbeddingModel` service. It adapts the OpenAI embeddings
+ * endpoint into Effect AI's batch embedding interface, preserving input order
+ * and returning numeric vectors for each requested input.
  *
- * Provides an EmbeddingModel implementation for OpenAI's embeddings API.
+ * **Mental model**
+ *
+ * `OpenAiClient` owns transport, authentication, and provider request
+ * execution. This module owns embedding-specific configuration, response
+ * validation, and the `EmbeddingModel.EmbeddingModel` layer. Use {@link model}
+ * when you want an `AiModel` descriptor that also provides the configured
+ * embedding dimensions, or {@link layer} / {@link make} when the dimensions are
+ * managed separately.
+ *
+ * **Common tasks**
+ *
+ * - Provide an OpenAI-backed `EmbeddingModel.EmbeddingModel` from an existing
+ *   `OpenAiClient`
+ * - Configure the OpenAI embedding model id, dimensions, encoding format, and
+ *   other create-embedding request fields
+ * - Scope per-request defaults with {@link Config} and
+ *   {@link withConfigOverride}
+ *
+ * **Gotchas**
+ *
+ * - The service expects OpenAI to return floating-point embedding arrays.
+ *   Requesting base64 embeddings causes an `InvalidOutputError`.
+ * - Provider results are checked for missing, duplicate, or out-of-range
+ *   indexes before they are exposed as Effect AI embedding results.
  *
  * @since 4.0.0
  */
@@ -25,7 +51,20 @@ import type * as OpenAiSchema from "./OpenAiSchema.ts"
 export type Model = "text-embedding-ada-002" | "text-embedding-3-small" | "text-embedding-3-large"
 
 /**
- * Service definition for OpenAI embedding model configuration.
+ * Context service for OpenAI embedding model configuration.
+ *
+ * **When to use**
+ *
+ * Use when embedding requests need scoped OpenAI request defaults or overrides
+ * from Effect context.
+ *
+ * **Details**
+ *
+ * The service stores the OpenAI create-embedding request payload without
+ * `input`, carrying options such as `model`, `dimensions`, `encoding_format`,
+ * and `user`.
+ *
+ * @see {@link withConfigOverride} for scoping embedding request overrides
  *
  * @category services
  * @since 4.0.0
@@ -48,6 +87,14 @@ export class Config extends Context.Service<
 /**
  * Creates an `AiModel` for an OpenAI embedding model with its configured vector dimensions.
  *
+ * **When to use**
+ *
+ * Use to provide an OpenAI `EmbeddingModel` and its `Dimensions` service to an
+ * Effect program.
+ *
+ * @see {@link layer} for providing only the embedding model service
+ * @see {@link withConfigOverride} for scoped request configuration overrides
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -76,6 +123,29 @@ export const model = (
 /**
  * Creates an OpenAI embedding model service.
  *
+ * **When to use**
+ *
+ * Use to construct the `EmbeddingModel.Service` effectfully when
+ * `OpenAiClient` is already available in the environment or when the service
+ * value is needed directly.
+ *
+ * **Details**
+ *
+ * The `model` option is sent with each embedding request. Constructor `config`
+ * supplies create-embedding request fields other than `model` and `input`, and
+ * scoped overrides from `withConfigOverride` are merged last for each request.
+ *
+ * **Gotchas**
+ *
+ * The service expects numeric embedding vectors. It fails with
+ * `InvalidOutputError` when the provider returns base64 embeddings,
+ * out-of-range indexes, duplicate indexes, or an unexpected number of
+ * embeddings.
+ *
+ * @see {@link layer} for providing the embedding model service as a layer
+ * @see {@link model} for creating an `AiModel` that also provides dimensions
+ * @see {@link withConfigOverride} for scoped request configuration overrides
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -102,6 +172,21 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
 /**
  * Creates a layer for the OpenAI embedding model.
  *
+ * **When to use**
+ *
+ * Use when composing application layers and you want OpenAI to satisfy
+ * `EmbeddingModel.EmbeddingModel` while supplying `OpenAiClient` from another
+ * layer.
+ *
+ * **Gotchas**
+ *
+ * Use the default floating-point embedding format. The service expects numeric
+ * vectors and fails with `InvalidOutputError` if OpenAI returns base64
+ * embeddings.
+ *
+ * @see {@link make} for constructing the embedding model service effectfully
+ * @see {@link model} for creating an `AiModel` that also provides embedding dimensions
+ *
  * @category layers
  * @since 4.0.0
  */
@@ -114,6 +199,19 @@ export const layer = (options: {
 /**
  * Provides config overrides for OpenAI embedding model operations.
  *
+ * **When to use**
+ *
+ * Use when a single effect or workflow needs scoped OpenAI embedding request
+ * defaults without rebuilding the embedding model service.
+ *
+ * **Details**
+ *
+ * Supports both data-first and data-last forms. Existing scoped config is read
+ * first, then the provided overrides are applied so override fields take
+ * precedence.
+ *
+ * @see {@link Config} for the scoped embedding request configuration service
+ *
  * @category configuration
  * @since 4.0.0
  */
@@ -121,6 +219,19 @@ export const withConfigOverride: {
   /**
    * Provides config overrides for OpenAI embedding model operations.
    *
+   * **When to use**
+   *
+   * Use when a single effect or workflow needs scoped OpenAI embedding request
+   * defaults without rebuilding the embedding model service.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. Existing scoped config is read
+   * first, then the provided overrides are applied so override fields take
+   * precedence.
+   *
+   * @see {@link Config} for the scoped embedding request configuration service
+   *
    * @category configuration
    * @since 4.0.0
    */
@@ -128,6 +239,19 @@ export const withConfigOverride: {
   /**
    * Provides config overrides for OpenAI embedding model operations.
    *
+   * **When to use**
+   *
+   * Use when a single effect or workflow needs scoped OpenAI embedding request
+   * defaults without rebuilding the embedding model service.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. Existing scoped config is read
+   * first, then the provided overrides are applied so override fields take
+   * precedence.
+   *
+   * @see {@link Config} for the scoped embedding request configuration service
+   *
    * @category configuration
    * @since 4.0.0
    */
@@ -136,6 +260,19 @@ export const withConfigOverride: {
   /**
    * Provides config overrides for OpenAI embedding model operations.
    *
+   * **When to use**
+   *
+   * Use when a single effect or workflow needs scoped OpenAI embedding request
+   * defaults without rebuilding the embedding model service.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. Existing scoped config is read
+   * first, then the provided overrides are applied so override fields take
+   * precedence.
+   *
+   * @see {@link Config} for the scoped embedding request configuration service
+   *
    * @category configuration
    * @since 4.0.0
    */
@@ -143,6 +280,19 @@ export const withConfigOverride: {
   /**
    * Provides config overrides for OpenAI embedding model operations.
    *
+   * **When to use**
+   *
+   * Use when a single effect or workflow needs scoped OpenAI embedding request
+   * defaults without rebuilding the embedding model service.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. Existing scoped config is read
+   * first, then the provided overrides are applied so override fields take
+   * precedence.
+   *
+   * @see {@link Config} for the scoped embedding request configuration service
+   *
    * @category configuration
    * @since 4.0.0
    */