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

package/src/OpenAiClient.ts

@@ -77,8 +77,22 @@ export interface Service {
 }
 
 /**
- * Context service tag for accessing an OpenAI-compatible client from the
- * Effect context.
+ * Context service tag for the OpenAI-compatible chat completions and embeddings client.
+ *
+ * **When to use**
+ *
+ * Use when building effects that depend on the low-level OpenAI-compatible
+ * client through context rather than receiving the client as a value.
+ *
+ * **Details**
+ *
+ * The tagged service is the `Service` interface produced by `make` and provided
+ * by `layer` or `layerConfig`.
+ *
+ * @see {@link Service} for the operations provided by the service
+ * @see {@link make} for constructing the service from explicit options
+ * @see {@link layer} for providing the service from explicit options
+ * @see {@link layerConfig} for loading client settings from `Config`
  *
  * @category services
  * @since 4.0.0
@@ -109,10 +123,25 @@ const RedactedOpenAiHeaders = {
 /**
  * Constructs an OpenAI-compatible client service from explicit options.
  *
+ * **When to use**
+ *
+ * Use to construct the OpenAI-compatible client service inside an effect when
+ * you need the service value directly.
+ *
  * **Details**
  *
- * The returned service applies the configured base URL, authentication, and
- * OpenAI organization/project headers to the underlying HTTP client.
+ * The returned service uses the current `HttpClient`, prepends `apiUrl` or
+ * `https://api.openai.com/v1`, adds authentication and OpenAI
+ * organization/project headers, accepts JSON responses, 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
@@ -257,6 +286,14 @@ export const make = Effect.fnUntraced(
 /**
  * Creates a layer that provides an OpenAI-compatible client from explicit options.
  *
+ * **When to use**
+ *
+ * Use to install `OpenAiClient` in an application layer when the client options
+ * are already available as values rather than loaded from `Config`.
+ *
+ * @see {@link make} for constructing the client service effectfully
+ * @see {@link layerConfig} for loading client settings from `Config`
+ *
  * @category layers
  * @since 4.0.0
  */
@@ -267,6 +304,20 @@ export const layer = (options: Options): Layer.Layer<OpenAiClient, never, HttpCl
  * Creates a layer that loads OpenAI-compatible client settings from `Config`
  * values before constructing the service.
  *
+ * **When to use**
+ *
+ * Use when OpenAI-compatible 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
  */

package/src/OpenAiConfig.ts

@@ -30,6 +30,13 @@ import type { HttpClient } from "effect/unstable/http/HttpClient"
  * Context service used to carry OpenAI-compatible client configuration for the
  * current Effect scope.
  *
+ * **When to use**
+ *
+ * Use as the context service for OpenAI-compatible client configuration when you
+ * need to provide or read scoped HTTP client transforms through Effect context.
+ *
+ * @see {@link withClientTransform} for scoping an HTTP client transformation
+ *
  * @category services
  * @since 4.0.0
  */
@@ -71,7 +78,7 @@ export declare namespace OpenAiConfig {
  *
  * **When to use**
  *
- * Use this to add provider-specific OpenAI-compatible HTTP behavior, such as
+ * Use to add provider-specific OpenAI-compatible HTTP behavior, such as
  * headers, retries, instrumentation, or proxy routing.
  *
  * **Details**
@@ -88,7 +95,7 @@ export const withClientTransform: {
    *
    * **When to use**
    *
-   * Use this to add provider-specific OpenAI-compatible HTTP behavior, such as
+   * Use to add provider-specific OpenAI-compatible HTTP behavior, such as
    * headers, retries, instrumentation, or proxy routing.
    *
    * **Details**
@@ -105,7 +112,7 @@ export const withClientTransform: {
    *
    * **When to use**
    *
-   * Use this to add provider-specific OpenAI-compatible HTTP behavior, such as
+   * Use to add provider-specific OpenAI-compatible HTTP behavior, such as
    * headers, retries, instrumentation, or proxy routing.
    *
    * **Details**

package/src/OpenAiEmbeddingModel.ts

@@ -1,7 +1,37 @@
 /**
- * OpenAI Embedding Model implementation.
+ * The `OpenAiEmbeddingModel` module adapts OpenAI-compatible embeddings
+ * endpoints to Effect's embedding model service. It sends embedding requests
+ * through {@link OpenAiClient}, exposes constructors for layers and `AiModel`
+ * values, and supports scoped request configuration overrides.
  *
- * Provides an EmbeddingModel implementation for OpenAI-compatible embeddings APIs.
+ * **Mental model**
+ *
+ * - {@link make} builds the `EmbeddingModel` service when an
+ *   {@link OpenAiClient} is already available.
+ * - {@link layer} provides that service as a `Layer`.
+ * - {@link model} creates an `AiModel` and also provides the configured vector
+ *   dimensions service expected by embedding consumers.
+ * - {@link Config} and {@link withConfigOverride} merge default request options
+ *   with scoped overrides for individual operations.
+ *
+ * **Common tasks**
+ *
+ * - Use {@link model} when application code wants a named `AiModel` with known
+ *   dimensions.
+ * - Use {@link layer} when composing services around an existing
+ *   {@link OpenAiClient} layer.
+ * - Use {@link withConfigOverride} to set per-operation options such as `user`,
+ *   `dimensions`, or provider-specific request fields.
+ *
+ * **Gotchas**
+ *
+ * - {@link Model} is `string` because OpenAI-compatible providers use their
+ *   own embedding model identifiers.
+ * - {@link model} requires explicit dimensions because compatible providers do
+ *   not expose a shared way to infer vector width.
+ * - Provider responses must contain one numeric vector per input with unique,
+ *   in-range indexes; base64 embeddings or malformed indexes fail with
+ *   `InvalidOutputError`.
  *
  * @since 4.0.0
  */
@@ -27,6 +57,20 @@ export type Model = string
 /**
  * Service definition for OpenAI embedding model configuration.
  *
+ * **When to use**
+ *
+ * Use when you need to provide shared default request options for
+ * OpenAI-compatible embedding operations through the Effect context, such as
+ * `dimensions`, `encoding_format`, or `user`.
+ *
+ * **Details**
+ *
+ * The service stores the embedding request payload without `input`. Requests
+ * combine the selected model, layer or constructor config, and scoped context
+ * config, with scoped context config taking precedence.
+ *
+ * @see {@link withConfigOverride} for scoping embedding request overrides
+ *
  * @category context
  * @since 4.0.0
  */
@@ -46,8 +90,15 @@ export class Config extends Context.Service<
 >()("@effect/ai-openai-compat/OpenAiEmbeddingModel/Config") {}
 
 /**
- * Creates an OpenAI-compatible embedding model that can be used with
- * `AiModel.provide`.
+ * Creates an `AiModel` for an OpenAI-compatible embedding model with its configured vector dimensions.
+ *
+ * **When to use**
+ *
+ * Use to provide an OpenAI-compatible `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
@@ -75,7 +126,29 @@ export const model = (
   )
 
 /**
- * Creates an OpenAI embedding model service.
+ * Creates an OpenAI-compatible embedding model service backed by `OpenAiClient`.
+ *
+ * **When to use**
+ *
+ * Use when you need to build or provide an `EmbeddingModel` service directly
+ * from an existing `OpenAiClient`.
+ *
+ * **Details**
+ *
+ * The service sends embedding requests through `OpenAiClient.createEmbedding`.
+ * Request config is merged as the selected model, constructor config, then
+ * scoped `Config`, so scoped overrides take precedence. Provider usage
+ * `prompt_tokens` is exposed as `usage.inputTokens`.
+ *
+ * **Gotchas**
+ *
+ * Provider responses must contain one numeric vector for every requested input
+ * with unique, in-range `index` values; otherwise embedding operations fail with
+ * `AiError.InvalidOutputError`.
+ *
+ * @see {@link model} for the higher-level `AiModel` descriptor that also provides `EmbeddingModel.Dimensions`
+ * @see {@link layer} for providing the service as a `Layer`
+ * @see {@link withConfigOverride} for scoping embedding request overrides
  *
  * @category constructors
  * @since 4.0.0
@@ -101,7 +174,16 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
 })
 
 /**
- * Creates a layer for the OpenAI embedding model.
+ * Creates a layer for an OpenAI-compatible embedding model service.
+ *
+ * **When to use**
+ *
+ * Use when composing application layers and you want an OpenAI-compatible
+ * embeddings endpoint to satisfy `EmbeddingModel.EmbeddingModel` while
+ * supplying `OpenAiClient` from another layer.
+ *
+ * @see {@link make} for constructing the embedding model service effectfully
+ * @see {@link model} for creating an `AiModel` with configured dimensions
  *
  * @category layers
  * @since 4.0.0
@@ -113,21 +195,63 @@ export const layer = (options: {
   Layer.effect(EmbeddingModel.EmbeddingModel, make(options))
 
 /**
- * Provides config overrides for OpenAI embedding model operations.
+ * Provides scoped request config overrides for OpenAI-compatible embedding model operations.
+ *
+ * **When to use**
+ *
+ * Use to apply embedding request options to one effect without changing the
+ * model's default configuration.
+ *
+ * **Details**
+ *
+ * The overrides are merged with any existing `Config` service for the duration
+ * of the supplied effect. Fields in `overrides` take precedence over existing
+ * config, and the helper supports both `effect.pipe(withConfigOverride(overrides))`
+ * and `withConfigOverride(effect, overrides)`.
+ *
+ * @see {@link Config} for available OpenAI-compatible embedding request configuration fields
  *
  * @category configuration
  * @since 4.0.0
  */
 export const withConfigOverride: {
   /**
-   * Provides config overrides for OpenAI embedding model operations.
+   * Provides scoped request config overrides for OpenAI-compatible embedding model operations.
+   *
+   * **When to use**
+   *
+   * Use to apply embedding request options to one effect without changing the
+   * model's default configuration.
+   *
+   * **Details**
+   *
+   * The overrides are merged with any existing `Config` service for the duration
+   * of the supplied effect. Fields in `overrides` take precedence over existing
+   * config, and the helper supports both `effect.pipe(withConfigOverride(overrides))`
+   * and `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available OpenAI-compatible embedding request configuration fields
    *
    * @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.
+   * Provides scoped request config overrides for OpenAI-compatible embedding model operations.
+   *
+   * **When to use**
+   *
+   * Use to apply embedding request options to one effect without changing the
+   * model's default configuration.
+   *
+   * **Details**
+   *
+   * The overrides are merged with any existing `Config` service for the duration
+   * of the supplied effect. Fields in `overrides` take precedence over existing
+   * config, and the helper supports both `effect.pipe(withConfigOverride(overrides))`
+   * and `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available OpenAI-compatible embedding request configuration fields
    *
    * @category configuration
    * @since 4.0.0
@@ -135,14 +259,42 @@ export const withConfigOverride: {
   <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.
+   * Provides scoped request config overrides for OpenAI-compatible embedding model operations.
+   *
+   * **When to use**
+   *
+   * Use to apply embedding request options to one effect without changing the
+   * model's default configuration.
+   *
+   * **Details**
+   *
+   * The overrides are merged with any existing `Config` service for the duration
+   * of the supplied effect. Fields in `overrides` take precedence over existing
+   * config, and the helper supports both `effect.pipe(withConfigOverride(overrides))`
+   * and `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available OpenAI-compatible embedding request configuration fields
    *
    * @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.
+   * Provides scoped request config overrides for OpenAI-compatible embedding model operations.
+   *
+   * **When to use**
+   *
+   * Use to apply embedding request options to one effect without changing the
+   * model's default configuration.
+   *
+   * **Details**
+   *
+   * The overrides are merged with any existing `Config` service for the duration
+   * of the supplied effect. Fields in `overrides` take precedence over existing
+   * config, and the helper supports both `effect.pipe(withConfigOverride(overrides))`
+   * and `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available OpenAI-compatible embedding request configuration fields
    *
    * @category configuration
    * @since 4.0.0

package/src/OpenAiLanguageModel.ts

@@ -1,8 +1,34 @@
 /**
- * OpenAI Language Model implementation.
+ * The `OpenAiLanguageModel` module adapts OpenAI-compatible chat-completions
+ * providers to the shared Effect AI `LanguageModel` interface. It translates
+ * provider-neutral prompts, tools, structured output schemas, and streaming
+ * responses into the request and response shapes used by `OpenAiClient`.
  *
- * Provides a LanguageModel implementation for OpenAI's chat completions API,
- * supporting text generation, structured output, tool calling, and streaming.
+ * Use this module when an application wants to talk to OpenAI-compatible
+ * endpoints through Effect AI abstractions rather than constructing provider
+ * payloads directly. The exported constructors build a language model service
+ * from a model id, while `Config` and {@link withConfigOverride} provide scoped
+ * defaults for request fields such as temperature, reasoning options, text
+ * format, and provider-specific file handling.
+ *
+ * **Common tasks**
+ *
+ * - Create a model descriptor with {@link model}
+ * - Build or provide the `LanguageModel` service with {@link make} or
+ *   {@link layer}
+ * - Scope request defaults with {@link Config} and {@link withConfigOverride}
+ * - Send tool calls, structured output schemas, images, files, and reasoning
+ *   metadata through the provider-neutral Effect AI prompt types
+ *
+ * **Gotchas**
+ *
+ * - The module requires an `OpenAiClient` service; configure authentication,
+ *   base URL, and HTTP behavior through that client layer.
+ * - Compatibility depends on the provider supporting the OpenAI request fields
+ *   being used. Optional capabilities such as strict JSON schemas, reasoning
+ *   metadata, and tool status fields may vary across providers.
+ * - `fileIdPrefixes` tells the prompt conversion which file references are
+ *   provider file IDs instead of base64 file contents.
  *
  * @since 4.0.0
  */
@@ -61,6 +87,14 @@ type ImageDetail = "auto" | "low" | "high"
 /**
  * Service definition for OpenAI language model configuration.
  *
+ * **When to use**
+ *
+ * Use as the context service for OpenAI-compatible language model request
+ * configuration, especially when a scoped operation should override the defaults
+ * supplied to `model`, `make`, or `layer`.
+ *
+ * @see {@link withConfigOverride} for scoping language model request overrides
+ *
  * @category context
  * @since 4.0.0
  */
@@ -506,7 +540,15 @@ declare module "effect/unstable/ai/Response" {
 // =============================================================================
 
 /**
- * Creates an AI model descriptor for an OpenAI-compatible language model.
+ * Creates an OpenAI-compatible model descriptor that can be provided with `Effect.provide`.
+ *
+ * **When to use**
+ *
+ * Use when you want an OpenAI-compatible language model value that carries
+ * provider and model metadata and can be supplied directly to an Effect program.
+ *
+ * @see {@link layer} for creating a `LanguageModel.LanguageModel` layer directly
+ * @see {@link make} for constructing the language model service effectfully
  *
  * @category constructors
  * @since 4.0.0
@@ -529,7 +571,22 @@ export const model = (
 //   AiModel.make("openai", model, layerWithTokenizer({ model, config }))
 
 /**
- * Creates an OpenAI language model service.
+ * Creates an OpenAI-compatible `LanguageModel` service from a model identifier and optional request defaults.
+ *
+ * **When to use**
+ *
+ * Use when an Effect needs to construct a `LanguageModel.Service` value backed
+ * by `OpenAiClient`.
+ *
+ * **Details**
+ *
+ * The returned effect requires `OpenAiClient`. Request defaults from the
+ * `config` option are merged with any `Config` service in the context, with
+ * context values taking precedence. The service supports both `generateText` and
+ * `streamText`.
+ *
+ * @see {@link layer} for providing the service as a `Layer`
+ * @see {@link model} for creating a model descriptor for `AiModel.provide`
  *
  * @category constructors
  * @since 4.0.0
@@ -628,7 +685,16 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
 })
 
 /**
- * Creates a layer for the OpenAI language model.
+ * Creates a layer for the OpenAI-compatible language model.
+ *
+ * **When to use**
+ *
+ * Use when composing application layers and you want OpenAI-compatible APIs to
+ * satisfy `LanguageModel.LanguageModel` while supplying `OpenAiClient` from
+ * another layer.
+ *
+ * @see {@link make} for constructing the language model service effectfully
+ * @see {@link model} for creating an AI model descriptor
  *
  * @category layers
  * @since 4.0.0
@@ -640,21 +706,57 @@ export const layer = (options: {
   Layer.effect(LanguageModel.LanguageModel, make(options))
 
 /**
- * Provides config overrides for OpenAI language model operations.
+ * Provides scoped config overrides for OpenAI-compatible language model operations.
+ *
+ * **When to use**
+ *
+ * Use to override request configuration for a single language model effect
+ * without changing the defaults supplied to `model`, `make`, or `layer`.
+ *
+ * **Details**
+ *
+ * Existing `Config` values from the Effect context are merged with `overrides`,
+ * and the override values take precedence.
+ *
+ * @see {@link Config} for the configuration shape
  *
  * @category configuration
  * @since 4.0.0
  */
 export const withConfigOverride: {
   /**
-   * Provides config overrides for OpenAI language model operations.
+   * Provides scoped config overrides for OpenAI-compatible language model operations.
+   *
+   * **When to use**
+   *
+   * Use to override request configuration for a single language model effect
+   * without changing the defaults supplied to `model`, `make`, or `layer`.
+   *
+   * **Details**
+   *
+   * Existing `Config` values from the Effect context are merged with `overrides`,
+   * and the override values take precedence.
+   *
+   * @see {@link Config} for the configuration shape
    *
    * @category configuration
    * @since 4.0.0
    */
   (overrides: typeof Config.Service): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>
   /**
-   * Provides config overrides for OpenAI language model operations.
+   * Provides scoped config overrides for OpenAI-compatible language model operations.
+   *
+   * **When to use**
+   *
+   * Use to override request configuration for a single language model effect
+   * without changing the defaults supplied to `model`, `make`, or `layer`.
+   *
+   * **Details**
+   *
+   * Existing `Config` values from the Effect context are merged with `overrides`,
+   * and the override values take precedence.
+   *
+   * @see {@link Config} for the configuration shape
    *
    * @category configuration
    * @since 4.0.0
@@ -662,14 +764,38 @@ export const withConfigOverride: {
   <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service): Effect.Effect<A, E, Exclude<R, Config>>
 } = dual<
   /**
-   * Provides config overrides for OpenAI language model operations.
+   * Provides scoped config overrides for OpenAI-compatible language model operations.
+   *
+   * **When to use**
+   *
+   * Use to override request configuration for a single language model effect
+   * without changing the defaults supplied to `model`, `make`, or `layer`.
+   *
+   * **Details**
+   *
+   * Existing `Config` values from the Effect context are merged with `overrides`,
+   * and the override values take precedence.
+   *
+   * @see {@link Config} for the configuration shape
    *
    * @category configuration
    * @since 4.0.0
    */
   (overrides: typeof Config.Service) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>,
   /**
-   * Provides config overrides for OpenAI language model operations.
+   * Provides scoped config overrides for OpenAI-compatible language model operations.
+   *
+   * **When to use**
+   *
+   * Use to override request configuration for a single language model effect
+   * without changing the defaults supplied to `model`, `make`, or `layer`.
+   *
+   * **Details**
+   *
+   * Existing `Config` values from the Effect context are merged with `overrides`,
+   * and the override values take precedence.
+   *
+   * @see {@link Config} for the configuration shape
    *
    * @category configuration
    * @since 4.0.0

package/src/OpenAiTelemetry.ts

@@ -1,9 +1,35 @@
 /**
- * OpenAI telemetry attributes for OpenTelemetry integration.
+ * The `OpenAiTelemetry` module adds OpenAI-compatible provider attributes to
+ * the provider-neutral GenAI telemetry model. It keeps the standard
+ * `Telemetry.addGenAIAnnotations` attributes and adds OpenAI request and
+ * response metadata under the `gen_ai.openai.*` OpenTelemetry namespaces.
+ *
+ * **Mental model**
+ *
+ * - Standard GenAI attributes come from `effect/unstable/ai/Telemetry`
+ * - OpenAI request attributes are written under `gen_ai.openai.request.*`
+ * - OpenAI response attributes are written under `gen_ai.openai.response.*`
+ * - Attribute option keys are written in camelCase and converted to
+ *   OpenTelemetry snake_case attribute names
+ * - {@link addGenAIAnnotations} mutates the supplied span by adding any
+ *   non-nullish attributes from the option object
+ *
+ * **Common tasks**
+ *
+ * - Use {@link OpenAiTelemetryAttributes} when typing the complete set of
+ *   standard and OpenAI-specific span attributes
+ * - Pass `openai.request` data for requested response format and service tier
+ * - Pass `openai.response` data for the service tier actually used and the
+ *   system fingerprint returned by the provider
+ * - Use {@link addGenAIAnnotations} from an OpenAI-compatible model span to keep
+ *   standard GenAI and provider-specific annotations together
  *
- * Provides OpenAI-specific GenAI telemetry attributes following OpenTelemetry
- * semantic conventions, extending the base GenAI attributes with OpenAI-specific
- * request and response metadata.
+ * **Gotchas**
+ *
+ * - This module only annotates spans; it does not start spans or export traces
+ * - Null and undefined attribute values are skipped instead of being written
+ * - OpenAI-compatible providers may not return every OpenAI-specific response
+ *   field, so only pass fields that are present on the provider response
  *
  * @since 4.0.0
  */
@@ -17,7 +43,12 @@ import * as Telemetry from "effect/unstable/ai/Telemetry"
  * The attributes used to describe telemetry in the context of Generative
  * Artificial Intelligence (GenAI) Models requests and responses.
  *
- * @see https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/
+ * **Details**
+ *
+ * These attributes follow the OpenTelemetry generative AI semantic
+ * conventions:
+ * https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/
+ *
  * @category models
  * @since 4.0.0
  */
@@ -126,6 +157,17 @@ const addOpenAiResponseAttributes = Telemetry.addSpanAttributes("gen_ai.openai.r
  * Applies the specified OpenAi GenAI telemetry attributes to the provided
  * `Span`.
  *
+ * **When to use**
+ *
+ * Use to annotate an OpenAI-compatible model span with standard GenAI telemetry
+ * attributes and OpenAI-specific request or response metadata.
+ *
+ * **Details**
+ *
+ * Standard GenAI attributes are applied first. When OpenAI request or response
+ * metadata is present, it is written under `gen_ai.openai.request.*` and
+ * `gen_ai.openai.response.*` attributes.
+ *
  * **Gotchas**
  *
  * This method will mutate the `Span` **in-place**.
@@ -138,6 +180,17 @@ export const addGenAIAnnotations: {
    * Applies the specified OpenAi GenAI telemetry attributes to the provided
    * `Span`.
    *
+   * **When to use**
+   *
+   * Use to annotate an OpenAI-compatible model span with standard GenAI telemetry
+   * attributes and OpenAI-specific request or response metadata.
+   *
+   * **Details**
+   *
+   * Standard GenAI attributes are applied first. When OpenAI request or response
+   * metadata is present, it is written under `gen_ai.openai.request.*` and
+   * `gen_ai.openai.response.*` attributes.
+   *
    * **Gotchas**
    *
    * This method will mutate the `Span` **in-place**.
@@ -150,6 +203,17 @@ export const addGenAIAnnotations: {
    * Applies the specified OpenAi GenAI telemetry attributes to the provided
    * `Span`.
    *
+   * **When to use**
+   *
+   * Use to annotate an OpenAI-compatible model span with standard GenAI telemetry
+   * attributes and OpenAI-specific request or response metadata.
+   *
+   * **Details**
+   *
+   * Standard GenAI attributes are applied first. When OpenAI request or response
+   * metadata is present, it is written under `gen_ai.openai.request.*` and
+   * `gen_ai.openai.response.*` attributes.
+   *
    * **Gotchas**
    *
    * This method will mutate the `Span` **in-place**.