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

package/src/OpenAiError.ts

@@ -1,12 +1,25 @@
 /**
- * @since 1.0.0
+ * The `OpenAiError` module defines OpenAI-specific metadata that can be
+ * attached to the shared `AiError` error types used by the AI packages. It is
+ * primarily used by OpenAI-compatible clients to preserve provider details
+ * such as error codes, error types, request IDs, and rate limit headers while
+ * still exposing errors through the provider-neutral Effect AI error model.
+ *
+ * Use this module when mapping OpenAI API failures into `AiError` values and
+ * when consumers need enough structured metadata to debug failed requests,
+ * inspect quota or rate limit responses, or correlate an error with OpenAI
+ * support. The exported types are metadata shapes only; the module augmentation
+ * makes those shapes available on the corresponding shared AI error metadata
+ * interfaces without defining new runtime error classes.
+ *
+ * @since 4.0.0
  */
 
 /**
  * OpenAI-specific error metadata fields.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type OpenAiErrorMetadata = {
   /**
@@ -29,8 +42,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 & {
   /**
@@ -52,42 +65,111 @@ export type OpenAiRateLimitMetadata = OpenAiErrorMetadata & {
 }
 
 declare module "effect/unstable/ai/AiError" {
+  /**
+   * Metadata attached to rate limit errors returned by OpenAI-compatible APIs.
+   *
+   * @category models
+   * @since 4.0.0
+   */
   export interface RateLimitErrorMetadata {
     readonly openai?: OpenAiRateLimitMetadata | null
   }
 
+  /**
+   * Metadata attached when an OpenAI-compatible provider reports that quota or
+   * billing limits have been exhausted.
+   *
+   * @category models
+   * @since 4.0.0
+   */
   export interface QuotaExhaustedErrorMetadata {
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * Metadata attached to authentication failures from OpenAI-compatible APIs,
+   * such as invalid, missing, or unauthorized API credentials.
+   *
+   * @category models
+   * @since 4.0.0
+   */
   export interface AuthenticationErrorMetadata {
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * Metadata attached when an OpenAI-compatible provider rejects content because
+   * it violates a safety or usage policy.
+   *
+   * @category models
+   * @since 4.0.0
+   */
   export interface ContentPolicyErrorMetadata {
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * Metadata attached to malformed or unsupported requests rejected by an
+   * OpenAI-compatible API before model execution.
+   *
+   * @category models
+   * @since 4.0.0
+   */
   export interface InvalidRequestErrorMetadata {
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * Metadata attached to unexpected server-side failures reported by an
+   * OpenAI-compatible provider.
+   *
+   * @category models
+   * @since 4.0.0
+   */
   export interface InternalProviderErrorMetadata {
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * Metadata attached when an OpenAI-compatible response cannot be converted
+   * into the expected AI package output shape.
+   *
+   * @category models
+   * @since 4.0.0
+   */
   export interface InvalidOutputErrorMetadata {
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * Metadata attached when an OpenAI-compatible structured output response does
+   * not satisfy the requested schema or parsing constraints.
+   *
+   * @category models
+   * @since 4.0.0
+   */
   export interface StructuredOutputErrorMetadata {
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * Metadata attached when an OpenAI-compatible provider cannot support the
+   * schema supplied for structured output or tool definitions.
+   *
+   * @category models
+   * @since 4.0.0
+   */
   export interface UnsupportedSchemaErrorMetadata {
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * Metadata attached when an OpenAI-compatible error response cannot be mapped
+   * to a more specific shared AI error category.
+   *
+   * @category models
+   * @since 4.0.0
+   */
   export interface UnknownErrorMetadata {
     readonly openai?: OpenAiErrorMetadata | null
   }

package/src/OpenAiLanguageModel.ts

@@ -4,7 +4,7 @@
  * Provides a LanguageModel implementation for OpenAI's chat completions API,
  * supporting text generation, structured output, tool calling, and streaming.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 import * as Context from "effect/Context"
 import * as DateTime from "effect/DateTime"
@@ -61,8 +61,8 @@ type ImageDetail = "auto" | "low" | "high"
 /**
  * Service definition for OpenAI language model configuration.
  *
- * @since 1.0.0
  * @category context
+ * @since 4.0.0
  */
 export class Config extends Context.Service<
   Config,
@@ -112,7 +112,16 @@ export class Config extends Context.Service<
 // =============================================================================
 
 declare module "effect/unstable/ai/Prompt" {
+  /**
+   * OpenAI-compatible options for file prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface FilePartOptions extends ProviderOptions {
+    /**
+     * Provider-specific file options for OpenAI-compatible APIs.
+     */
     readonly openai?: {
       /**
        * The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`.
@@ -121,7 +130,16 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenAI-compatible options for reasoning prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ReasoningPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific reasoning options for OpenAI-compatible APIs.
+     */
     readonly openai?: {
       /**
        * The ID of the item to reference.
@@ -136,40 +154,67 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenAI-compatible options for assistant tool-call prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolCallPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific tool-call options for OpenAI-compatible APIs.
+     */
     readonly openai?: {
       /**
        * The ID of the item to reference.
        */
       readonly itemId?: string | null
       /**
-       * The status of item.
+       * The status to send for the tool-call item.
        */
       readonly status?: MessageStatus | null
     } | null
   }
 
+  /**
+   * OpenAI-compatible options for tool-result prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolResultPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific tool-result options for OpenAI-compatible APIs.
+     */
     readonly openai?: {
       /**
        * The ID of the item to reference.
        */
       readonly itemId?: string | null
       /**
-       * The status of item.
+       * The status to send for the tool-result item.
        */
       readonly status?: MessageStatus | null
     } | null
   }
 
+  /**
+   * OpenAI-compatible options for text prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface TextPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific text options for OpenAI-compatible APIs.
+     */
     readonly openai?: {
       /**
        * The ID of the item to reference.
        */
       readonly itemId?: string | null
       /**
-       * The status of item.
+       * The status to send for the text item.
        */
       readonly status?: MessageStatus | null
       /**
@@ -181,8 +226,20 @@ declare module "effect/unstable/ai/Prompt" {
 }
 
 declare module "effect/unstable/ai/Response" {
+  /**
+   * OpenAI-compatible metadata attached to a complete text response part.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface TextPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the text part.
+     */
     readonly openai?: {
+      /**
+       * The OpenAI item ID associated with the text part.
+       */
       readonly itemId?: string | null
       /**
        * If the model emits a refusal content part, the refusal explanation
@@ -191,7 +248,7 @@ declare module "effect/unstable/ai/Response" {
        */
       readonly refusal?: string | null
       /**
-       * The status of item.
+       * The status returned for the text item.
        */
       readonly status?: MessageStatus | null
       /**
@@ -201,55 +258,163 @@ declare module "effect/unstable/ai/Response" {
     }
   }
 
+  /**
+   * OpenAI-compatible metadata emitted when a streamed text part starts.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface TextStartPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the streamed text start.
+     */
     readonly openai?: {
+      /**
+       * The OpenAI item ID associated with the streamed text part.
+       */
       readonly itemId?: string | null
     } | null
   }
 
+  /**
+   * OpenAI-compatible metadata emitted when a streamed text part ends.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface TextEndPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the streamed text end.
+     */
     readonly openai?: {
+      /**
+       * The OpenAI item ID associated with the streamed text part.
+       */
       readonly itemId?: string | null
+      /**
+       * The annotations collected for the completed streamed text part.
+       */
       readonly annotations?: ReadonlyArray<Annotation> | null
     } | null
   }
 
+  /**
+   * OpenAI-compatible metadata attached to a complete reasoning response part.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the reasoning part.
+     */
     readonly openai?: {
+      /**
+       * The OpenAI item ID associated with the reasoning part.
+       */
       readonly itemId?: string | null
+      /**
+       * Encrypted reasoning content that can be sent back in later requests.
+       */
       readonly encryptedContent?: string | null
     } | null
   }
 
+  /**
+   * OpenAI-compatible metadata emitted when a streamed reasoning part starts.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningStartPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the streamed reasoning start.
+     */
     readonly openai?: {
+      /**
+       * The OpenAI item ID associated with the reasoning part.
+       */
       readonly itemId?: string | null
+      /**
+       * Encrypted reasoning content that can be sent back in later requests.
+       */
       readonly encryptedContent?: string | null
     } | null
   }
 
+  /**
+   * OpenAI-compatible metadata emitted for a streamed reasoning delta.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningDeltaPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the streamed reasoning delta.
+     */
     readonly openai?: {
+      /**
+       * The OpenAI item ID associated with the reasoning part.
+       */
       readonly itemId?: string | null
     } | null
   }
 
+  /**
+   * OpenAI-compatible metadata emitted when a streamed reasoning part ends.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningEndPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the streamed reasoning end.
+     */
     readonly openai?: {
+      /**
+       * The OpenAI item ID associated with the reasoning part.
+       */
       readonly itemId?: string | null
+      /**
+       * Encrypted reasoning content that can be sent back in later requests.
+       */
       readonly encryptedContent?: string
     } | null
   }
 
+  /**
+   * OpenAI-compatible metadata attached to tool-call response parts.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ToolCallPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the tool call.
+     */
     readonly openai?: {
+      /**
+       * The OpenAI item ID associated with the tool call.
+       */
       readonly itemId?: string | null
     } | null
   }
 
+  /**
+   * OpenAI-compatible metadata attached to document source citations.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface DocumentSourcePartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific citation metadata for OpenAI-compatible APIs.
+     */
     readonly openai?:
       | {
+        /**
+         * Identifies a citation to an uploaded file.
+         */
         readonly type: "file_citation"
         /**
          * The index of the file in the list of files.
@@ -261,6 +426,9 @@ declare module "effect/unstable/ai/Response" {
         readonly fileId: string
       }
       | {
+        /**
+         * Identifies a citation to a generated file path.
+         */
         readonly type: "file_path"
         /**
          * The index of the file in the list of files.
@@ -272,6 +440,9 @@ declare module "effect/unstable/ai/Response" {
         readonly fileId: string
       }
       | {
+        /**
+         * Identifies a citation to a file inside a container.
+         */
         readonly type: "container_file_citation"
         /**
          * The ID of the file.
@@ -285,8 +456,20 @@ declare module "effect/unstable/ai/Response" {
       | null
   }
 
+  /**
+   * OpenAI-compatible metadata attached to URL source citations.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface UrlSourcePartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific URL citation metadata for OpenAI-compatible APIs.
+     */
     readonly openai?: {
+      /**
+       * Identifies a citation to a URL.
+       */
       readonly type: "url_citation"
       /**
        * The index of the first character of the URL citation in the message.
@@ -299,8 +482,20 @@ declare module "effect/unstable/ai/Response" {
     } | null
   }
 
+  /**
+   * OpenAI-compatible metadata attached to finish response parts.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface FinishPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned when generation finishes.
+     */
     readonly openai?: {
+      /**
+       * The service tier reported by the OpenAI-compatible provider.
+       */
       readonly serviceTier?: "default" | "auto" | "flex" | "scale" | "priority" | null
     } | null
   }
@@ -311,8 +506,10 @@ declare module "effect/unstable/ai/Response" {
 // =============================================================================
 
 /**
- * @since 1.0.0
+ * Creates an AI model descriptor for an OpenAI-compatible language model.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const model = (
   model: string,
@@ -322,7 +519,7 @@ export const model = (
 
 // TODO
 // /**
-//  * @since 1.0.0
+//  * @since 4.0.0
 //  * @category constructors
 //  */
 // export const modelWithTokenizer = (
@@ -334,8 +531,8 @@ export const model = (
 /**
  * Creates an OpenAI language model service.
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.fnUntraced(function*({ model, config: providerConfig }: {
   readonly model: string
@@ -433,8 +630,8 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
 /**
  * Creates a layer for the OpenAI language model.
  *
- * @since 1.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (options: {
   readonly model: string
@@ -445,37 +642,37 @@ export const layer = (options: {
 /**
  * Provides config overrides for OpenAI language model operations.
  *
- * @since 1.0.0
  * @category configuration
+ * @since 4.0.0
  */
 export const withConfigOverride: {
   /**
    * Provides config overrides for OpenAI language 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 language 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 language 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 language 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/OpenAiTelemetry.ts

@@ -5,7 +5,7 @@
  * semantic conventions, extending the base GenAI attributes with OpenAI-specific
  * request and response metadata.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 import { dual } from "effect/Function"
 import * as String from "effect/String"
@@ -19,8 +19,8 @@ import * as Telemetry from "effect/unstable/ai/Telemetry"
  *
  * {@see https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/}
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type OpenAiTelemetryAttributes = Simplify<
   & Telemetry.GenAITelemetryAttributes
@@ -32,8 +32,8 @@ export type OpenAiTelemetryAttributes = Simplify<
  * All telemetry attributes which are part of the GenAI specification,
  * including the OpenAi-specific attributes.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AllAttributes = Telemetry.AllAttributes & RequestAttributes & ResponseAttributes
 
@@ -41,8 +41,8 @@ export type AllAttributes = Telemetry.AllAttributes & RequestAttributes & Respon
  * Telemetry attributes which are part of the GenAI specification and are
  * namespaced by `gen_ai.openai.request`.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface RequestAttributes {
   /**
@@ -59,8 +59,8 @@ export interface RequestAttributes {
  * Telemetry attributes which are part of the GenAI specification and are
  * namespaced by `gen_ai.openai.response`.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ResponseAttributes {
   /**
@@ -81,8 +81,8 @@ export interface ResponseAttributes {
  * If one of them applies, then the respective value **MUST** be used;
  * otherwise, a custom value **MAY** be used.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type WellKnownResponseFormat = "json_object" | "json_schema" | "text"
 
@@ -93,14 +93,17 @@ export type WellKnownResponseFormat = "json_object" | "json_schema" | "text"
  * If one of them applies, then the respective value **MUST** be used;
  * otherwise, a custom value **MAY** be used.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type WellKnownServiceTier = "auto" | "default"
 
 /**
- * @since 1.0.0
- * @since models
+ * Options accepted by `addGenAIAnnotations`, combining standard GenAI telemetry
+ * attributes with optional OpenAI-compatible request and response attributes.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type OpenAiTelemetryAttributeOptions = Telemetry.GenAITelemetryAttributeOptions & {
   openai?: {
@@ -122,8 +125,8 @@ const addOpenAiResponseAttributes = Telemetry.addSpanAttributes("gen_ai.openai.r
  *
  * **NOTE**: This method will mutate the `Span` **in-place**.
  *
- * @since 1.0.0
- * @since utilities
+ * @category tracing
+ * @since 4.0.0
  */
 export const addGenAIAnnotations: {
   /**
@@ -132,8 +135,8 @@ export const addGenAIAnnotations: {
    *
    * **NOTE**: This method will mutate the `Span` **in-place**.
    *
-   * @since 1.0.0
-   * @since utilities
+   * @category tracing
+   * @since 4.0.0
    */
   (options: OpenAiTelemetryAttributeOptions): (span: Span) => void
   /**
@@ -142,8 +145,8 @@ export const addGenAIAnnotations: {
    *
    * **NOTE**: This method will mutate the `Span` **in-place**.
    *
-   * @since 1.0.0
-   * @since utilities
+   * @category tracing
+   * @since 4.0.0
    */
   (span: Span, options: OpenAiTelemetryAttributeOptions): void
 } = dual(2, (span: Span, options: OpenAiTelemetryAttributeOptions) => {