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

package/src/OpenAiSchema.ts

@@ -1,7 +1,7 @@
 /**
  * Minimal local OpenAI schemas used by the handwritten Responses client path.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 import * as Predicate from "effect/Predicate"
 import * as Schema from "effect/Schema"
@@ -15,7 +15,13 @@ const MessageRole = Schema.Literals(["system", "developer", "user", "assistant"]
 const ImageDetail = Schema.Literals(["low", "high", "auto"])
 
 /**
- * @since 1.0.0
+ * Schema for optional `include` values on OpenAI Responses requests.
+ *
+ * **Details**
+ * These values request additional response fields such as image URLs, encrypted reasoning content, output logprobs, code interpreter outputs, or web search sources.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const IncludeEnum = Schema.Literals([
   "message.input_image.image_url",
@@ -26,17 +32,26 @@ export const IncludeEnum = Schema.Literals([
 ])
 
 /**
- * @since 1.0.0
+ * Type of optional `include` values accepted by OpenAI Responses requests.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type IncludeEnum = typeof IncludeEnum.Type
 
 /**
- * @since 1.0.0
+ * Schema for lifecycle statuses shared by messages, reasoning items, and tool calls.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const MessageStatus = Schema.Literals(["in_progress", "completed", "incomplete"])
 
 /**
- * @since 1.0.0
+ * Lifecycle status shared by messages, reasoning items, and tool calls.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type MessageStatus = typeof MessageStatus.Type
 
@@ -61,7 +76,10 @@ const InputFileContent = Schema.Struct({
 })
 
 /**
- * @since 1.0.0
+ * Schema for content blocks accepted in OpenAI Responses input messages.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const InputContent = Schema.Union([
   InputTextContent,
@@ -70,12 +88,18 @@ export const InputContent = Schema.Union([
 ])
 
 /**
- * @since 1.0.0
+ * Content block accepted in OpenAI Responses input messages.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type InputContent = typeof InputContent.Type
 
 /**
- * @since 1.0.0
+ * Schema for a text block containing a model-provided reasoning summary.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const SummaryTextContent = Schema.Struct({
   type: Schema.Literal("summary_text"),
@@ -83,7 +107,10 @@ export const SummaryTextContent = Schema.Struct({
 })
 
 /**
- * @since 1.0.0
+ * Text content block used for model-provided reasoning summaries.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type SummaryTextContent = typeof SummaryTextContent.Type
 
@@ -139,7 +166,10 @@ const FilePathAnnotation = Schema.Struct({
 })
 
 /**
- * @since 1.0.0
+ * Schema for citation and file-path annotations attached to output text content.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const Annotation = Schema.Union([
   FileCitationAnnotation,
@@ -149,7 +179,10 @@ export const Annotation = Schema.Union([
 ])
 
 /**
- * @since 1.0.0
+ * Citation or file-path annotation attached to output text content.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type Annotation = typeof Annotation.Type
 
@@ -181,7 +214,10 @@ const OutputMessage = Schema.Struct({
 })
 
 /**
- * @since 1.0.0
+ * Schema for a reasoning output item containing encrypted content, summaries, and optional reasoning text.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const ReasoningItem = Schema.Struct({
   type: Schema.Literal("reasoning"),
@@ -193,7 +229,10 @@ export const ReasoningItem = Schema.Struct({
 })
 
 /**
- * @since 1.0.0
+ * Reasoning output item containing encrypted content, summaries, and optional reasoning text.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type ReasoningItem = typeof ReasoningItem.Type
 
@@ -279,7 +318,10 @@ const RequestMessageItem = Schema.Struct({
 })
 
 /**
- * @since 1.0.0
+ * Schema for item shapes accepted by an OpenAI Responses request `input` field.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const InputItem = Schema.Union([
   RequestMessageItem,
@@ -297,7 +339,10 @@ export const InputItem = Schema.Union([
 ])
 
 /**
- * @since 1.0.0
+ * Item shape accepted by an OpenAI Responses request `input` field.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type InputItem = typeof InputItem.Type
 
@@ -334,7 +379,10 @@ const ProviderDefinedTool = Schema.StructWithRest(
 )
 
 /**
- * @since 1.0.0
+ * Schema for tool definitions that can be supplied to an OpenAI Responses request.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const Tool = Schema.Union([
   FunctionTool,
@@ -343,12 +391,18 @@ export const Tool = Schema.Union([
 ])
 
 /**
- * @since 1.0.0
+ * Tool definition that can be supplied to an OpenAI Responses request.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type Tool = typeof Tool.Type
 
 /**
- * @since 1.0.0
+ * Schema for selecting whether and which tools the model may call in a Responses request.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const ToolChoice = Schema.Union([
   Schema.Literals(["none", "auto", "required"]),
@@ -384,12 +438,18 @@ export const ToolChoice = Schema.Union([
 ])
 
 /**
- * @since 1.0.0
+ * Tool selection mode or named tool choice for a Responses request.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type ToolChoice = typeof ToolChoice.Type
 
 /**
- * @since 1.0.0
+ * Schema for text output format configuration, including plain text, JSON object, and JSON Schema responses.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const TextResponseFormatConfiguration = Schema.Union([
   Schema.Struct({ type: Schema.Literal("text") }),
@@ -404,12 +464,18 @@ export const TextResponseFormatConfiguration = Schema.Union([
 ])
 
 /**
- * @since 1.0.0
+ * Text output format configuration for plain text, JSON object, or JSON Schema responses.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type TextResponseFormatConfiguration = typeof TextResponseFormatConfiguration.Type
 
 /**
- * @since 1.0.0
+ * Schema for request options used to create an OpenAI Responses API response.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const CreateResponse = Schema.Struct({
   metadata: Schema.optional(Schema.Record(Schema.String, Schema.String)),
@@ -454,12 +520,18 @@ export const CreateResponse = Schema.Struct({
 })
 
 /**
- * @since 1.0.0
+ * Request options used to create an OpenAI Responses API response.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type CreateResponse = typeof CreateResponse.Type
 
 /**
- * @since 1.0.0
+ * Schema for token accounting reported on OpenAI Responses API response objects.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const ResponseUsage = Schema.StructWithRest(
   Schema.Struct({
@@ -473,7 +545,10 @@ export const ResponseUsage = Schema.StructWithRest(
 )
 
 /**
- * @since 1.0.0
+ * Token accounting reported on OpenAI Responses API response objects.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type ResponseUsage = typeof ResponseUsage.Type
 
@@ -570,7 +645,10 @@ const OutputItem = Schema.Union([
 ])
 
 /**
- * @since 1.0.0
+ * Schema for an OpenAI Responses API response object.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const Response = Schema.Struct({
   id: Schema.String,
@@ -590,7 +668,10 @@ export const Response = Schema.Struct({
 })
 
 /**
- * @since 1.0.0
+ * OpenAI Responses API response object.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type Response = typeof Response.Type
 
@@ -767,7 +848,10 @@ const knownResponseStreamEventTypes = new Set([
 ])
 
 /**
- * @since 1.0.0
+ * Fallback event shape for future or provider-specific response stream events.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type UnknownResponseStreamEvent = {
   readonly type: string
@@ -786,7 +870,10 @@ const UnknownResponseStreamEvent = Schema.declare<UnknownResponseStreamEvent>(
 )
 
 /**
- * @since 1.0.0
+ * Schema for server-sent event shapes emitted by OpenAI Responses API streams.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const ResponseStreamEvent = Schema.Union([
   ResponseCreatedEvent,
@@ -812,12 +899,18 @@ export const ResponseStreamEvent = Schema.Union([
 ])
 
 /**
- * @since 1.0.0
+ * Server-sent event shape emitted by OpenAI Responses API streams.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type ResponseStreamEvent = typeof ResponseStreamEvent.Type
 
 /**
- * @since 1.0.0
+ * Schema for one embedding item returned by the OpenAI embeddings API.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const Embedding = Schema.Struct({
   embedding: Schema.Union([
@@ -829,12 +922,18 @@ export const Embedding = Schema.Struct({
 })
 
 /**
- * @since 1.0.0
+ * One embedding item returned by the OpenAI embeddings API.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type Embedding = typeof Embedding.Type
 
 /**
- * @since 1.0.0
+ * Schema for the request payload sent to the OpenAI embeddings endpoint.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const CreateEmbeddingRequest = Schema.Struct({
   input: Schema.Union([
@@ -850,12 +949,18 @@ export const CreateEmbeddingRequest = Schema.Struct({
 })
 
 /**
- * @since 1.0.0
+ * Request payload sent to the OpenAI embeddings endpoint.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type CreateEmbeddingRequest = typeof CreateEmbeddingRequest.Type
 
 /**
- * @since 1.0.0
+ * Schema for a successful response payload returned by the OpenAI embeddings endpoint.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const CreateEmbeddingResponse = Schema.Struct({
   data: Schema.Array(Embedding),
@@ -870,6 +975,9 @@ export const CreateEmbeddingResponse = Schema.Struct({
 })
 
 /**
- * @since 1.0.0
+ * Successful response payload returned by the OpenAI embeddings endpoint.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type CreateEmbeddingResponse = typeof CreateEmbeddingResponse.Type

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 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) => {

package/src/OpenAiTool.ts

@@ -4,7 +4,7 @@
  * Provides tools that are natively supported by OpenAI's API, including
  * code interpreter, file search, and web search functionality.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 import * as Schema from "effect/Schema"
 import * as Tool from "effect/unstable/ai/Tool"
@@ -13,8 +13,8 @@ import * as Generated from "./Generated.ts"
 /**
  * Union of all OpenAI provider-defined tools.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type OpenAiTool =
   | ReturnType<typeof ApplyPatch>
@@ -34,8 +34,8 @@ export type OpenAiTool =
  * This is a local tool that runs in your environment and requires a handler
  * to execute file operations.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const ApplyPatch = Tool.providerDefined({
   id: "openai.apply_patch",
@@ -57,8 +57,8 @@ export const ApplyPatch = Tool.providerDefined({
  *
  * Allows the model to execute Python code in a sandboxed environment.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const CodeInterpreter = Tool.providerDefined({
   id: "openai.code_interpreter",
@@ -81,8 +81,8 @@ export const CodeInterpreter = Tool.providerDefined({
  *
  * Enables the model to search through uploaded files and vector stores.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const FileSearch = Tool.providerDefined({
   id: "openai.file_search",
@@ -106,8 +106,8 @@ export const FileSearch = Tool.providerDefined({
  *
  * Enables the model to generate images using the GPT image models.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const ImageGeneration = Tool.providerDefined({
   id: "openai.image_generation",
@@ -136,8 +136,8 @@ export const ImageGeneration = Tool.providerDefined({
  * Enables the model to run a command with a local shell. This is a local tool
  * that runs in your environment and requires a handler to execute commands.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const LocalShell = Tool.providerDefined({
   id: "openai.local_shell",
@@ -158,8 +158,8 @@ export const LocalShell = Tool.providerDefined({
  * Gives the model access to additional tools via remote Model Context Protocol
  * (MCP) servers
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const Mcp = Tool.providerDefined({
   id: "openai.mcp",
@@ -192,8 +192,8 @@ export const Mcp = Tool.providerDefined({
  * environment. This is a local tool that runs in your environment and requires
  * a handler to execute commands.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const Shell = Tool.providerDefined({
   id: "openai.shell",
@@ -213,8 +213,8 @@ export const Shell = Tool.providerDefined({
  *
  * Enables the model to search the web for information.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const WebSearch = Tool.providerDefined({
   id: "openai.web_search",
@@ -239,8 +239,8 @@ export const WebSearch = Tool.providerDefined({
  *
  * Preview version of the web search tool with additional features.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const WebSearchPreview = Tool.providerDefined({
   id: "openai.web_search_preview",

package/src/index.ts

@@ -1,11 +1,11 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as Generated from "./Generated.ts"
 
@@ -15,17 +15,33 @@ export * as Generated from "./Generated.ts"
  * Provides a type-safe, Effect-based client for OpenAI operations including
  * completions, embeddings, and streaming responses.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenAiClient from "./OpenAiClient.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenAiClientGenerated from "./OpenAiClientGenerated.ts"
 
 /**
- * @since 1.0.0
+ * The `OpenAiConfig` module provides contextual configuration for the
+ * `@effect/ai-openai` integration. It is used to customize how OpenAI clients
+ * are built and interpreted without threading configuration through every API
+ * call manually.
+ *
+ * The primary use case is installing an HTTP client transform with
+ * {@link withClientTransform}. This lets applications adapt the underlying
+ * OpenAI HTTP client for cross-cutting concerns such as custom middleware,
+ * instrumentation, proxying, or request policy changes while keeping the
+ * OpenAI service APIs unchanged.
+ *
+ * Configuration is scoped through Effect's context, so transforms only apply to
+ * the effect they are provided to and anything evaluated inside that scope.
+ * When multiple transforms are needed, compose them into a single
+ * `HttpClient => HttpClient` function before providing the configuration.
+ *
+ * @since 4.0.0
  */
 export * as OpenAiConfig from "./OpenAiConfig.ts"
 
@@ -34,7 +50,7 @@ export * as OpenAiConfig from "./OpenAiConfig.ts"
  *
  * Provides an EmbeddingModel implementation for OpenAI's embeddings API.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenAiEmbeddingModel from "./OpenAiEmbeddingModel.ts"
 
@@ -44,7 +60,7 @@ export * as OpenAiEmbeddingModel from "./OpenAiEmbeddingModel.ts"
  * Provides OpenAI-specific metadata fields for AI error types through module
  * augmentation, enabling typed access to OpenAI error details.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenAiError from "./OpenAiError.ts"
 
@@ -54,14 +70,14 @@ export * as OpenAiError from "./OpenAiError.ts"
  * Provides a LanguageModel implementation for OpenAI's responses API,
  * supporting text generation, structured output, tool calling, and streaming.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenAiLanguageModel from "./OpenAiLanguageModel.ts"
 
 /**
  * Minimal local OpenAI schemas used by the handwritten Responses client path.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenAiSchema from "./OpenAiSchema.ts"
 
@@ -72,7 +88,7 @@ export * as OpenAiSchema from "./OpenAiSchema.ts"
  * semantic conventions, extending the base GenAI attributes with OpenAI-specific
  * request and response metadata.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenAiTelemetry from "./OpenAiTelemetry.ts"
 
@@ -82,6 +98,6 @@ export * as OpenAiTelemetry from "./OpenAiTelemetry.ts"
  * Provides tools that are natively supported by OpenAI's API, including
  * code interpreter, file search, and web search functionality.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenAiTool from "./OpenAiTool.ts"