@effect/ai-openai-compat 4.0.0-beta.8 → 4.0.0-beta.81

package/dist/OpenAiClient.d.ts

@@ -1,16 +1,24 @@
 import type * as Config from "effect/Config";
+import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 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 HttpClient from "effect/unstable/http/HttpClient";
 import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
 /**
- * @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;
@@ -24,16 +32,35 @@ export interface Service {
     ], AiError.AiError>;
     readonly createEmbedding: (options: CreateEmbeddingRequestJson) => Effect.Effect<CreateEmbedding200, AiError.AiError>;
 }
-declare const OpenAiClient_base: ServiceMap.ServiceClass<OpenAiClient, "@effect/ai-openai-compat/OpenAiClient", Service>;
-/**
- * @since 1.0.0
- * @category service
+declare const OpenAiClient_base: Context.ServiceClass<OpenAiClient, "@effect/ai-openai-compat/OpenAiClient", Service>;
+/**
+ * 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
  */
 export declare class OpenAiClient extends OpenAiClient_base {
 }
 /**
- * @since 1.0.0
- * @category models
+ * Configuration options used to construct an OpenAI-compatible client.
+ *
+ * @category options
+ * @since 4.0.0
  */
 export type Options = {
     readonly apiKey?: Redacted.Redacted<string> | undefined;
@@ -43,35 +70,89 @@ export type Options = {
     readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient) | undefined;
 };
 /**
- * @since 1.0.0
+ * Constructs an OpenAI-compatible client service from explicit options.
+ *
+ * **When to use**
+ *
+ * Use when you need the OpenAI-compatible client service value inside an effect.
+ *
+ * **Details**
+ *
+ * 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
  */
 export declare const make: (options: Options) => Effect.Effect<Service, never, HttpClient.HttpClient>;
 /**
- * @since 1.0.0
+ * 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
  */
 export declare const layer: (options: Options) => Layer.Layer<OpenAiClient, never, HttpClient.HttpClient>;
 /**
- * @since 1.0.0
+ * Creates a layer that loads OpenAI-compatible client settings from `Config`
+ * values before constructing the service.
+ *
+ * **When to use**
+ *
+ * Use when you need client settings for OpenAI-compatible APIs to 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
  */
 export declare 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>;
 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" | "reasoning.encrypted_content" | "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";
 type InputTextContent = {
@@ -92,11 +173,17 @@ type InputFileContent = {
     readonly file_data?: string | undefined;
 };
 /**
- * @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";
@@ -146,7 +233,10 @@ type FilePathAnnotation = {
     readonly index: number;
 };
 /**
- * @since 1.0.0
+ * Citation and file-path annotations attached to output text content.
+ *
+ * @category response
+ * @since 4.0.0
  */
 export type Annotation = FileCitationAnnotation | UrlCitationAnnotation | ContainerFileCitationAnnotation | FilePathAnnotation;
 type OutputTextContent = {
@@ -164,7 +254,11 @@ type OutputMessage = {
     readonly status: MessageStatus;
 };
 /**
- * @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";
@@ -207,7 +301,15 @@ type ItemReference = {
     readonly id: string;
 };
 /**
- * @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 = {
     readonly role: "user" | "assistant" | "system" | "developer";
@@ -233,7 +335,10 @@ type CustomToolParam = {
     readonly format?: unknown;
 };
 /**
- * @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 | CustomToolParam;
 type ToolChoice = "none" | "auto" | "required" | {
@@ -248,7 +353,11 @@ type ToolChoice = "none" | "auto" | "required" | {
     readonly name: string;
 };
 /**
- * @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 = {
     readonly type: "text";
@@ -262,7 +371,11 @@ export type TextResponseFormatConfiguration = {
     readonly type: "json_object";
 };
 /**
- * @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;
@@ -298,7 +411,10 @@ export type CreateResponse = {
     readonly seed?: number | undefined;
 };
 /**
- * @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;
@@ -309,7 +425,11 @@ export type ResponseUsage = {
 };
 type OutputItem = OutputMessage | FunctionCall | ReasoningItem | 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;
@@ -417,11 +537,23 @@ type UnknownResponseStreamEvent = {
     readonly [key: string]: unknown;
 };
 /**
- * @since 1.0.0
+ * Server-sent event shapes emitted by Responses-style response streams.
+ *
+ * @category streaming
+ * @since 4.0.0
  */
 export type ResponseStreamEvent = ResponseCreatedEvent | ResponseCompletedEvent | ResponseIncompleteEvent | ResponseFailedEvent | ResponseOutputItemAddedEvent | ResponseOutputItemDoneEvent | ResponseTextDeltaEvent | ResponseOutputTextAnnotationAddedEvent | ResponseFunctionCallArgumentsDeltaEvent | ResponseReasoningSummaryPartAddedEvent | ResponseReasoningSummaryPartDoneEvent | ResponseReasoningSummaryTextDeltaEvent | ResponseErrorEvent | 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;
@@ -429,7 +561,10 @@ export type Embedding = {
     readonly object?: string | undefined;
 };
 /**
- * @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>>;
@@ -439,7 +574,10 @@ export type CreateEmbeddingRequest = {
     readonly user?: string | undefined;
 };
 /**
- * @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>;
@@ -451,15 +589,24 @@ export type CreateEmbeddingResponse = {
     } | undefined;
 };
 /**
- * @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 = {
     readonly type: "text";
@@ -472,7 +619,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;
@@ -483,7 +633,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 = {
     readonly role: "system" | "developer" | "user" | "assistant";
@@ -495,7 +648,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";
@@ -507,7 +663,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" | "auto" | "required" | {
     readonly type: "function";
@@ -516,7 +675,10 @@ export type ChatCompletionToolChoice = "none" | "auto" | "required" | {
     };
 };
 /**
- * @since 1.0.0
+ * JSON response format configuration for chat completion requests.
+ *
+ * @category configuration
+ * @since 4.0.0
  */
 export type ChatCompletionResponseFormat = {
     readonly type: "json_object";
@@ -530,7 +692,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;
@@ -545,21 +710,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;
 declare const ChatCompletionToolCall: Schema.Struct<{
@@ -574,6 +750,8 @@ declare const ChatCompletionToolCall: Schema.Struct<{
 declare const ChatCompletionMessage: Schema.Struct<{
     readonly role: Schema.optionalKey<Schema.String>;
     readonly content: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly reasoning: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly reasoning_content: Schema.optionalKey<Schema.NullOr<Schema.String>>;
     readonly tool_calls: Schema.optionalKey<Schema.$Array<Schema.Struct<{
         readonly id: Schema.optionalKey<Schema.String>;
         readonly index: Schema.optionalKey<Schema.Number>;
@@ -590,6 +768,8 @@ declare const ChatCompletionChoice: Schema.Struct<{
     readonly message: Schema.optionalKey<Schema.Struct<{
         readonly role: Schema.optionalKey<Schema.String>;
         readonly content: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+        readonly reasoning: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+        readonly reasoning_content: Schema.optionalKey<Schema.NullOr<Schema.String>>;
         readonly tool_calls: Schema.optionalKey<Schema.$Array<Schema.Struct<{
             readonly id: Schema.optionalKey<Schema.String>;
             readonly index: Schema.optionalKey<Schema.Number>;
@@ -603,12 +783,14 @@ declare const ChatCompletionChoice: Schema.Struct<{
     readonly delta: Schema.optionalKey<Schema.Struct<{
         readonly role: Schema.optionalKey<Schema.String>;
         readonly content: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+        readonly reasoning: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+        readonly reasoning_content: Schema.optionalKey<Schema.NullOr<Schema.String>>;
         readonly tool_calls: Schema.optionalKey<Schema.$Array<Schema.Struct<{
             readonly id: Schema.optionalKey<Schema.String>;
             readonly index: Schema.optionalKey<Schema.Number>;
             readonly type: Schema.optionalKey<Schema.String>;
             readonly function: Schema.optionalKey<Schema.Struct<{
-                readonly name: Schema.String;
+                readonly name: Schema.optionalKey<Schema.NullOr<Schema.String>>;
                 readonly arguments: Schema.optionalKey<Schema.String>;
             }>>;
         }>>>;
@@ -631,6 +813,8 @@ declare const ChatCompletionResponse: Schema.Struct<{
         readonly message: Schema.optionalKey<Schema.Struct<{
             readonly role: Schema.optionalKey<Schema.String>;
             readonly content: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly reasoning: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly reasoning_content: Schema.optionalKey<Schema.NullOr<Schema.String>>;
             readonly tool_calls: Schema.optionalKey<Schema.$Array<Schema.Struct<{
                 readonly id: Schema.optionalKey<Schema.String>;
                 readonly index: Schema.optionalKey<Schema.Number>;
@@ -644,12 +828,14 @@ declare const ChatCompletionResponse: Schema.Struct<{
         readonly delta: Schema.optionalKey<Schema.Struct<{
             readonly role: Schema.optionalKey<Schema.String>;
             readonly content: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly reasoning: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly reasoning_content: Schema.optionalKey<Schema.NullOr<Schema.String>>;
             readonly tool_calls: Schema.optionalKey<Schema.$Array<Schema.Struct<{
                 readonly id: Schema.optionalKey<Schema.String>;
                 readonly index: Schema.optionalKey<Schema.Number>;
                 readonly type: Schema.optionalKey<Schema.String>;
                 readonly function: Schema.optionalKey<Schema.Struct<{
-                    readonly name: Schema.String;
+                    readonly name: Schema.optionalKey<Schema.NullOr<Schema.String>>;
                     readonly arguments: Schema.optionalKey<Schema.String>;
                 }>>;
             }>>>;
@@ -674,6 +860,8 @@ declare const ChatCompletionChunk: Schema.Struct<{
         readonly message: Schema.optionalKey<Schema.Struct<{
             readonly role: Schema.optionalKey<Schema.String>;
             readonly content: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly reasoning: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly reasoning_content: Schema.optionalKey<Schema.NullOr<Schema.String>>;
             readonly tool_calls: Schema.optionalKey<Schema.$Array<Schema.Struct<{
                 readonly id: Schema.optionalKey<Schema.String>;
                 readonly index: Schema.optionalKey<Schema.Number>;
@@ -687,12 +875,14 @@ declare const ChatCompletionChunk: Schema.Struct<{
         readonly delta: Schema.optionalKey<Schema.Struct<{
             readonly role: Schema.optionalKey<Schema.String>;
             readonly content: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly reasoning: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly reasoning_content: Schema.optionalKey<Schema.NullOr<Schema.String>>;
             readonly tool_calls: Schema.optionalKey<Schema.$Array<Schema.Struct<{
                 readonly id: Schema.optionalKey<Schema.String>;
                 readonly index: Schema.optionalKey<Schema.Number>;
                 readonly type: Schema.optionalKey<Schema.String>;
                 readonly function: Schema.optionalKey<Schema.Struct<{
-                    readonly name: Schema.String;
+                    readonly name: Schema.optionalKey<Schema.NullOr<Schema.String>>;
                     readonly arguments: Schema.optionalKey<Schema.String>;
                 }>>;
             }>>>;
@@ -708,31 +898,53 @@ declare const ChatCompletionChunk: Schema.Struct<{
     readonly service_tier: Schema.optionalKey<Schema.String>;
 }>;
 /**
- * @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]";
 export {};