@effect/ai-openai 4.0.0-beta.7 → 4.0.0-beta.71

package/src/OpenAiTelemetry.ts

@@ -1,11 +1,28 @@
 /**
- * OpenAI telemetry attributes for OpenTelemetry integration.
+ * OpenAI-specific telemetry annotations for GenAI spans.
  *
- * Provides OpenAI-specific GenAI telemetry attributes following OpenTelemetry
- * semantic conventions, extending the base GenAI attributes with OpenAI-specific
- * request and response metadata.
+ * This module extends the provider-neutral GenAI telemetry model with
+ * attributes that only exist on OpenAI requests and responses. Use
+ * {@link addGenAIAnnotations} when an OpenAI operation already has an
+ * OpenTelemetry span and you want to record both standard GenAI metadata and
+ * OpenAI details such as response format, requested service tier, actual
+ * service tier, or system fingerprint.
  *
- * @since 1.0.0
+ * **Mental model**
+ *
+ * The public option shape stays idiomatic TypeScript (`responseFormat`,
+ * `serviceTier`, `systemFingerprint`). When annotations are applied, the
+ * attributes are written to the span under OpenTelemetry semantic-convention
+ * keys such as `gen_ai.openai.request.response_format` and
+ * `gen_ai.openai.response.system_fingerprint`.
+ *
+ * **Gotchas**
+ *
+ * Annotation mutates the provided span in place. It does not create, end, or
+ * export spans, and OpenAI-specific attributes are only added when the
+ * `openai.request` or `openai.response` option objects are present.
+ *
+ * @since 4.0.0
  */
 import { dual } from "effect/Function"
 import * as String from "effect/String"
@@ -17,10 +34,14 @@ import * as Telemetry from "effect/unstable/ai/Telemetry"
  * The attributes used to describe telemetry in the context of Generative
  * Artificial Intelligence (GenAI) Models requests and responses.
  *
- * {@see https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/}
+ * **Details**
+ *
+ * These attributes follow the OpenTelemetry generative AI semantic
+ * conventions:
+ * 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 +53,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 +62,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 +80,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 {
   /**
@@ -78,11 +99,13 @@ export interface ResponseAttributes {
  * The `gen_ai.openai.request.response_format` attribute has the following
  * list of well-known values.
  *
+ * **Details**
+ *
  * 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"
 
@@ -90,17 +113,22 @@ export type WellKnownResponseFormat = "json_object" | "json_schema" | "text"
  * The `gen_ai.openai.request.service_tier` attribute has the following
  * list of well-known values.
  *
+ * **Details**
+ *
  * 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?: {
@@ -120,30 +148,60 @@ const addOpenAiResponseAttributes = Telemetry.addSpanAttributes("gen_ai.openai.r
  * Applies the specified OpenAi GenAI telemetry attributes to the provided
  * `Span`.
  *
- * **NOTE**: This method will mutate the `Span` **in-place**.
+ * **When to use**
+ *
+ * Use to annotate an existing OpenTelemetry span with standard GenAI attributes
+ * plus OpenAI-specific request and response metadata.
+ *
+ * **Gotchas**
  *
- * @since 1.0.0
- * @since utilities
+ * This method will mutate the `Span` **in-place**.
+ *
+ * @see {@link OpenAiTelemetryAttributeOptions} for the accepted telemetry attributes
+ * @see {@link Telemetry.addGenAIAnnotations} for the provider-neutral annotation helper
+ *
+ * @category tracing
+ * @since 4.0.0
  */
 export const addGenAIAnnotations: {
   /**
    * Applies the specified OpenAi GenAI telemetry attributes to the provided
    * `Span`.
    *
-   * **NOTE**: This method will mutate the `Span` **in-place**.
+   * **When to use**
+   *
+   * Use to annotate an existing OpenTelemetry span with standard GenAI attributes
+   * plus OpenAI-specific request and response metadata.
+   *
+   * **Gotchas**
+   *
+   * This method will mutate the `Span` **in-place**.
    *
-   * @since 1.0.0
-   * @since utilities
+   * @see {@link OpenAiTelemetryAttributeOptions} for the accepted telemetry attributes
+   * @see {@link Telemetry.addGenAIAnnotations} for the provider-neutral annotation helper
+   *
+   * @category tracing
+   * @since 4.0.0
    */
   (options: OpenAiTelemetryAttributeOptions): (span: Span) => void
   /**
    * Applies the specified OpenAi GenAI telemetry attributes to the provided
    * `Span`.
    *
-   * **NOTE**: This method will mutate the `Span` **in-place**.
+   * **When to use**
+   *
+   * Use to annotate an existing OpenTelemetry span with standard GenAI attributes
+   * plus OpenAI-specific request and response metadata.
+   *
+   * **Gotchas**
+   *
+   * This method will mutate the `Span` **in-place**.
+   *
+   * @see {@link OpenAiTelemetryAttributeOptions} for the accepted telemetry attributes
+   * @see {@link Telemetry.addGenAIAnnotations} for the provider-neutral annotation helper
    *
-   * @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

@@ -1,10 +1,29 @@
 /**
- * OpenAI provider-defined tools for use with the LanguageModel.
+ * OpenAI provider-defined tools for Effect AI language model requests.
  *
- * Provides tools that are natively supported by OpenAI's API, including
- * code interpreter, file search, and web search functionality.
+ * This module exposes typed descriptors for OpenAI tools such as code
+ * interpreter, file search, image generation, MCP, web search, and shell-like
+ * local tools. Each descriptor captures the OpenAI provider name, user-facing
+ * configuration arguments, provider call parameters, success output schema, and
+ * whether the tool call needs an application-provided handler.
  *
- * @since 1.0.0
+ * **Mental model**
+ *
+ * Provider-defined tools are not implementations of the capability themselves.
+ * They are schemas and metadata that tell the language model provider which
+ * tool to make available and tell Effect AI how to decode any tool calls or
+ * tool results that come back.
+ *
+ * **Common tasks**
+ *
+ * Use hosted or provider-routed tools such as {@link CodeInterpreter},
+ * {@link FileSearch}, {@link ImageGeneration}, {@link Mcp}, {@link WebSearch},
+ * and {@link WebSearchPreview} to opt into OpenAI-managed capabilities. Use
+ * handler-required tools such as {@link ApplyPatch}, {@link Shell}, and
+ * {@link LocalShell} only when your application is prepared to execute the
+ * requested local operation and enforce its own safety policy.
+ *
+ * @since 4.0.0
  */
 import * as Schema from "effect/Schema"
 import * as Tool from "effect/unstable/ai/Tool"
@@ -13,8 +32,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>
@@ -28,14 +47,18 @@ export type OpenAiTool =
   | ReturnType<typeof WebSearchPreview>
 
 /**
- * OpenAI Apply Patch tool.
+ * OpenAI Apply Patch tool that allows the model to apply diffs by creating,
+ * deleting, or updating files. This local tool runs in your environment and
+ * requires a handler to execute file operations.
  *
- * Allows the model to apply diffs by creating, deleting, or updating files.
- * This is a local tool that runs in your environment and requires a handler
- * to execute file operations.
+ * **When to use**
+ *
+ * Use when you want an OpenAI model to request structured file edits as create,
+ * delete, or update operations that your application executes through a local
+ * handler.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const ApplyPatch = Tool.providerDefined({
   id: "openai.apply_patch",
@@ -53,12 +76,21 @@ export const ApplyPatch = Tool.providerDefined({
 })
 
 /**
- * OpenAI Code Interpreter tool.
+ * OpenAI Code Interpreter tool that allows the model to execute Python code in
+ * a sandboxed environment.
+ *
+ * **When to use**
+ *
+ * Use to enable OpenAI-hosted Python execution for a model response.
+ *
+ * **Details**
  *
- * Allows the model to execute Python code in a sandboxed environment.
+ * The tool is configured with a `container` argument. Successful tool calls
+ * expose `outputs`, which may contain logs or generated images, or `null` when
+ * no outputs are available.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const CodeInterpreter = Tool.providerDefined({
   id: "openai.code_interpreter",
@@ -77,12 +109,22 @@ export const CodeInterpreter = Tool.providerDefined({
 })
 
 /**
- * OpenAI File Search tool.
+ * OpenAI File Search tool that enables the model to search through uploaded
+ * files and vector stores.
  *
- * Enables the model to search through uploaded files and vector stores.
+ * **When to use**
+ *
+ * Use to let an OpenAI model search uploaded files through one or more vector
+ * stores.
+ *
+ * **Details**
+ *
+ * The tool requires `vector_store_ids` and accepts optional `filters`,
+ * `max_num_results`, and `ranking_options`. Successful tool calls expose the
+ * search `status`, generated `queries`, and optional `results`.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const FileSearch = Tool.providerDefined({
   id: "openai.file_search",
@@ -102,12 +144,23 @@ export const FileSearch = Tool.providerDefined({
 })
 
 /**
- * OpenAI Image Generation tool.
+ * OpenAI Image Generation tool that enables the model to generate images using
+ * the GPT image models.
+ *
+ * **When to use**
  *
- * Enables the model to generate images using the GPT image models.
+ * Use to enable OpenAI provider-defined image generation through a language
+ * model response.
+ *
+ * **Details**
+ *
+ * The tool configures the `image_generation` provider tool, including model,
+ * size, quality, output format, moderation, background, input-image options,
+ * and partial image settings. Successful tool calls expose `result` as base64
+ * image data or `null`.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const ImageGeneration = Tool.providerDefined({
   id: "openai.image_generation",
@@ -131,13 +184,23 @@ export const ImageGeneration = Tool.providerDefined({
 })
 
 /**
- * OpenAI Local Shell tool.
+ * OpenAI Local Shell tool that enables the model to run a command with a local
+ * shell. This local tool runs in your environment and requires a handler to
+ * execute commands.
+ *
+ * **When to use**
+ *
+ * Use to let an OpenAI model request local shell commands that your application
+ * executes through a handler.
  *
- * 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.
+ * **Details**
+ *
+ * The tool exposes a provider-defined `local_shell` call. It is marked as
+ * handler-required, so applications must provide the command execution policy
+ * and implementation.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const LocalShell = Tool.providerDefined({
   id: "openai.local_shell",
@@ -153,13 +216,27 @@ export const LocalShell = Tool.providerDefined({
 })
 
 /**
- * OpenAI MCP tool.
+ * OpenAI MCP tool that gives the model access to additional tools via remote
+ * Model Context Protocol (MCP) servers.
+ *
+ * **When to use**
+ *
+ * Use to let an OpenAI model call tools exposed by a remote MCP server.
+ *
+ * **Details**
  *
- * Gives the model access to additional tools via remote Model Context Protocol
- * (MCP) servers
+ * The tool accepts MCP server configuration such as allowed tools,
+ * authorization, connector id, approval requirements, server metadata, and
+ * server URL. Tool call results include the called tool name, arguments, output,
+ * error, and server label.
+ *
+ * **Gotchas**
+ *
+ * This schema leaves both `server_url` and `connector_id` optional, but OpenAI
+ * may require a server URL or connector id for a usable MCP tool configuration.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const Mcp = Tool.providerDefined({
   id: "openai.mcp",
@@ -174,6 +251,7 @@ export const Mcp = Tool.providerDefined({
     server_label: Generated.MCPTool.fields.server_label,
     server_url: Generated.MCPTool.fields.server_url
   }),
+  parameters: Schema.Unknown,
   success: Schema.Struct({
     type: Generated.MCPToolCall.fields.type,
     name: Generated.MCPToolCall.fields.name,
@@ -185,14 +263,12 @@ export const Mcp = Tool.providerDefined({
 })
 
 /**
- * OpenAI Function Shell tool.
+ * OpenAI Function Shell tool that enables the model to execute one or more shell
+ * commands in a managed environment. This local tool runs in your environment
+ * and requires a handler to execute commands.
  *
- * Enables the model to execute one or more shell commands in a managed
- * 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",
@@ -203,17 +279,27 @@ export const Shell = Tool.providerDefined({
     action: Generated.FunctionShellCall.fields.action
   }),
   success: Schema.Struct({
-    output: Generated.FunctionShellCallOutputItemParam.fields.output
+    output: Generated.FunctionShellCallOutput.fields.output
   })
 })
 
 /**
- * OpenAI Web Search tool.
+ * OpenAI Web Search tool that enables the model to search the web for
+ * information.
+ *
+ * **When to use**
  *
- * Enables the model to search the web for information.
+ * Use to enable OpenAI provider-defined web search for a model response.
+ *
+ * **Details**
+ *
+ * The tool accepts optional filters, user location, and search context size.
+ * Successful calls expose the performed search action and status.
+ *
+ * @see {@link WebSearchPreview} for the preview web search provider tool
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const WebSearch = Tool.providerDefined({
   id: "openai.web_search",
@@ -234,12 +320,21 @@ export const WebSearch = Tool.providerDefined({
 })
 
 /**
- * OpenAI Web Search Preview tool.
+ * OpenAI preview Web Search tool for model responses.
+ *
+ * **When to use**
+ *
+ * Use to enable the preview OpenAI web search provider tool.
+ *
+ * **Details**
+ *
+ * The preview tool accepts optional user location and search context size, then
+ * exposes the performed search action and status in successful calls.
  *
- * Preview version of the web search tool with additional features.
+ * @see {@link WebSearch} for the stable web search provider tool
  *
- * @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,5 +1,5 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 // @barrel: Auto-generated exports. Do not edit manually.
@@ -10,57 +10,46 @@
 export * as Generated from "./Generated.ts"
 
 /**
- * OpenAI Client module for interacting with OpenAI's API.
- *
- * 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 4.0.0
  */
 export * as OpenAiConfig from "./OpenAiConfig.ts"
 
 /**
- * OpenAI error metadata augmentation.
- *
- * 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 OpenAiEmbeddingModel from "./OpenAiEmbeddingModel.ts"
+
+/**
+ * @since 4.0.0
  */
 export * as OpenAiError from "./OpenAiError.ts"
 
 /**
- * OpenAI Language Model implementation.
- *
- * 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"
 
 /**
- * OpenAI telemetry attributes for OpenTelemetry integration.
- *
- * Provides OpenAI-specific GenAI telemetry attributes following OpenTelemetry
- * semantic conventions, extending the base GenAI attributes with OpenAI-specific
- * request and response metadata.
- *
- * @since 1.0.0
+ * @since 4.0.0
+ */
+export * as OpenAiSchema from "./OpenAiSchema.ts"
+
+/**
+ * @since 4.0.0
  */
 export * as OpenAiTelemetry from "./OpenAiTelemetry.ts"
 
 /**
- * OpenAI provider-defined tools for use with the LanguageModel.
- *
- * 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"

package/src/internal/errors.ts

@@ -161,12 +161,14 @@ export const parseRateLimitHeaders = (headers: Record<string, string>) => {
   let retryAfter: Duration.Duration | undefined
   if (Predicate.isNotUndefined(retryAfterRaw)) {
     const parsed = Number.parse(retryAfterRaw)
-    if (Predicate.isNotUndefined(parsed)) {
-      retryAfter = Duration.seconds(parsed)
+    if (Option.isSome(parsed)) {
+      retryAfter = Duration.seconds(parsed.value)
     }
   }
   const remainingRaw = headers["x-ratelimit-remaining-requests"]
-  const remaining = Predicate.isNotUndefined(remainingRaw) ? Number.parse(remainingRaw) ?? null : null
+  const remaining = Predicate.isNotUndefined(remainingRaw)
+    ? Option.getOrNull(Number.parse(remainingRaw))
+    : null
   return {
     retryAfter,
     limit: headers["x-ratelimit-limit-requests"] ?? null,
@@ -187,7 +189,7 @@ export const buildHttpRequestDetails = (
   method: request.method,
   url: request.url,
   urlParams: Array.from(request.urlParams),
-  hash: request.hash,
+  hash: Option.getOrUndefined(request.hash),
   headers: Redactable.redact(request.headers) as Record<string, string>
 })