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

package/src/OpenAiClient.ts

@@ -77,7 +77,7 @@ export interface Service {
  * Context service tag for accessing an OpenAI-compatible client from the
  * Effect context.
  *
- * @category service
+ * @category services
  * @since 4.0.0
  */
 export class OpenAiClient extends Context.Service<OpenAiClient, Service>()(
@@ -302,6 +302,7 @@ type JsonObject = { readonly [x: string]: Schema.Json }
 /**
  * Optional response fields that can be requested with the `include` parameter.
  *
+ * @category response
  * @since 4.0.0
  */
 export type IncludeEnum =
@@ -312,6 +313,7 @@ export type IncludeEnum =
 /**
  * Lifecycle status shared by message, reasoning, and tool-call items.
  *
+ * @category models
  * @since 4.0.0
  */
 export type MessageStatus = "in_progress" | "completed" | "incomplete"
@@ -339,6 +341,7 @@ type InputFileContent = {
 /**
  * Content blocks accepted in input messages.
  *
+ * @category request
  * @since 4.0.0
  */
 export type InputContent = InputTextContent | InputImageContent | InputFileContent
@@ -346,6 +349,7 @@ export type InputContent = InputTextContent | InputImageContent | InputFileConte
 /**
  * Text content block used for model-provided reasoning summaries.
  *
+ * @category response
  * @since 4.0.0
  */
 export type SummaryTextContent = {
@@ -407,6 +411,7 @@ type FilePathAnnotation = {
 /**
  * Citation and file-path annotations attached to output text content.
  *
+ * @category response
  * @since 4.0.0
  */
 export type Annotation =
@@ -445,6 +450,7 @@ type OutputMessage = {
  * Reasoning output item containing encrypted reasoning content, summaries, and
  * optional reasoning text.
  *
+ * @category response
  * @since 4.0.0
  */
 export type ReasoningItem = {
@@ -499,6 +505,7 @@ type ItemReference = {
  * Supports input messages, output messages, tool calls, tool outputs, reasoning
  * items, custom tool interactions, and item references.
  *
+ * @category request
  * @since 4.0.0
  */
 export type InputItem =
@@ -539,6 +546,7 @@ type CustomToolParam = {
 /**
  * Tool definitions that can be supplied to a Responses-style request.
  *
+ * @category request
  * @since 4.0.0
  */
 export type Tool =
@@ -567,6 +575,7 @@ type ToolChoice =
  * Text output format configuration for plain text, JSON object, or JSON Schema
  * responses.
  *
+ * @category configuration
  * @since 4.0.0
  */
 export type TextResponseFormatConfiguration =
@@ -588,6 +597,7 @@ export type TextResponseFormatConfiguration =
  * Request options for creating a Responses-style response with an
  * OpenAI-compatible provider.
  *
+ * @category request
  * @since 4.0.0
  */
 export type CreateResponse = {
@@ -627,6 +637,7 @@ export type CreateResponse = {
 /**
  * Token accounting reported on Responses-style response objects.
  *
+ * @category response
  * @since 4.0.0
  */
 export type ResponseUsage = {
@@ -647,6 +658,7 @@ type OutputItem =
  * Responses-style response object returned by compatible providers or embedded
  * in response stream lifecycle events.
  *
+ * @category response
  * @since 4.0.0
  */
 export type Response = {
@@ -775,6 +787,7 @@ type UnknownResponseStreamEvent = {
 /**
  * Server-sent event shapes emitted by Responses-style response streams.
  *
+ * @category streaming
  * @since 4.0.0
  */
 export type ResponseStreamEvent =
@@ -802,6 +815,7 @@ export type ResponseStreamEvent =
  * string. The `index` field identifies the input item that produced this
  * embedding.
  *
+ * @category response
  * @since 4.0.0
  */
 export type Embedding = {
@@ -813,6 +827,7 @@ export type Embedding = {
 /**
  * Request payload for the embeddings endpoint.
  *
+ * @category request
  * @since 4.0.0
  */
 export type CreateEmbeddingRequest = {
@@ -826,6 +841,7 @@ export type CreateEmbeddingRequest = {
 /**
  * Successful response payload returned by the embeddings endpoint.
  *
+ * @category response
  * @since 4.0.0
  */
 export type CreateEmbeddingResponse = {
@@ -841,18 +857,21 @@ export type CreateEmbeddingResponse = {
 /**
  * JSON request body accepted by the embeddings endpoint.
  *
+ * @category request
  * @since 4.0.0
  */
 export type CreateEmbeddingRequestJson = CreateEmbeddingRequest
 /**
  * Decoded successful embeddings response body.
  *
+ * @category response
  * @since 4.0.0
  */
 export type CreateEmbedding200 = CreateEmbeddingResponse
 /**
  * Structured content parts accepted in chat completion messages.
  *
+ * @category request
  * @since 4.0.0
  */
 export type ChatCompletionContentPart =
@@ -870,6 +889,7 @@ export type ChatCompletionContentPart =
 /**
  * Tool call data attached to an assistant chat completion message.
  *
+ * @category request
  * @since 4.0.0
  */
 export type ChatCompletionRequestToolCall = {
@@ -883,6 +903,7 @@ export type ChatCompletionRequestToolCall = {
 /**
  * Message shapes accepted by the chat completions endpoint.
  *
+ * @category request
  * @since 4.0.0
  */
 export type ChatCompletionRequestMessage =
@@ -899,6 +920,7 @@ export type ChatCompletionRequestMessage =
 /**
  * Function tool definition accepted by the chat completions endpoint.
  *
+ * @category request
  * @since 4.0.0
  */
 export type ChatCompletionTool = {
@@ -913,6 +935,7 @@ export type ChatCompletionTool = {
 /**
  * Controls whether the model may call tools and can force a specific function.
  *
+ * @category configuration
  * @since 4.0.0
  */
 export type ChatCompletionToolChoice =
@@ -928,6 +951,7 @@ export type ChatCompletionToolChoice =
 /**
  * JSON response format configuration for chat completion requests.
  *
+ * @category configuration
  * @since 4.0.0
  */
 export type ChatCompletionResponseFormat =
@@ -946,6 +970,7 @@ export type ChatCompletionResponseFormat =
 /**
  * Request payload for the OpenAI-compatible chat completions endpoint.
  *
+ * @category request
  * @since 4.0.0
  */
 export type ChatCompletionRequest = {
@@ -971,18 +996,21 @@ export type ChatCompletionRequest = {
 /**
  * JSON request body used by this client when creating a chat completion response.
  *
+ * @category request
  * @since 4.0.0
  */
 export type CreateResponseRequestJson = ChatCompletionRequest
 /**
  * Decoded successful chat completion response body returned by `createResponse`.
  *
+ * @category response
  * @since 4.0.0
  */
 export type CreateResponse200 = ChatCompletionResponse
 /**
  * Decoded server-sent event payload emitted by `createResponseStream`.
  *
+ * @category streaming
  * @since 4.0.0
  */
 export type CreateResponse200Sse = ChatCompletionStreamEvent
@@ -1075,36 +1103,42 @@ const ChatCompletionChunk = Schema.Struct({
 /**
  * Decoded tool-call object from a chat completion response or streaming chunk.
  *
+ * @category response
  * @since 4.0.0
  */
 export type ChatCompletionToolCall = typeof ChatCompletionToolCall.Type
 /**
  * Decoded message object from a non-streaming chat completion choice.
  *
+ * @category response
  * @since 4.0.0
  */
 export type ChatCompletionMessage = typeof ChatCompletionMessage.Type
 /**
  * Decoded choice object returned by chat completion responses and chunks.
  *
+ * @category response
  * @since 4.0.0
  */
 export type ChatCompletionChoice = typeof ChatCompletionChoice.Type
 /**
  * Decoded token usage summary returned by chat completions.
  *
+ * @category response
  * @since 4.0.0
  */
 export type ChatCompletionUsage = typeof ChatCompletionUsage.Type
 /**
  * Decoded successful response from the chat completions endpoint.
  *
+ * @category response
  * @since 4.0.0
  */
 export type ChatCompletionResponse = typeof ChatCompletionResponse.Type
 /**
  * Decoded streaming chunk emitted by the chat completions endpoint.
  *
+ * @category streaming
  * @since 4.0.0
  */
 export type ChatCompletionChunk = typeof ChatCompletionChunk.Type
@@ -1112,6 +1146,7 @@ export type ChatCompletionChunk = typeof ChatCompletionChunk.Type
  * Streaming chat completion event, including decoded chunks and the `[DONE]`
  * sentinel.
  *
+ * @category streaming
  * @since 4.0.0
  */
 export type ChatCompletionStreamEvent = ChatCompletionChunk | "[DONE]"

package/src/OpenAiConfig.ts

@@ -59,7 +59,7 @@ export declare namespace OpenAiConfig {
    * resolve the underlying HTTP client.
    *
    * @category models
-   * @since 1.0.
+   * @since 4.0.0
    */
   export interface Service {
     readonly transformClient?: ((client: HttpClient) => HttpClient) | undefined

package/src/OpenAiLanguageModel.ts

@@ -114,6 +114,9 @@ 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 {
     /**
@@ -129,6 +132,9 @@ declare module "effect/unstable/ai/Prompt" {
 
   /**
    * OpenAI-compatible options for reasoning prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
    */
   export interface ReasoningPartOptions extends ProviderOptions {
     /**
@@ -150,6 +156,9 @@ declare module "effect/unstable/ai/Prompt" {
 
   /**
    * OpenAI-compatible options for assistant tool-call prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
    */
   export interface ToolCallPartOptions extends ProviderOptions {
     /**
@@ -169,6 +178,9 @@ declare module "effect/unstable/ai/Prompt" {
 
   /**
    * OpenAI-compatible options for tool-result prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
    */
   export interface ToolResultPartOptions extends ProviderOptions {
     /**
@@ -188,6 +200,9 @@ declare module "effect/unstable/ai/Prompt" {
 
   /**
    * OpenAI-compatible options for text prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
    */
   export interface TextPartOptions extends ProviderOptions {
     /**
@@ -213,6 +228,9 @@ 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 {
     /**
@@ -242,6 +260,9 @@ 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 {
     /**
@@ -257,6 +278,9 @@ declare module "effect/unstable/ai/Response" {
 
   /**
    * OpenAI-compatible metadata emitted when a streamed text part ends.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface TextEndPartMetadata extends ProviderMetadata {
     /**
@@ -276,6 +300,9 @@ declare module "effect/unstable/ai/Response" {
 
   /**
    * OpenAI-compatible metadata attached to a complete reasoning response part.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface ReasoningPartMetadata extends ProviderMetadata {
     /**
@@ -295,6 +322,9 @@ declare module "effect/unstable/ai/Response" {
 
   /**
    * OpenAI-compatible metadata emitted when a streamed reasoning part starts.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface ReasoningStartPartMetadata extends ProviderMetadata {
     /**
@@ -314,6 +344,9 @@ declare module "effect/unstable/ai/Response" {
 
   /**
    * OpenAI-compatible metadata emitted for a streamed reasoning delta.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface ReasoningDeltaPartMetadata extends ProviderMetadata {
     /**
@@ -329,6 +362,9 @@ declare module "effect/unstable/ai/Response" {
 
   /**
    * OpenAI-compatible metadata emitted when a streamed reasoning part ends.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface ReasoningEndPartMetadata extends ProviderMetadata {
     /**
@@ -348,6 +384,9 @@ declare module "effect/unstable/ai/Response" {
 
   /**
    * OpenAI-compatible metadata attached to tool-call response parts.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface ToolCallPartMetadata extends ProviderMetadata {
     /**
@@ -363,6 +402,9 @@ declare module "effect/unstable/ai/Response" {
 
   /**
    * OpenAI-compatible metadata attached to document source citations.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface DocumentSourcePartMetadata extends ProviderMetadata {
     /**
@@ -416,6 +458,9 @@ declare module "effect/unstable/ai/Response" {
 
   /**
    * OpenAI-compatible metadata attached to URL source citations.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface UrlSourcePartMetadata extends ProviderMetadata {
     /**
@@ -439,6 +484,9 @@ declare module "effect/unstable/ai/Response" {
 
   /**
    * OpenAI-compatible metadata attached to finish response parts.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface FinishPartMetadata extends ProviderMetadata {
     /**

package/src/OpenAiTelemetry.ts

@@ -102,8 +102,8 @@ export type WellKnownServiceTier = "auto" | "default"
  * Options accepted by `addGenAIAnnotations`, combining standard GenAI telemetry
  * attributes with optional OpenAI-compatible request and response attributes.
  *
+ * @category models
  * @since 4.0.0
- * @since models
  */
 export type OpenAiTelemetryAttributeOptions = Telemetry.GenAITelemetryAttributeOptions & {
   openai?: {
@@ -125,8 +125,8 @@ const addOpenAiResponseAttributes = Telemetry.addSpanAttributes("gen_ai.openai.r
  *
  * **NOTE**: This method will mutate the `Span` **in-place**.
  *
+ * @category tracing
  * @since 4.0.0
- * @since utilities
  */
 export const addGenAIAnnotations: {
   /**
@@ -135,8 +135,8 @@ export const addGenAIAnnotations: {
    *
    * **NOTE**: This method will mutate the `Span` **in-place**.
    *
+   * @category tracing
    * @since 4.0.0
-   * @since utilities
    */
   (options: OpenAiTelemetryAttributeOptions): (span: Span) => void
   /**
@@ -145,8 +145,8 @@ export const addGenAIAnnotations: {
    *
    * **NOTE**: This method will mutate the `Span` **in-place**.
    *
+   * @category tracing
    * @since 4.0.0
-   * @since utilities
    */
   (span: Span, options: OpenAiTelemetryAttributeOptions): void
 } = dual(2, (span: Span, options: OpenAiTelemetryAttributeOptions) => {

package/src/index.ts

@@ -5,11 +5,54 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
+ * The `OpenAiClient` module provides an Effect service for calling
+ * OpenAI-compatible chat completions and embeddings APIs. It builds on the
+ * Effect HTTP client, adds authentication and OpenAI header handling, and
+ * exposes typed helpers for regular responses, server-sent event streaming, and
+ * embedding requests.
+ *
+ * **Common tasks**
+ *
+ * - Create a client service directly with {@link make}
+ * - Provide the service as a layer with {@link layer} or {@link layerConfig}
+ * - Send non-streaming chat completion requests with `createResponse`
+ * - Send streaming chat completion requests with `createResponseStream`
+ * - Generate embeddings with `createEmbedding`
+ * - Reuse the exported request and response types when integrating compatible providers
+ *
+ * **Gotchas**
+ *
+ * - The default base URL is `https://api.openai.com/v1`; set `apiUrl` for other
+ *   OpenAI-compatible providers.
+ * - `createResponseStream` forces `stream: true` and requests usage events with
+ *   `stream_options.include_usage`.
+ * - HTTP and schema decoding failures are mapped into `AiError`.
+ *
  * @since 4.0.0
  */
 export * as OpenAiClient from "./OpenAiClient.ts"
 
 /**
+ * The `OpenAiConfig` module provides shared configuration for clients that
+ * talk to OpenAI-compatible APIs. It is used to customize the HTTP client
+ * wiring around a provider without changing the higher-level model,
+ * embeddings, or tool-calling APIs that consume the client.
+ *
+ * **Common tasks**
+ *
+ * - Install a client transform with {@link withClientTransform}
+ * - Add provider-specific HTTP behavior, such as headers, retries, proxies, or
+ *   instrumentation
+ * - Read the active configuration from the Effect context when implementing
+ *   OpenAI-compatible integrations
+ *
+ * **Gotchas**
+ *
+ * - The transform receives and returns an `HttpClient`, so it should preserve
+ *   the existing client behavior unless it intentionally replaces it
+ * - Configuration is provided through Effect context and is scoped to the
+ *   effect that receives the service
+ *
  * @since 4.0.0
  */
 export * as OpenAiConfig from "./OpenAiConfig.ts"
@@ -24,6 +67,19 @@ export * as OpenAiConfig from "./OpenAiConfig.ts"
 export * as OpenAiEmbeddingModel from "./OpenAiEmbeddingModel.ts"
 
 /**
+ * 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
  */
 export * as OpenAiError from "./OpenAiError.ts"