1# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
  2
  3from __future__ import annotations
  4
  5from typing import Dict, Union, Optional
  6from typing_extensions import Literal, Required, TypeAlias, TypedDict
  7
  8from . import web_search_tool_param
  9from ..chat import ChatCompletionFunctionToolParam
 10from ..._types import SequenceNotStr
 11from .custom_tool_param import CustomToolParam
 12from .computer_tool_param import ComputerToolParam
 13from .function_tool_param import FunctionToolParam
 14from .web_search_tool_param import WebSearchToolParam
 15from .apply_patch_tool_param import ApplyPatchToolParam
 16from .file_search_tool_param import FileSearchToolParam
 17from .function_shell_tool_param import FunctionShellToolParam
 18from .web_search_preview_tool_param import WebSearchPreviewToolParam
 19
 20__all__ = [
 21    "ToolParam",
 22    "Mcp",
 23    "McpAllowedTools",
 24    "McpAllowedToolsMcpToolFilter",
 25    "McpRequireApproval",
 26    "McpRequireApprovalMcpToolApprovalFilter",
 27    "McpRequireApprovalMcpToolApprovalFilterAlways",
 28    "McpRequireApprovalMcpToolApprovalFilterNever",
 29    "CodeInterpreter",
 30    "CodeInterpreterContainer",
 31    "CodeInterpreterContainerCodeInterpreterToolAuto",
 32    "ImageGeneration",
 33    "ImageGenerationInputImageMask",
 34    "LocalShell",
 35]
 36
 37WebSearchTool = web_search_tool_param.WebSearchToolParam
 38WebSearchToolFilters = web_search_tool_param.Filters
 39WebSearchToolUserLocation = web_search_tool_param.UserLocation
 40
 41
 42class McpAllowedToolsMcpToolFilter(TypedDict, total=False):
 43    read_only: bool
 44    """Indicates whether or not a tool modifies data or is read-only.
 45
 46    If an MCP server is
 47    [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
 48    it will match this filter.
 49    """
 50
 51    tool_names: SequenceNotStr[str]
 52    """List of allowed tool names."""
 53
 54
 55McpAllowedTools: TypeAlias = Union[SequenceNotStr[str], McpAllowedToolsMcpToolFilter]
 56
 57
 58class McpRequireApprovalMcpToolApprovalFilterAlways(TypedDict, total=False):
 59    read_only: bool
 60    """Indicates whether or not a tool modifies data or is read-only.
 61
 62    If an MCP server is
 63    [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
 64    it will match this filter.
 65    """
 66
 67    tool_names: SequenceNotStr[str]
 68    """List of allowed tool names."""
 69
 70
 71class McpRequireApprovalMcpToolApprovalFilterNever(TypedDict, total=False):
 72    read_only: bool
 73    """Indicates whether or not a tool modifies data or is read-only.
 74
 75    If an MCP server is
 76    [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
 77    it will match this filter.
 78    """
 79
 80    tool_names: SequenceNotStr[str]
 81    """List of allowed tool names."""
 82
 83
 84class McpRequireApprovalMcpToolApprovalFilter(TypedDict, total=False):
 85    always: McpRequireApprovalMcpToolApprovalFilterAlways
 86    """A filter object to specify which tools are allowed."""
 87
 88    never: McpRequireApprovalMcpToolApprovalFilterNever
 89    """A filter object to specify which tools are allowed."""
 90
 91
 92McpRequireApproval: TypeAlias = Union[McpRequireApprovalMcpToolApprovalFilter, Literal["always", "never"]]
 93
 94
 95class Mcp(TypedDict, total=False):
 96    server_label: Required[str]
 97    """A label for this MCP server, used to identify it in tool calls."""
 98
 99    type: Required[Literal["mcp"]]
100    """The type of the MCP tool. Always `mcp`."""
101
102    allowed_tools: Optional[McpAllowedTools]
103    """List of allowed tool names or a filter object."""
104
105    authorization: str
106    """
107    An OAuth access token that can be used with a remote MCP server, either with a
108    custom MCP server URL or a service connector. Your application must handle the
109    OAuth authorization flow and provide the token here.
110    """
111
112    connector_id: Literal[
113        "connector_dropbox",
114        "connector_gmail",
115        "connector_googlecalendar",
116        "connector_googledrive",
117        "connector_microsoftteams",
118        "connector_outlookcalendar",
119        "connector_outlookemail",
120        "connector_sharepoint",
121    ]
122    """Identifier for service connectors, like those available in ChatGPT.
123
124    One of `server_url` or `connector_id` must be provided. Learn more about service
125    connectors
126    [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors).
127
128    Currently supported `connector_id` values are:
129
130    - Dropbox: `connector_dropbox`
131    - Gmail: `connector_gmail`
132    - Google Calendar: `connector_googlecalendar`
133    - Google Drive: `connector_googledrive`
134    - Microsoft Teams: `connector_microsoftteams`
135    - Outlook Calendar: `connector_outlookcalendar`
136    - Outlook Email: `connector_outlookemail`
137    - SharePoint: `connector_sharepoint`
138    """
139
140    headers: Optional[Dict[str, str]]
141    """Optional HTTP headers to send to the MCP server.
142
143    Use for authentication or other purposes.
144    """
145
146    require_approval: Optional[McpRequireApproval]
147    """Specify which of the MCP server's tools require approval."""
148
149    server_description: str
150    """Optional description of the MCP server, used to provide more context."""
151
152    server_url: str
153    """The URL for the MCP server.
154
155    One of `server_url` or `connector_id` must be provided.
156    """
157
158
159class CodeInterpreterContainerCodeInterpreterToolAuto(TypedDict, total=False):
160    type: Required[Literal["auto"]]
161    """Always `auto`."""
162
163    file_ids: SequenceNotStr[str]
164    """An optional list of uploaded files to make available to your code."""
165
166    memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]
167
168
169CodeInterpreterContainer: TypeAlias = Union[str, CodeInterpreterContainerCodeInterpreterToolAuto]
170
171
172class CodeInterpreter(TypedDict, total=False):
173    container: Required[CodeInterpreterContainer]
174    """The code interpreter container.
175
176    Can be a container ID or an object that specifies uploaded file IDs to make
177    available to your code, along with an optional `memory_limit` setting.
178    """
179
180    type: Required[Literal["code_interpreter"]]
181    """The type of the code interpreter tool. Always `code_interpreter`."""
182
183
184class ImageGenerationInputImageMask(TypedDict, total=False):
185    file_id: str
186    """File ID for the mask image."""
187
188    image_url: str
189    """Base64-encoded mask image."""
190
191
192class ImageGeneration(TypedDict, total=False):
193    type: Required[Literal["image_generation"]]
194    """The type of the image generation tool. Always `image_generation`."""
195
196    background: Literal["transparent", "opaque", "auto"]
197    """Background type for the generated image.
198
199    One of `transparent`, `opaque`, or `auto`. Default: `auto`.
200    """
201
202    input_fidelity: Optional[Literal["high", "low"]]
203    """
204    Control how much effort the model will exert to match the style and features,
205    especially facial features, of input images. This parameter is only supported
206    for `gpt-image-1`. Unsupported for `gpt-image-1-mini`. Supports `high` and
207    `low`. Defaults to `low`.
208    """
209
210    input_image_mask: ImageGenerationInputImageMask
211    """Optional mask for inpainting.
212
213    Contains `image_url` (string, optional) and `file_id` (string, optional).
214    """
215
216    model: Literal["gpt-image-1", "gpt-image-1-mini"]
217    """The image generation model to use. Default: `gpt-image-1`."""
218
219    moderation: Literal["auto", "low"]
220    """Moderation level for the generated image. Default: `auto`."""
221
222    output_compression: int
223    """Compression level for the output image. Default: 100."""
224
225    output_format: Literal["png", "webp", "jpeg"]
226    """The output format of the generated image.
227
228    One of `png`, `webp`, or `jpeg`. Default: `png`.
229    """
230
231    partial_images: int
232    """
233    Number of partial images to generate in streaming mode, from 0 (default value)
234    to 3.
235    """
236
237    quality: Literal["low", "medium", "high", "auto"]
238    """The quality of the generated image.
239
240    One of `low`, `medium`, `high`, or `auto`. Default: `auto`.
241    """
242
243    size: Literal["1024x1024", "1024x1536", "1536x1024", "auto"]
244    """The size of the generated image.
245
246    One of `1024x1024`, `1024x1536`, `1536x1024`, or `auto`. Default: `auto`.
247    """
248
249
250class LocalShell(TypedDict, total=False):
251    type: Required[Literal["local_shell"]]
252    """The type of the local shell tool. Always `local_shell`."""
253
254
255ToolParam: TypeAlias = Union[
256    FunctionToolParam,
257    FileSearchToolParam,
258    ComputerToolParam,
259    WebSearchToolParam,
260    Mcp,
261    CodeInterpreter,
262    ImageGeneration,
263    LocalShell,
264    FunctionShellToolParam,
265    CustomToolParam,
266    WebSearchPreviewToolParam,
267    ApplyPatchToolParam,
268]
269
270
271ParseableToolParam: TypeAlias = Union[ToolParam, ChatCompletionFunctionToolParam]