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

package/src/OpenAiClient.ts

@@ -1,5 +1,28 @@
 /**
- * @since 1.0.0
+ * 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
  */
 import * as Array from "effect/Array"
 import type * as Config from "effect/Config"
@@ -20,8 +43,13 @@ import * as Errors from "./internal/errors.ts"
 import { OpenAiConfig } from "./OpenAiConfig.ts"
 
 /**
- * @since 1.0.0
+ * Effect service interface for OpenAI-compatible chat completions and embeddings.
+ *
+ * **Details**
+ * Exposes the configured HTTP client plus helpers for non-streaming chat completions, streaming chat completions, and embeddings. Transport and schema decoding failures are mapped to `AiError`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Service {
   readonly client: HttpClient.HttpClient
@@ -46,16 +74,21 @@ export interface Service {
 }
 
 /**
- * @since 1.0.0
- * @category service
+ * Context service tag for accessing an OpenAI-compatible client from the
+ * Effect context.
+ *
+ * @category services
+ * @since 4.0.0
  */
 export class OpenAiClient extends Context.Service<OpenAiClient, Service>()(
   "@effect/ai-openai-compat/OpenAiClient"
 ) {}
 
 /**
- * @since 1.0.0
+ * Configuration options used to construct an OpenAI-compatible client.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Options = {
   readonly apiKey?: Redacted.Redacted<string> | undefined
@@ -71,8 +104,13 @@ const RedactedOpenAiHeaders = {
 }
 
 /**
- * @since 1.0.0
+ * Constructs an OpenAI-compatible client service from explicit options.
+ *
+ * The returned service applies the configured base URL, authentication, and
+ * OpenAI organization/project headers to the underlying HTTP client.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.fnUntraced(
   function*(options: Options): Effect.fn.Return<Service, never, HttpClient.HttpClient> {
@@ -212,15 +250,20 @@ export const make = Effect.fnUntraced(
 )
 
 /**
- * @since 1.0.0
+ * Creates a layer that provides an OpenAI-compatible client from explicit options.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (options: Options): Layer.Layer<OpenAiClient, never, HttpClient.HttpClient> =>
   Layer.effect(OpenAiClient, make(options))
 
 /**
- * @since 1.0.0
+ * Creates a layer that loads OpenAI-compatible client settings from `Config`
+ * values before constructing the service.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerConfig = (options?: {
   readonly apiKey?: Config.Config<Redacted.Redacted<string> | undefined> | undefined
@@ -257,7 +300,10 @@ export const layerConfig = (options?: {
 type JsonObject = { readonly [x: string]: Schema.Json }
 
 /**
- * @since 1.0.0
+ * Optional response fields that can be requested with the `include` parameter.
+ *
+ * @category response
+ * @since 4.0.0
  */
 export type IncludeEnum =
   | "message.input_image.image_url"
@@ -265,7 +311,10 @@ export type IncludeEnum =
   | "message.output_text.logprobs"
 
 /**
- * @since 1.0.0
+ * Lifecycle status shared by message, reasoning, and tool-call items.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type MessageStatus = "in_progress" | "completed" | "incomplete"
 
@@ -290,12 +339,18 @@ type InputFileContent = {
 }
 
 /**
- * @since 1.0.0
+ * Content blocks accepted in input messages.
+ *
+ * @category request
+ * @since 4.0.0
  */
 export type InputContent = InputTextContent | InputImageContent | InputFileContent
 
 /**
- * @since 1.0.0
+ * Text content block used for model-provided reasoning summaries.
+ *
+ * @category response
+ * @since 4.0.0
  */
 export type SummaryTextContent = {
   readonly type: "summary_text"
@@ -354,7 +409,10 @@ type FilePathAnnotation = {
 }
 
 /**
- * @since 1.0.0
+ * Citation and file-path annotations attached to output text content.
+ *
+ * @category response
+ * @since 4.0.0
  */
 export type Annotation =
   | FileCitationAnnotation
@@ -389,7 +447,11 @@ type OutputMessage = {
 }
 
 /**
- * @since 1.0.0
+ * Reasoning output item containing encrypted reasoning content, summaries, and
+ * optional reasoning text.
+ *
+ * @category response
+ * @since 4.0.0
  */
 export type ReasoningItem = {
   readonly type: "reasoning"
@@ -438,7 +500,13 @@ type ItemReference = {
 }
 
 /**
- * @since 1.0.0
+ * Item shapes accepted by a Responses-style `input` field.
+ *
+ * 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 =
   | {
@@ -476,7 +544,10 @@ type CustomToolParam = {
 }
 
 /**
- * @since 1.0.0
+ * Tool definitions that can be supplied to a Responses-style request.
+ *
+ * @category request
+ * @since 4.0.0
  */
 export type Tool =
   | FunctionTool
@@ -501,7 +572,11 @@ type ToolChoice =
   }
 
 /**
- * @since 1.0.0
+ * Text output format configuration for plain text, JSON object, or JSON Schema
+ * responses.
+ *
+ * @category configuration
+ * @since 4.0.0
  */
 export type TextResponseFormatConfiguration =
   | {
@@ -519,7 +594,11 @@ export type TextResponseFormatConfiguration =
   }
 
 /**
- * @since 1.0.0
+ * Request options for creating a Responses-style response with an
+ * OpenAI-compatible provider.
+ *
+ * @category request
+ * @since 4.0.0
  */
 export type CreateResponse = {
   readonly metadata?: Readonly<Record<string, string>> | null | undefined
@@ -556,7 +635,10 @@ export type CreateResponse = {
 }
 
 /**
- * @since 1.0.0
+ * Token accounting reported on Responses-style response objects.
+ *
+ * @category response
+ * @since 4.0.0
  */
 export type ResponseUsage = {
   readonly input_tokens: number
@@ -573,7 +655,11 @@ type OutputItem =
   | CustomToolCall
 
 /**
- * @since 1.0.0
+ * Responses-style response object returned by compatible providers or embedded
+ * in response stream lifecycle events.
+ *
+ * @category response
+ * @since 4.0.0
  */
 export type Response = {
   readonly id: string
@@ -699,7 +785,10 @@ type UnknownResponseStreamEvent = {
 }
 
 /**
- * @since 1.0.0
+ * Server-sent event shapes emitted by Responses-style response streams.
+ *
+ * @category streaming
+ * @since 4.0.0
  */
 export type ResponseStreamEvent =
   | ResponseCreatedEvent
@@ -718,7 +807,16 @@ export type ResponseStreamEvent =
   | UnknownResponseStreamEvent
 
 /**
- * @since 1.0.0
+ * Represents one embedding item returned by an OpenAI-compatible embeddings API.
+ *
+ * **Details**
+ *
+ * The embedding can be returned either as a numeric vector or as a base64-encoded
+ * string. The `index` field identifies the input item that produced this
+ * embedding.
+ *
+ * @category response
+ * @since 4.0.0
  */
 export type Embedding = {
   readonly embedding: ReadonlyArray<number> | string
@@ -727,7 +825,10 @@ export type Embedding = {
 }
 
 /**
- * @since 1.0.0
+ * Request payload for the embeddings endpoint.
+ *
+ * @category request
+ * @since 4.0.0
  */
 export type CreateEmbeddingRequest = {
   readonly input: string | ReadonlyArray<string> | ReadonlyArray<number> | ReadonlyArray<ReadonlyArray<number>>
@@ -738,7 +839,10 @@ export type CreateEmbeddingRequest = {
 }
 
 /**
- * @since 1.0.0
+ * Successful response payload returned by the embeddings endpoint.
+ *
+ * @category response
+ * @since 4.0.0
  */
 export type CreateEmbeddingResponse = {
   readonly data: ReadonlyArray<Embedding>
@@ -751,15 +855,24 @@ export type CreateEmbeddingResponse = {
 }
 
 /**
- * @since 1.0.0
+ * JSON request body accepted by the embeddings endpoint.
+ *
+ * @category request
+ * @since 4.0.0
  */
 export type CreateEmbeddingRequestJson = CreateEmbeddingRequest
 /**
- * @since 1.0.0
+ * Decoded successful embeddings response body.
+ *
+ * @category response
+ * @since 4.0.0
  */
 export type CreateEmbedding200 = CreateEmbeddingResponse
 /**
- * @since 1.0.0
+ * Structured content parts accepted in chat completion messages.
+ *
+ * @category request
+ * @since 4.0.0
  */
 export type ChatCompletionContentPart =
   | {
@@ -774,7 +887,10 @@ export type ChatCompletionContentPart =
     }
   }
 /**
- * @since 1.0.0
+ * Tool call data attached to an assistant chat completion message.
+ *
+ * @category request
+ * @since 4.0.0
  */
 export type ChatCompletionRequestToolCall = {
   readonly id: string
@@ -785,7 +901,10 @@ export type ChatCompletionRequestToolCall = {
   }
 }
 /**
- * @since 1.0.0
+ * Message shapes accepted by the chat completions endpoint.
+ *
+ * @category request
+ * @since 4.0.0
  */
 export type ChatCompletionRequestMessage =
   | {
@@ -799,7 +918,10 @@ export type ChatCompletionRequestMessage =
     readonly content: string
   }
 /**
- * @since 1.0.0
+ * Function tool definition accepted by the chat completions endpoint.
+ *
+ * @category request
+ * @since 4.0.0
  */
 export type ChatCompletionTool = {
   readonly type: "function"
@@ -811,7 +933,10 @@ export type ChatCompletionTool = {
   }
 }
 /**
- * @since 1.0.0
+ * Controls whether the model may call tools and can force a specific function.
+ *
+ * @category configuration
+ * @since 4.0.0
  */
 export type ChatCompletionToolChoice =
   | "none"
@@ -824,7 +949,10 @@ export type ChatCompletionToolChoice =
     }
   }
 /**
- * @since 1.0.0
+ * JSON response format configuration for chat completion requests.
+ *
+ * @category configuration
+ * @since 4.0.0
  */
 export type ChatCompletionResponseFormat =
   | {
@@ -840,7 +968,10 @@ export type ChatCompletionResponseFormat =
     }
   }
 /**
- * @since 1.0.0
+ * Request payload for the OpenAI-compatible chat completions endpoint.
+ *
+ * @category request
+ * @since 4.0.0
  */
 export type ChatCompletionRequest = {
   readonly model: string
@@ -863,15 +994,24 @@ export type ChatCompletionRequest = {
   readonly [x: string]: unknown
 }
 /**
- * @since 1.0.0
+ * JSON request body used by this client when creating a chat completion response.
+ *
+ * @category request
+ * @since 4.0.0
  */
 export type CreateResponseRequestJson = ChatCompletionRequest
 /**
- * @since 1.0.0
+ * Decoded successful chat completion response body returned by `createResponse`.
+ *
+ * @category response
+ * @since 4.0.0
  */
 export type CreateResponse200 = ChatCompletionResponse
 /**
- * @since 1.0.0
+ * Decoded server-sent event payload emitted by `createResponseStream`.
+ *
+ * @category streaming
+ * @since 4.0.0
  */
 export type CreateResponse200Sse = ChatCompletionStreamEvent
 
@@ -961,31 +1101,53 @@ const ChatCompletionChunk = Schema.Struct({
 })
 
 /**
- * @since 1.0.0
+ * Decoded tool-call object from a chat completion response or streaming chunk.
+ *
+ * @category response
+ * @since 4.0.0
  */
 export type ChatCompletionToolCall = typeof ChatCompletionToolCall.Type
 /**
- * @since 1.0.0
+ * Decoded message object from a non-streaming chat completion choice.
+ *
+ * @category response
+ * @since 4.0.0
  */
 export type ChatCompletionMessage = typeof ChatCompletionMessage.Type
 /**
- * @since 1.0.0
+ * Decoded choice object returned by chat completion responses and chunks.
+ *
+ * @category response
+ * @since 4.0.0
  */
 export type ChatCompletionChoice = typeof ChatCompletionChoice.Type
 /**
- * @since 1.0.0
+ * Decoded token usage summary returned by chat completions.
+ *
+ * @category response
+ * @since 4.0.0
  */
 export type ChatCompletionUsage = typeof ChatCompletionUsage.Type
 /**
- * @since 1.0.0
+ * Decoded successful response from the chat completions endpoint.
+ *
+ * @category response
+ * @since 4.0.0
  */
 export type ChatCompletionResponse = typeof ChatCompletionResponse.Type
 /**
- * @since 1.0.0
+ * Decoded streaming chunk emitted by the chat completions endpoint.
+ *
+ * @category streaming
+ * @since 4.0.0
  */
 export type ChatCompletionChunk = typeof ChatCompletionChunk.Type
 /**
- * @since 1.0.0
+ * 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

@@ -1,5 +1,25 @@
 /**
- * @since 1.0.0
+ * 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
  */
 import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
@@ -7,15 +27,20 @@ import { dual } from "effect/Function"
 import type { HttpClient } from "effect/unstable/http/HttpClient"
 
 /**
- * @since 1.0.0
+ * Context service used to carry OpenAI-compatible client configuration for the
+ * current Effect scope.
+ *
  * @category services
+ * @since 4.0.0
  */
 export class OpenAiConfig extends Context.Service<
   OpenAiConfig,
   OpenAiConfig.Service
 >()("@effect/ai-openai-compat/OpenAiConfig") {
   /**
-   * @since 1.0.0
+   * Gets the configured OpenAI-compatible service from the current context when present.
+   *
+   * @since 4.0.0
    */
   static readonly getOrUndefined: Effect.Effect<typeof OpenAiConfig.Service | undefined> = Effect.map(
     Effect.context<never>(),
@@ -24,12 +49,17 @@ export class OpenAiConfig extends Context.Service<
 }
 
 /**
- * @since 1.0.0
+ * Types associated with the `OpenAiConfig` context service.
+ *
+ * @since 4.0.0
  */
 export declare namespace OpenAiConfig {
   /**
-   * @since 1.0.
+   * Configuration consumed by OpenAI-compatible clients when they build or
+   * resolve the underlying HTTP client.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface Service {
     readonly transformClient?: ((client: HttpClient) => HttpClient) | undefined
@@ -37,18 +67,36 @@ export declare namespace OpenAiConfig {
 }
 
 /**
- * @since 1.0.0
+ * Provides an HTTP client transform for the supplied effect.
+ *
+ * The transform is read by OpenAI-compatible provider services from the
+ * `OpenAiConfig` context and can be used to add provider-specific behavior such
+ * as headers, retries, instrumentation, or proxy routing.
+ *
  * @category configuration
+ * @since 4.0.0
  */
 export const withClientTransform: {
   /**
-   * @since 1.0.0
+   * Provides an HTTP client transform for the supplied effect.
+   *
+   * The transform is read by OpenAI-compatible provider services from the
+   * `OpenAiConfig` context and can be used to add provider-specific behavior such
+   * as headers, retries, instrumentation, or proxy routing.
+   *
    * @category configuration
+   * @since 4.0.0
    */
   (transform: (client: HttpClient) => HttpClient): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
   /**
-   * @since 1.0.0
+   * Provides an HTTP client transform for the supplied effect.
+   *
+   * The transform is read by OpenAI-compatible provider services from the
+   * `OpenAiConfig` context and can be used to add provider-specific behavior such
+   * as headers, retries, instrumentation, or proxy routing.
+   *
    * @category configuration
+   * @since 4.0.0
    */
   <A, E, R>(
     self: Effect.Effect<A, E, R>,

package/src/OpenAiEmbeddingModel.ts

@@ -3,7 +3,7 @@
  *
  * Provides an EmbeddingModel implementation for OpenAI-compatible embeddings APIs.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
@@ -17,16 +17,18 @@ import type { CreateEmbedding200, CreateEmbeddingRequestJson } from "./OpenAiCli
 import { OpenAiClient } from "./OpenAiClient.ts"
 
 /**
- * @since 1.0.0
+ * A model identifier accepted by an OpenAI-compatible embeddings endpoint.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Model = string
 
 /**
  * Service definition for OpenAI embedding model configuration.
  *
- * @since 1.0.0
  * @category context
+ * @since 4.0.0
  */
 export class Config extends Context.Service<
   Config,
@@ -44,8 +46,11 @@ export class Config extends Context.Service<
 >()("@effect/ai-openai-compat/OpenAiEmbeddingModel/Config") {}
 
 /**
- * @since 1.0.0
+ * Creates an OpenAI-compatible embedding model that can be used with
+ * `AiModel.provide`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const model = (
   model: string,
@@ -72,8 +77,8 @@ export const model = (
 /**
  * Creates an OpenAI embedding model service.
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.fnUntraced(function*({ model, config: providerConfig }: {
   readonly model: string
@@ -98,8 +103,8 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
 /**
  * Creates a layer for the OpenAI embedding model.
  *
- * @since 1.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (options: {
   readonly model: string
@@ -110,37 +115,37 @@ export const layer = (options: {
 /**
  * Provides config overrides for OpenAI embedding model operations.
  *
- * @since 1.0.0
  * @category configuration
+ * @since 4.0.0
  */
 export const withConfigOverride: {
   /**
    * Provides config overrides for OpenAI embedding 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 embedding 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 embedding 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 embedding 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) =>