@effect/ai-openai 4.0.0-beta.69 → 4.0.0-beta.70

package/src/OpenAiClient.ts

@@ -42,6 +42,7 @@ import * as OpenAiSchema from "./OpenAiSchema.ts"
  * Effect service interface for the handwritten OpenAI client.
  *
  * **Details**
+ *
  * Provides the configured HTTP client plus helpers for Responses API calls, streaming Responses events, and embeddings. Transport and schema decoding failures are mapped to `AiError`.
  *
  * @category models
@@ -586,13 +587,14 @@ const decodeEvent = Schema.decodeUnknownSync(Schema.fromJsonString(AllEvents))
 /**
  * Uses OpenAI's websocket mode for all responses within the provided effect.
  *
- * Note: This only works with the following WebSocket constructor layers:
+ * **Gotchas**
+ *
+ * This only works with the following WebSocket constructor layers:
  *
  * - `NodeSocket.layerWebSocketConstructorWS`
  * - `BunSocket.layerWebSocketConstructor`
  *
- * This is because it needs to use non-standard options for setting the
- * Authorization header.
+ * This is because it needs to use non-standard options for setting the Authorization header.
  *
  * @category Websocket mode
  * @since 4.0.0
@@ -614,13 +616,14 @@ export const withWebSocketMode = <A, E, R>(
 /**
  * Uses OpenAI's websocket mode for all responses that use the Layer.
  *
- * Note: This only works with the following WebSocket constructor layers:
+ * **Gotchas**
+ *
+ * This only works with the following WebSocket constructor layers:
  *
  * - `NodeSocket.layerWebSocketConstructorWS`
  * - `BunSocket.layerWebSocketConstructor`
  *
- * This is because it needs to use non-standard options for setting the
- * Authorization header.
+ * This is because it needs to use non-standard options for setting the Authorization header.
  *
  * @category Websocket mode
  * @since 4.0.0

package/src/OpenAiError.ts

@@ -31,6 +31,8 @@ export type OpenAiErrorMetadata = {
 /**
  * OpenAI-specific rate limit metadata fields.
  *
+ * **Details**
+ *
  * Extends base error metadata with rate limit specific information from
  * OpenAI's rate limit headers.
  *
@@ -60,6 +62,8 @@ declare module "effect/unstable/ai/AiError" {
   /**
    * OpenAI metadata attached to `RateLimitError` values.
    *
+   * **Details**
+   *
    * Captures OpenAI error details together with rate limit header information
    * from responses where the provider rejected the request because a limit was
    * reached.
@@ -77,6 +81,8 @@ declare module "effect/unstable/ai/AiError" {
   /**
    * OpenAI metadata attached to `QuotaExhaustedError` values.
    *
+   * **Details**
+   *
    * Preserves provider error details for failures caused by exhausted account,
    * billing, or usage quota.
    *
@@ -93,6 +99,8 @@ declare module "effect/unstable/ai/AiError" {
   /**
    * OpenAI metadata attached to `AuthenticationError` values.
    *
+   * **Details**
+   *
    * Preserves provider error details for failed API key, authorization, or
    * permission checks.
    *
@@ -109,6 +117,8 @@ declare module "effect/unstable/ai/AiError" {
   /**
    * OpenAI metadata attached to `ContentPolicyError` values.
    *
+   * **Details**
+   *
    * Preserves provider error details when OpenAI rejects input or output because
    * it violates a content policy.
    *
@@ -125,6 +135,8 @@ declare module "effect/unstable/ai/AiError" {
   /**
    * OpenAI metadata attached to `InvalidRequestError` values.
    *
+   * **Details**
+   *
    * Preserves provider error details for malformed requests, unsupported
    * parameters, or other request validation failures reported by OpenAI.
    *
@@ -141,6 +153,8 @@ declare module "effect/unstable/ai/AiError" {
   /**
    * OpenAI metadata attached to `InternalProviderError` values.
    *
+   * **Details**
+   *
    * Preserves provider error details for OpenAI-side failures such as transient
    * server errors.
    *
@@ -157,6 +171,8 @@ declare module "effect/unstable/ai/AiError" {
   /**
    * OpenAI metadata attached to `InvalidOutputError` values.
    *
+   * **Details**
+   *
    * Preserves provider error details when an OpenAI response cannot be parsed or
    * validated as the expected output.
    *
@@ -173,6 +189,8 @@ declare module "effect/unstable/ai/AiError" {
   /**
    * OpenAI metadata attached to `StructuredOutputError` values.
    *
+   * **Details**
+   *
    * Preserves provider error details when OpenAI returns content that does not
    * satisfy the requested structured output schema.
    *
@@ -189,6 +207,8 @@ declare module "effect/unstable/ai/AiError" {
   /**
    * OpenAI metadata attached to `UnsupportedSchemaError` values.
    *
+   * **Details**
+   *
    * Preserves provider error details when an unsupported schema failure is
    * associated with an OpenAI response.
    *
@@ -205,6 +225,8 @@ declare module "effect/unstable/ai/AiError" {
   /**
    * OpenAI metadata attached to `UnknownError` values.
    *
+   * **Details**
+   *
    * Preserves provider error details for OpenAI failures that do not map cleanly
    * to a more specific AI error category.
    *

package/src/OpenAiSchema.ts

@@ -18,6 +18,7 @@ const ImageDetail = Schema.Literals(["low", "high", "auto"])
  * 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

package/src/OpenAiTelemetry.ts

@@ -17,7 +17,7 @@ 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/}
+ * @see https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/
  *
  * @category models
  * @since 4.0.0
@@ -78,6 +78,8 @@ 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.
  *
@@ -90,6 +92,8 @@ 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.
  *
@@ -123,7 +127,9 @@ 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**.
+ * **Gotchas**
+ *
+ * This method will mutate the `Span` **in-place**.
  *
  * @category tracing
  * @since 4.0.0
@@ -133,7 +139,9 @@ export const addGenAIAnnotations: {
    * Applies the specified OpenAi GenAI telemetry attributes to the provided
    * `Span`.
    *
-   * **NOTE**: This method will mutate the `Span` **in-place**.
+   * **Gotchas**
+   *
+   * This method will mutate the `Span` **in-place**.
    *
    * @category tracing
    * @since 4.0.0
@@ -143,7 +151,9 @@ export const addGenAIAnnotations: {
    * Applies the specified OpenAi GenAI telemetry attributes to the provided
    * `Span`.
    *
-   * **NOTE**: This method will mutate the `Span` **in-place**.
+   * **Gotchas**
+   *
+   * This method will mutate the `Span` **in-place**.
    *
    * @category tracing
    * @since 4.0.0

package/src/OpenAiTool.ts

@@ -28,11 +28,9 @@ export type OpenAiTool =
   | ReturnType<typeof WebSearchPreview>
 
 /**
- * OpenAI Apply Patch tool.
- *
- * 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.
+ * 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.
  *
  * @category tools
  * @since 4.0.0
@@ -53,9 +51,8 @@ export const ApplyPatch = Tool.providerDefined({
 })
 
 /**
- * OpenAI Code Interpreter tool.
- *
- * Allows the model to execute Python code in a sandboxed environment.
+ * OpenAI Code Interpreter tool that allows the model to execute Python code in
+ * a sandboxed environment.
  *
  * @category tools
  * @since 4.0.0
@@ -77,9 +74,8 @@ export const CodeInterpreter = Tool.providerDefined({
 })
 
 /**
- * OpenAI File Search tool.
- *
- * Enables the model to search through uploaded files and vector stores.
+ * OpenAI File Search tool that enables the model to search through uploaded
+ * files and vector stores.
  *
  * @category tools
  * @since 4.0.0
@@ -102,9 +98,8 @@ export const FileSearch = Tool.providerDefined({
 })
 
 /**
- * OpenAI Image Generation tool.
- *
- * Enables the model to generate images using the GPT image models.
+ * OpenAI Image Generation tool that enables the model to generate images using
+ * the GPT image models.
  *
  * @category tools
  * @since 4.0.0
@@ -131,10 +126,9 @@ export const ImageGeneration = Tool.providerDefined({
 })
 
 /**
- * OpenAI Local Shell tool.
- *
- * 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.
+ * 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.
  *
  * @category tools
  * @since 4.0.0
@@ -153,10 +147,8 @@ export const LocalShell = Tool.providerDefined({
 })
 
 /**
- * OpenAI MCP tool.
- *
- * Gives the model access to additional tools via remote Model Context Protocol
- * (MCP) servers
+ * OpenAI MCP tool that gives the model access to additional tools via remote
+ * Model Context Protocol (MCP) servers.
  *
  * @category tools
  * @since 4.0.0
@@ -186,11 +178,9 @@ export const Mcp = Tool.providerDefined({
 })
 
 /**
- * OpenAI Function Shell tool.
- *
- * 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.
+ * 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.
  *
  * @category tools
  * @since 4.0.0
@@ -209,9 +199,8 @@ export const Shell = Tool.providerDefined({
 })
 
 /**
- * OpenAI Web Search tool.
- *
- * Enables the model to search the web for information.
+ * OpenAI Web Search tool that enables the model to search the web for
+ * information.
  *
  * @category tools
  * @since 4.0.0
@@ -235,9 +224,8 @@ export const WebSearch = Tool.providerDefined({
 })
 
 /**
- * OpenAI Web Search Preview tool.
- *
- * Preview version of the web search tool with additional features.
+ * OpenAI Web Search Preview tool, a preview version of the web search tool with
+ * additional features.
  *
  * @category tools
  * @since 4.0.0