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

package/dist/OpenAiConfig.js

@@ -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
  */
@@ -21,8 +35,14 @@ import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import { dual } from "effect/Function";
 /**
- * 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
@@ -39,6 +59,22 @@ export class OpenAiConfig extends /*#__PURE__*/Context.Service()("@effect/ai-ope
  * 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/dist/OpenAiConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"OpenAiConfig.js","names":["Context","Effect","dual","OpenAiConfig","Service","getOrUndefined","map","context","mapUnsafe","get","key","withClientTransform","self","transformClient","flatMap","config","provideService"],"sources":["../src/OpenAiConfig.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;AAmBA,OAAO,KAAKA,OAAO,MAAM,gBAAgB;AACzC,OAAO,KAAKC,MAAM,MAAM,eAAe;AACvC,SAASC,IAAI,QAAQ,iBAAiB;AAGtC;;;;;;;AAOA,OAAM,MAAOC,YAAa,sBAAQH,OAAO,CAACI,OAAO,EAG9C,CAAC,gCAAgC,CAAC;EACnC;;;;;EAKA,OAAgBC,cAAc,gBAA2DJ,MAAM,CAACK,GAAG,cACjGL,MAAM,CAACM,OAAO,EAAS,EACtBA,OAAO,IAAKA,OAAO,CAACC,SAAS,CAACC,GAAG,CAACN,YAAY,CAACO,GAAG,CAAC,CACrD;;AAqBH;;;;;;;AAOA,OAAO,MAAMC,mBAAmB,gBAoB5BT,IAAI,CAAC,CAAC,EAAE,CACVU,IAA4B,EAC5BC,eAAmD,KAEnDZ,MAAM,CAACa,OAAO,CACZX,YAAY,CAACE,cAAc,EAC1BU,MAAM,IAAKd,MAAM,CAACe,cAAc,CAACJ,IAAI,EAAET,YAAY,EAAE;EAAE,GAAGY,MAAM;EAAEF;AAAe,CAAE,CAAC,CACtF,CAAC","ignoreList":[]}
+{"version":3,"file":"OpenAiConfig.js","names":["Context","Effect","dual","OpenAiConfig","Service","getOrUndefined","map","context","mapUnsafe","get","key","withClientTransform","self","transformClient","flatMap","config","provideService"],"sources":["../src/OpenAiConfig.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,OAAO,KAAKA,OAAO,MAAM,gBAAgB;AACzC,OAAO,KAAKC,MAAM,MAAM,eAAe;AACvC,SAASC,IAAI,QAAQ,iBAAiB;AAGtC;;;;;;;;;;;;;AAaA,OAAM,MAAOC,YAAa,sBAAQH,OAAO,CAACI,OAAO,EAG9C,CAAC,gCAAgC,CAAC;EACnC;;;;;EAKA,OAAgBC,cAAc,gBAA2DJ,MAAM,CAACK,GAAG,cACjGL,MAAM,CAACM,OAAO,EAAS,EACtBA,OAAO,IAAKA,OAAO,CAACC,SAAS,CAACC,GAAG,CAACN,YAAY,CAACO,GAAG,CAAC,CACrD;;AAqBH;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,MAAMC,mBAAmB,gBAoD5BT,IAAI,CAAC,CAAC,EAAE,CACVU,IAA4B,EAC5BC,eAAmD,KAEnDZ,MAAM,CAACa,OAAO,CACZX,YAAY,CAACE,cAAc,EAC1BU,MAAM,IAAKd,MAAM,CAACe,cAAc,CAACJ,IAAI,EAAET,YAAY,EAAE;EAAE,GAAGY,MAAM;EAAEF;AAAe,CAAE,CAAC,CACtF,CAAC","ignoreList":[]}

package/dist/OpenAiEmbeddingModel.d.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
  */
@@ -26,7 +52,20 @@ declare const Config_base: Context.ServiceClass<Config, "@effect/ai-openai/OpenA
     readonly model?: string;
 }>;
 /**
- * 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
@@ -36,6 +75,14 @@ export declare class Config extends Config_base {
 /**
  * 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
  */
@@ -46,6 +93,29 @@ export declare const model: (model: (string & {}) | Model, options: {
 /**
  * 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
  */
@@ -56,6 +126,21 @@ export declare const make: (args_0: {
 /**
  * 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
  */
@@ -66,6 +151,19 @@ export declare 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
  */
@@ -73,6 +171,19 @@ export declare 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
      */
@@ -80,6 +191,19 @@ export declare 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
      */

package/dist/OpenAiEmbeddingModel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OpenAiEmbeddingModel.d.ts","sourceRoot":"","sources":["../src/OpenAiEmbeddingModel.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAGrC,OAAO,KAAK,cAAc,MAAM,mCAAmC,CAAA;AACnE,OAAO,KAAK,OAAO,MAAM,0BAA0B,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAGhD;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,wBAAwB,GAAG,wBAAwB,GAAG,wBAAwB,CAAA;;;;;;;;AAElG;;;;;GAKG;AACH,qBAAa,MAAO,SAAQ,WAawB;CAAG;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAChB,OAAO,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,KAAK,EAC5B,SAAS;IACP,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY,CAAC,CAAA;CACtE,KACA,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,cAAc,CAAC,cAAc,GAAG,cAAc,CAAC,UAAU,EAAE,YAAY,CAc/F,CAAA;AAEH;;;;;GAKG;AACH,eAAO,MAAM,IAAI;oBACC,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,KAAK;sBACnB,IAAI,CAAC,OAAO,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,SAAS;gEAgBlE,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAAI,SAAS;IAC7B,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,KAAK,CAAA;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;CACnE,KAAG,KAAK,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,EAAE,KAAK,EAAE,YAAY,CACN,CAAA;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE;IAC/B;;;;;OAKG;IACH,CAAC,SAAS,EAAE,OAAO,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA;IACtH;;;;;OAKG;IACH,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA;CAwBhH,CAAA"}
+{"version":3,"file":"OpenAiEmbeddingModel.d.ts","sourceRoot":"","sources":["../src/OpenAiEmbeddingModel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAGrC,OAAO,KAAK,cAAc,MAAM,mCAAmC,CAAA;AACnE,OAAO,KAAK,OAAO,MAAM,0BAA0B,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAGhD;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,wBAAwB,GAAG,wBAAwB,GAAG,wBAAwB,CAAA;;;;;;;;AAElG;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,MAAO,SAAQ,WAawB;CAAG;AAEvD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,KAAK,GAChB,OAAO,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,KAAK,EAC5B,SAAS;IACP,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY,CAAC,CAAA;CACtE,KACA,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,cAAc,CAAC,cAAc,GAAG,cAAc,CAAC,UAAU,EAAE,YAAY,CAc/F,CAAA;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,IAAI;oBACC,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,KAAK;sBACnB,IAAI,CAAC,OAAO,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,SAAS;gEAgBlE,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,KAAK,GAAI,SAAS;IAC7B,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,KAAK,CAAA;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;CACnE,KAAG,KAAK,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,EAAE,KAAK,EAAE,YAAY,CACN,CAAA;AAE5D;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,kBAAkB,EAAE;IAC/B;;;;;;;;;;;;;;;;;;OAkBG;IACH,CAAC,SAAS,EAAE,OAAO,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA;IACtH;;;;;;;;;;;;;;;;;;OAkBG;IACH,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA;CAkDhH,CAAA"}

package/dist/OpenAiEmbeddingModel.js

@@ -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
  */
@@ -14,7 +40,20 @@ import * as EmbeddingModel from "effect/unstable/ai/EmbeddingModel";
 import * as AiModel from "effect/unstable/ai/Model";
 import { OpenAiClient } from "./OpenAiClient.js";
 /**
- * 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
@@ -23,6 +62,14 @@ export class Config extends /*#__PURE__*/Context.Service()("@effect/ai-openai/Op
 /**
  * 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
  */
@@ -36,6 +83,29 @@ export const model = (model, options) => AiModel.make("openai", model, Layer.mer
 /**
  * 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
  */
@@ -68,6 +138,21 @@ export const make = /*#__PURE__*/Effect.fnUntraced(function* ({
 /**
  * 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
  */
@@ -75,6 +160,19 @@ export const layer = options => Layer.effect(EmbeddingModel.EmbeddingModel, make
 /**
  * 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
  */

package/dist/OpenAiEmbeddingModel.js.map

@@ -1 +1 @@
-{"version":3,"file":"OpenAiEmbeddingModel.js","names":["Context","Effect","dual","Layer","AiError","EmbeddingModel","AiModel","OpenAiClient","Config","Service","model","options","make","merge","layer","config","dimensions","succeed","Dimensions","fnUntraced","providerConfig","client","makeConfig","gen","services","context","mapUnsafe","get","key","embedMany","inputs","response","createEmbedding","input","mapProviderResponse","length","effect","withConfigOverride","self","overrides","flatMap","serviceOption","provideService","_tag","value","inputLength","data","fail","invalidOutput","results","Array","seen","Set","entry","Number","isInteger","index","has","isArray","embedding","add","size","usage","inputTokens","prompt_tokens","description","module","method","reason","InvalidOutputError"],"sources":["../src/OpenAiEmbeddingModel.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;AAOA,OAAO,KAAKA,OAAO,MAAM,gBAAgB;AACzC,OAAO,KAAKC,MAAM,MAAM,eAAe;AACvC,SAASC,IAAI,QAAQ,iBAAiB;AACtC,OAAO,KAAKC,KAAK,MAAM,cAAc;AAErC,OAAO,KAAKC,OAAO,MAAM,4BAA4B;AACrD,OAAO,KAAKC,cAAc,MAAM,mCAAmC;AACnE,OAAO,KAAKC,OAAO,MAAM,0BAA0B;AACnD,SAASC,YAAY,QAAQ,mBAAmB;AAWhD;;;;;;AAMA,OAAM,MAAOC,MAAO,sBAAQR,OAAO,CAACS,OAAO,EAaxC,CAAC,+CAA+C,CAAC;AAEpD;;;;;;AAMA,OAAO,MAAMC,KAAK,GAAGA,CACnBA,KAA4B,EAC5BC,OAGC,KAEDL,OAAO,CAACM,IAAI,CACV,QAAQ,EACRF,KAAK,EACLP,KAAK,CAACU,KAAK,CACTC,KAAK,CAAC;EACJJ,KAAK;EACLK,MAAM,EAAE;IACN,GAAGJ,OAAO,CAACI,MAAM;IACjBC,UAAU,EAAEL,OAAO,CAACK;;CAEvB,CAAC,EACFb,KAAK,CAACc,OAAO,CAACZ,cAAc,CAACa,UAAU,EAAEP,OAAO,CAACK,UAAU,CAAC,CAC7D,CACF;AAEH;;;;;;AAMA,OAAO,MAAMJ,IAAI,gBAAGX,MAAM,CAACkB,UAAU,CAAC,WAAU;EAAET,KAAK;EAAEK,MAAM,EAAEK;AAAc,CAG9E;EACC,MAAMC,MAAM,GAAG,OAAOd,YAAY;EAElC,MAAMe,UAAU,GAAGrB,MAAM,CAACsB,GAAG,CAAC,aAAS;IACrC,MAAMC,QAAQ,GAAG,OAAOvB,MAAM,CAACwB,OAAO,EAAS;IAC/C,OAAO;MAAEf,KAAK;MAAE,GAAGU,cAAc;MAAE,GAAGI,QAAQ,CAACE,SAAS,CAACC,GAAG,CAACnB,MAAM,CAACoB,GAAG;IAAC,CAAE;EAC5E,CAAC,CAAC;EAEF,OAAO,OAAOvB,cAAc,CAACO,IAAI,CAAC;IAChCiB,SAAS,EAAE5B,MAAM,CAACkB,UAAU,CAAC,WAAU;MAAEW;IAAM,CAAE;MAC/C,MAAMf,MAAM,GAAG,OAAOO,UAAU;MAChC,MAAMS,QAAQ,GAAG,OAAOV,MAAM,CAACW,eAAe,CAAC;QAAE,GAAGjB,MAAM;QAAEkB,KAAK,EAAEH;MAAM,CAAE,CAAC;MAC5E,OAAO,OAAOI,mBAAmB,CAACJ,MAAM,CAACK,MAAM,EAAEJ,QAAQ,CAAC;IAC5D,CAAC;GACF,CAAC;AACJ,CAAC,CAAC;AAEF;;;;;;AAMA,OAAO,MAAMjB,KAAK,GAAIH,OAGrB,IACCR,KAAK,CAACiC,MAAM,CAAC/B,cAAc,CAACA,cAAc,EAAEO,IAAI,CAACD,OAAO,CAAC,CAAC;AAE5D;;;;;;AAMA,OAAO,MAAM0B,kBAAkB,gBAe3BnC,IAAI,CAeN,CAAC,EAAE,CAACoC,IAAI,EAAEC,SAAS,KACnBtC,MAAM,CAACuC,OAAO,CACZvC,MAAM,CAACwC,aAAa,CAACjC,MAAM,CAAC,EAC3BO,MAAM,IACLd,MAAM,CAACyC,cAAc,CAACJ,IAAI,EAAE9B,MAAM,EAAE;EAClC,IAAIO,MAAM,CAAC4B,IAAI,KAAK,MAAM,GAAG5B,MAAM,CAAC6B,KAAK,GAAG,EAAE,CAAC;EAC/C,GAAGL;CACJ,CAAC,CACL,CAAC;AAEJ,MAAML,mBAAmB,GAAGA,CAC1BW,WAAmB,EACnBd,QAA0D,KACS;EACnE,IAAIA,QAAQ,CAACe,IAAI,CAACX,MAAM,KAAKU,WAAW,EAAE;IACxC,OAAO5C,MAAM,CAAC8C,IAAI,CAChBC,aAAa,CAAC,oBAAoB,GAAGjB,QAAQ,CAACe,IAAI,CAACX,MAAM,GAAG,2BAA2B,GAAGU,WAAW,CAAC,CACvG;EACH;EAEA,MAAMI,OAAO,GAAG,IAAIC,KAAK,CAAgBL,WAAW,CAAC;EACrD,MAAMM,IAAI,GAAG,IAAIC,GAAG,EAAU;EAE9B,KAAK,MAAMC,KAAK,IAAItB,QAAQ,CAACe,IAAI,EAAE;IACjC,IAAI,CAACQ,MAAM,CAACC,SAAS,CAACF,KAAK,CAACG,KAAK,CAAC,IAAIH,KAAK,CAACG,KAAK,GAAG,CAAC,IAAIH,KAAK,CAACG,KAAK,IAAIX,WAAW,EAAE;MACnF,OAAO5C,MAAM,CAAC8C,IAAI,CAACC,aAAa,CAAC,6CAA6C,GAAGK,KAAK,CAACG,KAAK,CAAC,CAAC;IAChG;IACA,IAAIL,IAAI,CAACM,GAAG,CAACJ,KAAK,CAACG,KAAK,CAAC,EAAE;MACzB,OAAOvD,MAAM,CAAC8C,IAAI,CAACC,aAAa,CAAC,+CAA+C,GAAGK,KAAK,CAACG,KAAK,CAAC,CAAC;IAClG;IACA,IAAI,CAACN,KAAK,CAACQ,OAAO,CAACL,KAAK,CAACM,SAAS,CAAC,EAAE;MACnC,OAAO1D,MAAM,CAAC8C,IAAI,CAACC,aAAa,CAAC,kDAAkD,GAAGK,KAAK,CAACG,KAAK,CAAC,CAAC;IACrG;IAEAL,IAAI,CAACS,GAAG,CAACP,KAAK,CAACG,KAAK,CAAC;IACrBP,OAAO,CAACI,KAAK,CAACG,KAAK,CAAC,GAAG,CAAC,GAAGH,KAAK,CAACM,SAAS,CAAC;EAC7C;EAEA,IAAIR,IAAI,CAACU,IAAI,KAAKhB,WAAW,EAAE;IAC7B,OAAO5C,MAAM,CAAC8C,IAAI,CAChBC,aAAa,CAAC,mCAAmC,GAAGG,IAAI,CAACU,IAAI,GAAG,uBAAuB,GAAGhB,WAAW,CAAC,CACvG;EACH;EAEA,OAAO5C,MAAM,CAACgB,OAAO,CAAC;IACpBgC,OAAO;IACPa,KAAK,EAAE;MACLC,WAAW,EAAEhC,QAAQ,CAAC+B,KAAK,EAAEE;;GAEhC,CAAC;AACJ,CAAC;AAED,MAAMhB,aAAa,GAAIiB,WAAmB,IACxC7D,OAAO,CAACQ,IAAI,CAAC;EACXsD,MAAM,EAAE,sBAAsB;EAC9BC,MAAM,EAAE,WAAW;EACnBC,MAAM,EAAE,IAAIhE,OAAO,CAACiE,kBAAkB,CAAC;IAAEJ;EAAW,CAAE;CACvD,CAAC","ignoreList":[]}
+{"version":3,"file":"OpenAiEmbeddingModel.js","names":["Context","Effect","dual","Layer","AiError","EmbeddingModel","AiModel","OpenAiClient","Config","Service","model","options","make","merge","layer","config","dimensions","succeed","Dimensions","fnUntraced","providerConfig","client","makeConfig","gen","services","context","mapUnsafe","get","key","embedMany","inputs","response","createEmbedding","input","mapProviderResponse","length","effect","withConfigOverride","self","overrides","flatMap","serviceOption","provideService","_tag","value","inputLength","data","fail","invalidOutput","results","Array","seen","Set","entry","Number","isInteger","index","has","isArray","embedding","add","size","usage","inputTokens","prompt_tokens","description","module","method","reason","InvalidOutputError"],"sources":["../src/OpenAiEmbeddingModel.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/OpenAiLanguageModel.d.ts

@@ -1,8 +1,38 @@
 /**
- * OpenAI Language Model implementation.
+ * 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.
  *
- * Provides a LanguageModel implementation for OpenAI's responses API,
- * supporting text generation, structured output, tool calling, and streaming.
+ * **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
  */
@@ -73,7 +103,19 @@ declare const Config_base: Context.ServiceClass<Config, "@effect/ai-openai/OpenA
     readonly strictJsonSchema?: boolean | undefined | undefined;
 }>;
 /**
- * Service definition for OpenAI language model configuration.
+ * Context service for OpenAI language model configuration.
+ *
+ * **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
@@ -459,14 +501,39 @@ declare module "effect/unstable/ai/Response" {
     }
 }
 /**
- * Creates an OpenAI language model that can be used with `AiModel.provide`.
+ * 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`
  *
  * @category constructors
  * @since 4.0.0
@@ -476,7 +543,24 @@ export declare const make: (args_0: {
     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
  *
  * @category layers
  * @since 4.0.0
@@ -486,21 +570,66 @@ export declare const layer: (options: {
     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
  *
  * @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
      *
      * @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
      *
      * @category configuration
      * @since 4.0.0