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

package/src/OpenAiClient.ts

@@ -1,14 +1,37 @@
 /**
- * @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"
+import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
 import { identity, pipe } from "effect/Function"
 import * as Layer from "effect/Layer"
 import * as Redacted from "effect/Redacted"
 import * as Schema from "effect/Schema"
-import * as ServiceMap from "effect/ServiceMap"
 import * as Stream from "effect/Stream"
 import type * as AiError from "effect/unstable/ai/AiError"
 import * as Sse from "effect/unstable/encoding/Sse"
@@ -20,8 +43,16 @@ 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 +77,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 ServiceMap.Service<OpenAiClient, Service>()(
+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 +107,15 @@ const RedactedOpenAiHeaders = {
 }
 
 /**
- * @since 1.0.0
+ * Constructs an OpenAI-compatible client service from explicit options.
+ *
+ * **Details**
+ *
+ * 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,21 +255,26 @@ 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
+  readonly apiKey?: Config.Config<Redacted.Redacted<string> | undefined> | undefined
   readonly apiUrl?: Config.Config<string> | undefined
-  readonly organizationId?: Config.Config<Redacted.Redacted<string>> | undefined
-  readonly projectId?: Config.Config<Redacted.Redacted<string>> | undefined
+  readonly organizationId?: Config.Config<Redacted.Redacted<string> | undefined> | undefined
+  readonly projectId?: Config.Config<Redacted.Redacted<string> | undefined> | undefined
   readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient) | undefined
 }): Layer.Layer<OpenAiClient, Config.ConfigError, HttpClient.HttpClient> =>
   Layer.effect(
@@ -257,7 +305,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 +316,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 +344,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 +414,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 +452,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 +505,15 @@ type ItemReference = {
 }
 
 /**
- * @since 1.0.0
+ * Item shapes accepted by a Responses-style `input` field.
+ *
+ * **Details**
+ *
+ * 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 +551,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 +579,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 +601,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 +642,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 +662,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 +792,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 +814,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 +832,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 +846,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 +862,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 +894,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 +908,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 +925,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 +940,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 +956,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 +975,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
@@ -855,21 +993,32 @@ export type ChatCompletionRequest = {
   readonly tools?: ReadonlyArray<ChatCompletionTool> | undefined
   readonly tool_choice?: ChatCompletionToolChoice | undefined
   readonly service_tier?: string | undefined
+  readonly reasoning?: unknown
   readonly stream?: boolean | undefined
   readonly stream_options?: {
     readonly include_usage?: boolean | undefined
   } | undefined
+  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
 
@@ -894,6 +1043,11 @@ const ChatCompletionToolFunction = Schema.Struct({
   arguments: Schema.optionalKey(Schema.String)
 })
 
+const ChatCompletionToolFunctionDelta = Schema.Struct({
+  name: Schema.optionalKey(Schema.String),
+  arguments: Schema.optionalKey(Schema.String)
+})
+
 const ChatCompletionToolCall = Schema.Struct({
   id: Schema.optionalKey(Schema.String),
   index: Schema.optionalKey(Schema.Number),
@@ -901,6 +1055,13 @@ const ChatCompletionToolCall = Schema.Struct({
   function: Schema.optionalKey(ChatCompletionToolFunction)
 })
 
+const ChatCompletionToolCallDelta = Schema.Struct({
+  id: Schema.optionalKey(Schema.String),
+  index: Schema.optionalKey(Schema.Number),
+  type: Schema.optionalKey(Schema.String),
+  function: Schema.optionalKey(ChatCompletionToolFunctionDelta)
+})
+
 const ChatCompletionMessage = Schema.Struct({
   role: Schema.optionalKey(Schema.String),
   content: Schema.optionalKey(Schema.NullOr(Schema.String)),
@@ -910,7 +1071,7 @@ const ChatCompletionMessage = Schema.Struct({
 const ChatCompletionDelta = Schema.Struct({
   role: Schema.optionalKey(Schema.String),
   content: Schema.optionalKey(Schema.NullOr(Schema.String)),
-  tool_calls: Schema.optionalKey(Schema.Array(ChatCompletionToolCall))
+  tool_calls: Schema.optionalKey(Schema.Array(ChatCompletionToolCallDelta))
 })
 
 const ChatCompletionChoice = Schema.Struct({
@@ -947,31 +1108,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,35 +1,65 @@
 /**
- * @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"
 import { dual } from "effect/Function"
-import * as ServiceMap from "effect/ServiceMap"
 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 ServiceMap.Service<
+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.services<never>(),
+    Effect.context<never>(),
     (context) => context.mapUnsafe.get(OpenAiConfig.key)
   )
 }
 
 /**
- * @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,54 @@ export declare namespace OpenAiConfig {
 }
 
 /**
- * @since 1.0.0
+ * Provides an HTTP client transform for the supplied effect.
+ *
+ * **When to use**
+ *
+ * Use this to add provider-specific OpenAI-compatible HTTP behavior, such as
+ * headers, retries, instrumentation, or proxy routing.
+ *
+ * **Details**
+ *
+ * OpenAI-compatible provider services read the transform from the
+ * `OpenAiConfig` context.
+ *
  * @category configuration
+ * @since 4.0.0
  */
 export const withClientTransform: {
   /**
-   * @since 1.0.0
+   * Provides an HTTP client transform for the supplied effect.
+   *
+   * **When to use**
+   *
+   * Use this to add provider-specific OpenAI-compatible HTTP behavior, such as
+   * headers, retries, instrumentation, or proxy routing.
+   *
+   * **Details**
+   *
+   * OpenAI-compatible provider services read the transform from the
+   * `OpenAiConfig` context.
+   *
    * @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.
+   *
+   * **When to use**
+   *
+   * Use this to add provider-specific OpenAI-compatible HTTP behavior, such as
+   * headers, retries, instrumentation, or proxy routing.
+   *
+   * **Details**
+   *
+   * OpenAI-compatible provider services read the transform from the
+   * `OpenAiConfig` context.
+   *
    * @category configuration
+   * @since 4.0.0
    */
   <A, E, R>(
     self: Effect.Effect<A, E, R>,