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

package/src/OpenAiTool.ts

@@ -1,8 +1,27 @@
 /**
- * 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.
+ *
+ * **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
  */
@@ -28,10 +47,16 @@ export type OpenAiTool =
   | ReturnType<typeof WebSearchPreview>
 
 /**
- * OpenAI Apply Patch tool that allows the model to apply diffs by creating,
+ * Defines the 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.
  *
+ * **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.
+ *
  * @category tools
  * @since 4.0.0
  */
@@ -51,9 +76,19 @@ export const ApplyPatch = Tool.providerDefined({
 })
 
 /**
- * OpenAI Code Interpreter tool that allows the model to execute Python code in
+ * Defines the 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**
+ *
+ * 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.
+ *
  * @category tools
  * @since 4.0.0
  */
@@ -74,9 +109,20 @@ export const CodeInterpreter = Tool.providerDefined({
 })
 
 /**
- * OpenAI File Search tool that enables the model to search through uploaded
+ * Defines the OpenAI File Search tool that 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`.
+ *
  * @category tools
  * @since 4.0.0
  */
@@ -98,9 +144,21 @@ export const FileSearch = Tool.providerDefined({
 })
 
 /**
- * OpenAI Image Generation tool that enables the model to generate images using
+ * Defines the OpenAI Image Generation tool that enables the model to generate images using
  * the GPT image models.
  *
+ * **When to use**
+ *
+ * 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`.
+ *
  * @category tools
  * @since 4.0.0
  */
@@ -126,10 +184,21 @@ export const ImageGeneration = Tool.providerDefined({
 })
 
 /**
- * OpenAI Local Shell tool that enables the model to run a command with a local
+ * Defines the 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.
+ *
+ * **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.
+ *
  * @category tools
  * @since 4.0.0
  */
@@ -147,9 +216,25 @@ export const LocalShell = Tool.providerDefined({
 })
 
 /**
- * OpenAI MCP tool that gives the model access to additional tools via remote
+ * Defines the 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**
+ *
+ * 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.
+ *
  * @category tools
  * @since 4.0.0
  */
@@ -178,9 +263,18 @@ export const Mcp = Tool.providerDefined({
 })
 
 /**
- * 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.
+ * Defines the OpenAI shell tool for model-requested command execution.
+ *
+ * **When to use**
+ *
+ * Use to let an OpenAI model request shell commands that your application
+ * executes through a handler.
+ *
+ * **Details**
+ *
+ * The tool exposes a provider-defined `shell` call. It is marked as
+ * handler-required, so applications must provide the command execution policy
+ * and implementation.
  *
  * @category tools
  * @since 4.0.0
@@ -199,9 +293,20 @@ export const Shell = Tool.providerDefined({
 })
 
 /**
- * OpenAI Web Search tool that enables the model to search the web for
+ * Defines the OpenAI Web Search tool that enables the model to search the web for
  * information.
  *
+ * **When to use**
+ *
+ * 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
+ *
  * @category tools
  * @since 4.0.0
  */
@@ -224,8 +329,18 @@ export const WebSearch = Tool.providerDefined({
 })
 
 /**
- * OpenAI Web Search Preview tool, a preview version of the web search tool with
- * additional features.
+ * Defines the 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.
+ *
+ * @see {@link WebSearch} for the stable web search provider tool
  *
  * @category tools
  * @since 4.0.0

package/src/index.ts

@@ -5,16 +5,11 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * @since 4.0.0
+ * @since 1.0.0
  */
 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 4.0.0
  */
 export * as OpenAiClient from "./OpenAiClient.ts"
@@ -25,79 +20,36 @@ export * as OpenAiClient from "./OpenAiClient.ts"
 export * as OpenAiClientGenerated from "./OpenAiClientGenerated.ts"
 
 /**
- * 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"
 
 /**
- * OpenAI Embedding Model implementation.
- *
- * Provides an EmbeddingModel implementation for OpenAI's embeddings API.
- *
  * @since 4.0.0
  */
 export * as OpenAiEmbeddingModel from "./OpenAiEmbeddingModel.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 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 4.0.0
  */
 export * as OpenAiLanguageModel from "./OpenAiLanguageModel.ts"
 
 /**
- * Minimal local OpenAI schemas used by the handwritten Responses client path.
- *
  * @since 4.0.0
  */
 export * as OpenAiSchema from "./OpenAiSchema.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 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 4.0.0
  */
 export * as OpenAiTool from "./OpenAiTool.ts"