1/**
2 * The `OpenAiTool` module defines OpenAI provider tools for Effect AI language
3 * model requests. It exposes typed descriptors for tools such as Apply Patch,
4 * Code Interpreter, File Search, Image Generation, MCP, Web Search, and
5 * shell-like local tools, including their provider names, configuration
6 * arguments, call parameters, success schemas, and handler requirements.
7 *
8 * @stability unstable
9 * @since 4.0.0
10 */
11import * as Tool from "effect/ai/Tool"
12import * as Schema from "effect/Schema"
13import * as Generated from "./Generated.ts"
14
15/**
16 * Union of all OpenAI provider-defined tools.
17 *
18 * @stability unstable
19 * @category models
20 * @since 4.0.0
21 */
22export type OpenAiTool =
23 | ReturnType<typeof ApplyPatch>
24 | ReturnType<typeof CodeInterpreter>
25 | ReturnType<typeof FileSearch>
26 | ReturnType<typeof Shell>
27 | ReturnType<typeof ImageGeneration>
28 | ReturnType<typeof LocalShell>
29 | ReturnType<typeof Mcp>
30 | ReturnType<typeof WebSearch>
31 | ReturnType<typeof WebSearchPreview>
32
33/**
34 * Defines the OpenAI Apply Patch tool that allows the model to apply diffs by creating,
35 * deleting, or updating files. This local tool runs in your environment and
36 * requires a handler to execute file operations.
37 *
38 * **When to use**
39 *
40 * Use when you want an OpenAI model to request structured file edits as create,
41 * delete, or update operations that your application executes through a local
42 * handler.
43 *
44 * @stability unstable
45 * @category tools
46 * @since 4.0.0
47 */
48export const ApplyPatch = Tool.providerDefined({
49 id: "openai.apply_patch",
50 customName: "OpenAiApplyPatch",
51 providerName: "apply_patch",
52 requiresHandler: true,
53 parameters: Schema.Struct({
54 call_id: Generated.ApplyPatchToolCall.fields.call_id,
55 operation: Generated.ApplyPatchToolCall.fields.operation
56 }),
57 success: Schema.Struct({
58 status: Generated.ApplyPatchToolCallOutput.fields.status,
59 output: Generated.ApplyPatchToolCallOutput.fields.output
60 })
61})
62
63/**
64 * Defines the OpenAI Code Interpreter tool that allows the model to execute Python code in
65 * a sandboxed environment.
66 *
67 * **When to use**
68 *
69 * Use to enable OpenAI-hosted Python execution for a model response.
70 *
71 * **Details**
72 *
73 * The tool is configured with a `container` argument. Results include `status`
74 * and `outputs`: logs, generated images, or `null` when unavailable. A `completed`
75 * status indicates success; omitted statuses default to it. Other statuses
76 * produce failure results that preserve any outputs.
77 *
78 * @stability unstable
79 * @category tools
80 * @since 4.0.0
81 */
82export const CodeInterpreter = Tool.providerDefined({
83 id: "openai.code_interpreter",
84 customName: "OpenAiCodeInterpreter",
85 providerName: "code_interpreter",
86 args: Schema.Struct({
87 container: Generated.CodeInterpreterTool.fields.container
88 }),
89 parameters: Schema.Struct({
90 code: Generated.CodeInterpreterToolCall.fields.code,
91 container_id: Generated.CodeInterpreterToolCall.fields.container_id
92 }),
93 success: Schema.Struct({
94 status: Schema.Literal("completed"),
95 outputs: Generated.CodeInterpreterToolCall.fields.outputs
96 }),
97 failure: Schema.Struct({
98 status: Schema.Literals(
99 Generated.CodeInterpreterToolCall.fields.status.literals.filter((status) => status !== "completed")
100 ),
101 outputs: Generated.CodeInterpreterToolCall.fields.outputs
102 })
103})
104
105/**
106 * Defines the OpenAI File Search tool that enables the model to search through uploaded
107 * files and vector stores.
108 *
109 * **When to use**
110 *
111 * Use to let an OpenAI model search uploaded files through one or more vector
112 * stores.
113 *
114 * **Details**
115 *
116 * The tool requires `vector_store_ids` and accepts optional `filters`,
117 * `max_num_results`, and `ranking_options`. Results include `queries` and a
118 * required `results` field containing matches or `null`. Only `completed` is
119 * successful; all other statuses produce failure results, preserving partial
120 * matches.
121 *
122 * @stability unstable
123 * @category tools
124 * @since 4.0.0
125 */
126export const FileSearch = Tool.providerDefined({
127 id: "openai.file_search",
128 customName: "OpenAiFileSearch",
129 providerName: "file_search",
130 args: Schema.Struct({
131 filters: Generated.FileSearchTool.fields.filters,
132 max_num_results: Generated.FileSearchTool.fields.max_num_results,
133 ranking_options: Generated.FileSearchTool.fields.ranking_options,
134 vector_store_ids: Generated.FileSearchTool.fields.vector_store_ids
135 }),
136 success: Schema.Struct({
137 status: Schema.Literal("completed"),
138 queries: Generated.FileSearchToolCall.fields.queries,
139 results: Generated.FileSearchToolCall.fields.results.schema
140 }),
141 failure: Schema.Struct({
142 status: Schema.Literals(
143 Generated.FileSearchToolCall.fields.status.literals.filter((status) => status !== "completed")
144 ),
145 queries: Generated.FileSearchToolCall.fields.queries,
146 results: Generated.FileSearchToolCall.fields.results.schema
147 })
148})
149
150/**
151 * Defines the OpenAI Image Generation tool that enables the model to generate images using
152 * the GPT image models.
153 *
154 * **When to use**
155 *
156 * Use to enable OpenAI provider-defined image generation through a language
157 * model response.
158 *
159 * **Details**
160 *
161 * The tool configures the `image_generation` provider tool, including model,
162 * size, quality, output format, moderation, background, input-image options,
163 * and partial image settings. Successful calls expose `result` as base64 image
164 * data or `null`. Partial images are preliminary success results. Final results
165 * with a status other than `completed` are failures that include `status`.
166 * Omitted statuses default to `completed`.
167 *
168 * @stability unstable
169 * @category tools
170 * @since 4.0.0
171 */
172export const ImageGeneration = Tool.providerDefined({
173 id: "openai.image_generation",
174 customName: "OpenAiImageGeneration",
175 providerName: "image_generation",
176 args: Schema.Struct({
177 background: Generated.ImageGenTool.fields.background,
178 input_fidelity: Generated.ImageGenTool.fields.input_fidelity,
179 input_image_mask: Generated.ImageGenTool.fields.input_image_mask,
180 model: Generated.ImageGenTool.fields.model,
181 moderation: Generated.ImageGenTool.fields.moderation,
182 output_compression: Generated.ImageGenTool.fields.output_compression,
183 output_format: Generated.ImageGenTool.fields.output_format,
184 partial_images: Generated.ImageGenTool.fields.partial_images,
185 quality: Generated.ImageGenTool.fields.quality,
186 size: Generated.ImageGenTool.fields.size
187 }),
188 success: Schema.Struct({
189 result: Generated.ImageGenToolCall.fields.result
190 }),
191 failure: Schema.Struct({
192 status: Schema.Literals(
193 Generated.ImageGenToolCall.fields.status.literals.filter((status) => status !== "completed")
194 ),
195 result: Generated.ImageGenToolCall.fields.result
196 })
197})
198
199/**
200 * Defines the OpenAI Local Shell tool that enables the model to run a command with a local
201 * shell. This local tool runs in your environment and requires a handler to
202 * execute commands.
203 *
204 * **When to use**
205 *
206 * Use to let an OpenAI model request local shell commands that your application
207 * executes through a handler.
208 *
209 * **Details**
210 *
211 * The tool exposes a provider-defined `local_shell` call. It is marked as
212 * handler-required, so applications must provide the command execution policy
213 * and implementation.
214 *
215 * @stability unstable
216 * @category tools
217 * @since 4.0.0
218 */
219export const LocalShell = Tool.providerDefined({
220 id: "openai.local_shell",
221 customName: "OpenAiLocalShell",
222 providerName: "local_shell",
223 requiresHandler: true,
224 parameters: Schema.Struct({
225 action: Generated.LocalShellToolCall.fields.action
226 }),
227 success: Schema.Struct({
228 output: Generated.LocalShellToolCallOutput.fields.output
229 })
230})
231
232const McpResultFields = {
233 type: Generated.MCPToolCall.fields.type,
234 name: Generated.MCPToolCall.fields.name,
235 arguments: Generated.MCPToolCall.fields.arguments,
236 output: Generated.MCPToolCall.fields.output,
237 server_label: Generated.MCPToolCall.fields.server_label
238}
239
240/**
241 * Defines the OpenAI MCP tool that gives the model access to additional tools via remote
242 * Model Context Protocol (MCP) servers.
243 *
244 * **When to use**
245 *
246 * Use to let an OpenAI model call tools exposed by a remote MCP server.
247 *
248 * **Details**
249 *
250 * The tool accepts MCP server configuration such as allowed tools,
251 * authorization, connector id, approval requirements, server metadata, and
252 * server URL. Tool call results include the called tool name, arguments, output,
253 * and server label. Calls that report an `error` produce failure results that
254 * include it; successful results omit `error`.
255 *
256 * **Gotchas**
257 *
258 * This schema leaves both `server_url` and `connector_id` optional, but OpenAI
259 * may require a server URL or connector id for a usable MCP tool configuration.
260 *
261 * @stability unstable
262 * @category tools
263 * @since 4.0.0
264 */
265export const Mcp = Tool.providerDefined({
266 id: "openai.mcp",
267 customName: "OpenAiMcp",
268 providerName: "mcp",
269 args: Schema.Struct({
270 allowed_tools: Generated.MCPTool.fields.allowed_tools,
271 authorization: Generated.MCPTool.fields.authorization,
272 connector_id: Generated.MCPTool.fields.connector_id,
273 require_approval: Generated.MCPTool.fields.require_approval,
274 server_description: Generated.MCPTool.fields.server_description,
275 server_label: Generated.MCPTool.fields.server_label,
276 server_url: Generated.MCPTool.fields.server_url
277 }),
278 parameters: Schema.Unknown,
279 success: Schema.Struct(McpResultFields),
280 failure: Schema.Struct({
281 ...McpResultFields,
282 error: Schema.String
283 })
284})
285
286/**
287 * Defines the OpenAI shell tool for model-requested command execution.
288 *
289 * **When to use**
290 *
291 * Use to let an OpenAI model request shell commands that your application
292 * executes through a handler.
293 *
294 * **Details**
295 *
296 * The tool exposes a provider-defined `shell` call. It is marked as
297 * handler-required, so applications must provide the command execution policy
298 * and implementation.
299 *
300 * @stability unstable
301 * @category tools
302 * @since 4.0.0
303 */
304export const Shell = Tool.providerDefined({
305 id: "openai.shell",
306 customName: "OpenAiShell",
307 providerName: "shell",
308 requiresHandler: true,
309 parameters: Schema.Struct({
310 action: Generated.FunctionShellCall.fields.action
311 }),
312 success: Schema.Struct({
313 output: Generated.FunctionShellCallOutput.fields.output
314 })
315})
316
317const WebSearchSuccess = Schema.Struct({
318 action: Generated.WebSearchToolCall.fields.action,
319 status: Schema.Literal("completed")
320})
321
322const WebSearchFailure = Schema.Struct({
323 action: Generated.WebSearchToolCall.fields.action,
324 status: Schema.Literals(Generated.WebSearchToolCall.fields.status.literals.filter((status) => status !== "completed"))
325})
326
327/**
328 * Defines the OpenAI Web Search tool that enables the model to search the web for
329 * information.
330 *
331 * **When to use**
332 *
333 * Use to enable OpenAI provider-defined web search for a model response.
334 *
335 * **Details**
336 *
337 * The tool accepts optional filters, user location, and search context size.
338 * Results include status and, when available, action. Only `completed` succeeds;
339 * other statuses produce failure results.
340 * Narrow search sources by `type` to read `url` for URL sources or `name`
341 * for API sources.
342 *
343 * @see {@link WebSearchPreview} for the preview web search provider tool
344 *
345 * @stability unstable
346 * @category tools
347 * @since 4.0.0
348 */
349export const WebSearch = Tool.providerDefined({
350 id: "openai.web_search",
351 customName: "OpenAiWebSearch",
352 providerName: "web_search",
353 args: Schema.Struct({
354 filters: Generated.WebSearchTool.fields.filters,
355 user_location: Generated.WebSearchTool.fields.user_location,
356 search_context_size: Generated.WebSearchTool.fields.search_context_size
357 }),
358 parameters: Schema.Struct({
359 action: Generated.WebSearchToolCall.fields.action
360 }),
361 success: WebSearchSuccess,
362 failure: WebSearchFailure
363})
364
365/**
366 * Defines the OpenAI preview Web Search tool for model responses.
367 *
368 * **When to use**
369 *
370 * Use to enable the preview OpenAI web search provider tool.
371 *
372 * **Details**
373 *
374 * The preview tool accepts optional user location and search context size.
375 * Results include status and, when available, action. Only `completed` succeeds;
376 * other statuses produce failure results.
377 * Narrow search sources by `type` to read `url` for URL sources or `name`
378 * for API sources.
379 *
380 * @see {@link WebSearch} for the stable web search provider tool
381 *
382 * @stability unstable
383 * @category tools
384 * @since 4.0.0
385 */
386export const WebSearchPreview = Tool.providerDefined({
387 id: "openai.web_search_preview",
388 customName: "OpenAiWebSearchPreview",
389 providerName: "web_search_preview",
390 args: Schema.Struct({
391 user_location: Generated.WebSearchPreviewTool.fields.user_location,
392 search_context_size: Generated.WebSearchPreviewTool.fields.search_context_size
393 }),
394 success: WebSearchSuccess,
395 failure: WebSearchFailure
396})