@effect/ai-openai 0.37.1 → 4.0.0-beta.0

package/src/OpenAiTelemetry.ts

@@ -1,12 +1,17 @@
 /**
+ * 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
  */
-import * as Telemetry from "@effect/ai/Telemetry"
 import { dual } from "effect/Function"
-import * as Predicate from "effect/Predicate"
 import * as String from "effect/String"
 import type { Span } from "effect/Tracer"
 import type { Simplify } from "effect/Types"
+import * as Telemetry from "effect/unstable/ai/Telemetry"
 
 /**
  * The attributes used to describe telemetry in the context of Generative
@@ -15,7 +20,7 @@ import type { Simplify } from "effect/Types"
  * {@see https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/}
  *
  * @since 1.0.0
- * @category Models
+ * @category models
  */
 export type OpenAiTelemetryAttributes = Simplify<
   & Telemetry.GenAITelemetryAttributes
@@ -28,7 +33,7 @@ export type OpenAiTelemetryAttributes = Simplify<
  * including the OpenAi-specific attributes.
  *
  * @since 1.0.0
- * @category Models
+ * @category models
  */
 export type AllAttributes = Telemetry.AllAttributes & RequestAttributes & ResponseAttributes
 
@@ -37,7 +42,7 @@ export type AllAttributes = Telemetry.AllAttributes & RequestAttributes & Respon
  * namespaced by `gen_ai.openai.request`.
  *
  * @since 1.0.0
- * @category Models
+ * @category models
  */
 export interface RequestAttributes {
   /**
@@ -55,7 +60,7 @@ export interface RequestAttributes {
  * namespaced by `gen_ai.openai.response`.
  *
  * @since 1.0.0
- * @category Models
+ * @category models
  */
 export interface ResponseAttributes {
   /**
@@ -77,7 +82,7 @@ export interface ResponseAttributes {
  * otherwise, a custom value **MAY** be used.
  *
  * @since 1.0.0
- * @category Models
+ * @category models
  */
 export type WellKnownResponseFormat = "json_object" | "json_schema" | "text"
 
@@ -89,13 +94,13 @@ export type WellKnownResponseFormat = "json_object" | "json_schema" | "text"
  * otherwise, a custom value **MAY** be used.
  *
  * @since 1.0.0
- * @category Models
+ * @category models
  */
 export type WellKnownServiceTier = "auto" | "default"
 
 /**
  * @since 1.0.0
- * @since Models
+ * @since models
  */
 export type OpenAiTelemetryAttributeOptions = Telemetry.GenAITelemetryAttributeOptions & {
   openai?: {
@@ -118,9 +123,9 @@ const addOpenAiResponseAttributes = Telemetry.addSpanAttributes("gen_ai.openai.r
  * **NOTE**: This method will mutate the `Span` **in-place**.
  *
  * @since 1.0.0
- * @since Utilities
+ * @since utilities
  */
-export const addGenAIAnnotations = dual<
+export const addGenAIAnnotations: {
   /**
    * Applies the specified OpenAi GenAI telemetry attributes to the provided
    * `Span`.
@@ -128,9 +133,9 @@ export const addGenAIAnnotations = dual<
    * **NOTE**: This method will mutate the `Span` **in-place**.
    *
    * @since 1.0.0
-   * @since Utilities
+   * @since utilities
    */
-  (options: OpenAiTelemetryAttributeOptions) => (span: Span) => void,
+  (options: OpenAiTelemetryAttributeOptions): (span: Span) => void
   /**
    * Applies the specified OpenAi GenAI telemetry attributes to the provided
    * `Span`.
@@ -138,16 +143,16 @@ export const addGenAIAnnotations = dual<
    * **NOTE**: This method will mutate the `Span` **in-place**.
    *
    * @since 1.0.0
-   * @since Utilities
+   * @since utilities
    */
-  (span: Span, options: OpenAiTelemetryAttributeOptions) => void
->(2, (span, options) => {
+  (span: Span, options: OpenAiTelemetryAttributeOptions): void
+} = dual(2, (span: Span, options: OpenAiTelemetryAttributeOptions) => {
   Telemetry.addGenAIAnnotations(span, options)
-  if (Predicate.isNotNullable(options.openai)) {
-    if (Predicate.isNotNullable(options.openai.request)) {
+  if (options.openai != null) {
+    if (options.openai.request != null) {
       addOpenAiRequestAttributes(span, options.openai.request)
     }
-    if (Predicate.isNotNullable(options.openai.response)) {
+    if (options.openai.response != null) {
       addOpenAiResponseAttributes(span, options.openai.response)
     }
   }

package/src/OpenAiTool.ts

@@ -1,110 +1,256 @@
 /**
+ * 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
  */
-import * as Tool from "@effect/ai/Tool"
 import * as Schema from "effect/Schema"
-import * as Struct from "effect/Struct"
-import * as Generated from "./Generated.js"
+import * as Tool from "effect/unstable/ai/Tool"
+import * as Generated from "./Generated.ts"
 
 /**
+ * Union of all OpenAI provider-defined tools.
+ *
  * @since 1.0.0
- * @category Tools
+ * @category models
+ */
+export type OpenAiTool =
+  | ReturnType<typeof ApplyPatch>
+  | ReturnType<typeof CodeInterpreter>
+  | ReturnType<typeof FileSearch>
+  | ReturnType<typeof Shell>
+  | ReturnType<typeof ImageGeneration>
+  | ReturnType<typeof LocalShell>
+  | ReturnType<typeof Mcp>
+  | ReturnType<typeof WebSearch>
+  | 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.
+ *
+ * @since 1.0.0
+ * @category tools
+ */
+export const ApplyPatch = Tool.providerDefined({
+  id: "openai.apply_patch",
+  customName: "OpenAiApplyPatch",
+  providerName: "apply_patch",
+  requiresHandler: true,
+  parameters: Schema.Struct({
+    call_id: Generated.ApplyPatchToolCall.fields.call_id,
+    operation: Generated.ApplyPatchToolCall.fields.operation
+  }),
+  success: Schema.Struct({
+    status: Generated.ApplyPatchToolCallOutput.fields.status,
+    output: Generated.ApplyPatchToolCallOutput.fields.output
+  })
+})
+
+/**
+ * OpenAI Code Interpreter tool.
+ *
+ * Allows the model to execute Python code in a sandboxed environment.
+ *
+ * @since 1.0.0
+ * @category tools
  */
 export const CodeInterpreter = Tool.providerDefined({
   id: "openai.code_interpreter",
-  toolkitName: "OpenAiCodeInterpreter",
+  customName: "OpenAiCodeInterpreter",
   providerName: "code_interpreter",
-  args: {
-    /**
-     * The configuration for the code interpreter container.
-     *
-     * Can be either a string which specifies the ID of a container created via
-     * the `/v1/containers` endpoint, or an object which specifies an optional
-     * list of files to make available to the container.
-     */
-    container: Schema.Union(
-      Schema.String,
-      Schema.Struct({
-        type: Schema.Literal("auto"),
-        /**
-         * An optional list of uploaded files to make available to your code.
-         */
-        file_ids: Schema.optional(Schema.Array(Schema.String))
-      })
-    )
-  },
-  parameters: {
-    code: Schema.NullOr(Schema.String),
-    container_id: Schema.String
-  },
-  success: Schema.NullOr(Schema.Array(Schema.Union(
-    Generated.CodeInterpreterOutputLogs,
-    Generated.CodeInterpreterOutputImage
-  )))
+  args: Schema.Struct({
+    container: Generated.CodeInterpreterTool.fields.container
+  }),
+  parameters: Schema.Struct({
+    code: Generated.CodeInterpreterToolCall.fields.code,
+    container_id: Generated.CodeInterpreterToolCall.fields.container_id
+  }),
+  success: Schema.Struct({
+    outputs: Generated.CodeInterpreterToolCall.fields.outputs
+  })
 })
 
 /**
+ * OpenAI File Search tool.
+ *
+ * Enables the model to search through uploaded files and vector stores.
+ *
  * @since 1.0.0
- * @category Tools
+ * @category tools
  */
 export const FileSearch = Tool.providerDefined({
   id: "openai.file_search",
-  toolkitName: "OpenAiFileSearch",
+  customName: "OpenAiFileSearch",
   providerName: "file_search",
-  args: Struct.omit(Generated.FileSearchTool.fields, "type"),
-  success: Generated.FileSearchToolCall.pipe(Schema.omit("id", "type"))
+  args: Schema.Struct({
+    filters: Generated.FileSearchTool.fields.filters,
+    max_num_results: Generated.FileSearchTool.fields.max_num_results,
+    ranking_options: Generated.FileSearchTool.fields.ranking_options,
+    vector_store_ids: Generated.FileSearchTool.fields.vector_store_ids
+  }),
+  success: Schema.Struct({
+    status: Generated.FileSearchToolCall.fields.status,
+    queries: Generated.FileSearchToolCall.fields.queries,
+    results: Generated.FileSearchToolCall.fields.results
+  })
+})
+
+/**
+ * OpenAI Image Generation tool.
+ *
+ * Enables the model to generate images using the GPT image models.
+ *
+ * @since 1.0.0
+ * @category tools
+ */
+export const ImageGeneration = Tool.providerDefined({
+  id: "openai.image_generation",
+  customName: "OpenAiImageGeneration",
+  providerName: "image_generation",
+  args: Schema.Struct({
+    background: Generated.ImageGenTool.fields.background,
+    input_fidelity: Generated.ImageGenTool.fields.input_fidelity,
+    input_image_mask: Generated.ImageGenTool.fields.input_image_mask,
+    model: Generated.ImageGenTool.fields.model,
+    moderation: Generated.ImageGenTool.fields.moderation,
+    output_compression: Generated.ImageGenTool.fields.output_compression,
+    output_format: Generated.ImageGenTool.fields.output_format,
+    partial_images: Generated.ImageGenTool.fields.partial_images,
+    quality: Generated.ImageGenTool.fields.quality,
+    size: Generated.ImageGenTool.fields.size
+  }),
+  success: Schema.Struct({
+    result: Generated.ImageGenToolCall.fields.result
+  })
+})
+
+/**
+ * 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.
+ *
+ * @since 1.0.0
+ * @category tools
+ */
+export const LocalShell = Tool.providerDefined({
+  id: "openai.local_shell",
+  customName: "OpenAiLocalShell",
+  providerName: "local_shell",
+  requiresHandler: true,
+  parameters: Schema.Struct({
+    action: Generated.LocalShellToolCall.fields.action
+  }),
+  success: Schema.Struct({
+    output: Generated.LocalShellToolCallOutput.fields.output
+  })
 })
 
 /**
+ * OpenAI MCP tool.
+ *
+ * Gives the model access to additional tools via remote Model Context Protocol
+ * (MCP) servers
+ *
  * @since 1.0.0
- * @category Tools
+ * @category tools
+ */
+export const Mcp = Tool.providerDefined({
+  id: "openai.mcp",
+  customName: "OpenAiMcp",
+  providerName: "mcp",
+  args: Schema.Struct({
+    allowed_tools: Generated.MCPTool.fields.allowed_tools,
+    authorization: Generated.MCPTool.fields.authorization,
+    connector_id: Generated.MCPTool.fields.connector_id,
+    require_approval: Generated.MCPTool.fields.require_approval,
+    server_description: Generated.MCPTool.fields.server_description,
+    server_label: Generated.MCPTool.fields.server_label,
+    server_url: Generated.MCPTool.fields.server_url
+  }),
+  success: Schema.Struct({
+    type: Generated.MCPToolCall.fields.type,
+    name: Generated.MCPToolCall.fields.name,
+    arguments: Generated.MCPToolCall.fields.arguments,
+    output: Generated.MCPToolCall.fields.output,
+    error: Generated.MCPToolCall.fields.error,
+    server_label: Generated.MCPToolCall.fields.server_label
+  })
+})
+
+/**
+ * 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.
+ *
+ * @since 1.0.0
+ * @category tools
+ */
+export const Shell = Tool.providerDefined({
+  id: "openai.shell",
+  customName: "OpenAiShell",
+  providerName: "shell",
+  requiresHandler: true,
+  parameters: Schema.Struct({
+    action: Generated.FunctionShellCall.fields.action
+  }),
+  success: Schema.Struct({
+    output: Generated.FunctionShellCallOutputItemParam.fields.output
+  })
+})
+
+/**
+ * OpenAI Web Search tool.
+ *
+ * Enables the model to search the web for information.
+ *
+ * @since 1.0.0
+ * @category tools
  */
 export const WebSearch = Tool.providerDefined({
   id: "openai.web_search",
-  toolkitName: "OpenAiWebSearch",
+  customName: "OpenAiWebSearch",
   providerName: "web_search",
-  args: Struct.omit(Generated.WebSearchTool.fields, "type"),
-  parameters: {
-    action: Schema.Union(
-      Generated.WebSearchActionSearch,
-      Generated.WebSearchActionOpenPage,
-      Generated.WebSearchActionFind
-    )
-  },
+  args: Schema.Struct({
+    filters: Generated.WebSearchTool.fields.filters,
+    user_location: Generated.WebSearchTool.fields.user_location,
+    search_context_size: Generated.WebSearchTool.fields.search_context_size
+  }),
+  parameters: Schema.Struct({
+    action: Generated.WebSearchToolCall.fields.action
+  }),
   success: Schema.Struct({
-    status: Generated.WebSearchToolCallStatus
+    action: Generated.WebSearchToolCall.fields.action,
+    status: Generated.WebSearchToolCall.fields.status
   })
 })
 
 /**
+ * OpenAI Web Search Preview tool.
+ *
+ * Preview version of the web search tool with additional features.
+ *
  * @since 1.0.0
- * @category Tools
+ * @category tools
  */
 export const WebSearchPreview = Tool.providerDefined({
   id: "openai.web_search_preview",
-  toolkitName: "OpenAiWebSearchPreview",
+  customName: "OpenAiWebSearchPreview",
   providerName: "web_search_preview",
-  args: Struct.omit(Generated.WebSearchPreviewTool.fields, "type"),
-  parameters: {
-    action: Schema.Union(
-      Generated.WebSearchActionSearch,
-      Generated.WebSearchActionOpenPage,
-      Generated.WebSearchActionFind
-    )
-  },
+  args: Schema.Struct({
+    user_location: Generated.WebSearchPreviewTool.fields.user_location,
+    search_context_size: Generated.WebSearchPreviewTool.fields.search_context_size
+  }),
   success: Schema.Struct({
-    status: Generated.WebSearchToolCallStatus
+    action: Generated.WebSearchToolCall.fields.action,
+    status: Generated.WebSearchToolCall.fields.status
   })
 })
-
-type ProviderToolNames = "code_interpreter" | "file_search" | "web_search" | "web_search_preview"
-
-const ProviderToolNamesMap: Map<ProviderToolNames | (string & {}), string> = new Map([
-  ["code_interpreter", "OpenAiCodeInterpreter"],
-  ["file_search", "OpenAiFileSearch"],
-  ["web_search", "OpenAiWebSearch"],
-  ["web_search_preview", "OpenAiWebSearchPreview"]
-])
-
-/** @internal */
-export const getProviderDefinedToolName = (name: string): string | undefined => ProviderToolNamesMap.get(name)

package/src/index.ts

@@ -1,39 +1,66 @@
 /**
  * @since 1.0.0
  */
-export * as Generated from "./Generated.js"
+
+// @barrel: Auto-generated exports. Do not edit manually.
 
 /**
  * @since 1.0.0
  */
-export * as OpenAiClient from "./OpenAiClient.js"
+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
  */
-export * as OpenAiConfig from "./OpenAiConfig.js"
+export * as OpenAiClient from "./OpenAiClient.ts"
 
 /**
  * @since 1.0.0
  */
-export * as OpenAiEmbeddingModel from "./OpenAiEmbeddingModel.js"
+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
  */
-export * as OpenAiLanguageModel from "./OpenAiLanguageModel.js"
+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
  */
-export * as OpenAiTelemetry from "./OpenAiTelemetry.js"
+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
  */
-export * as OpenAiTokenizer from "./OpenAiTokenizer.js"
+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
  */
-export * as OpenAiTool from "./OpenAiTool.js"
+export * as OpenAiTool from "./OpenAiTool.ts"