1# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
  2
  3from typing import Dict, List, Union, Optional
  4from typing_extensions import Literal, Annotated, TypeAlias
  5
  6from . import web_search_tool
  7from ..._utils import PropertyInfo
  8from ..._models import BaseModel
  9from .custom_tool import CustomTool
 10from .computer_tool import ComputerTool
 11from .function_tool import FunctionTool
 12from .web_search_tool import WebSearchTool
 13from .apply_patch_tool import ApplyPatchTool
 14from .file_search_tool import FileSearchTool
 15from .function_shell_tool import FunctionShellTool
 16from .web_search_preview_tool import WebSearchPreviewTool
 17
 18__all__ = [
 19    "Tool",
 20    "WebSearchTool",
 21    "Mcp",
 22    "McpAllowedTools",
 23    "McpAllowedToolsMcpToolFilter",
 24    "McpRequireApproval",
 25    "McpRequireApprovalMcpToolApprovalFilter",
 26    "McpRequireApprovalMcpToolApprovalFilterAlways",
 27    "McpRequireApprovalMcpToolApprovalFilterNever",
 28    "CodeInterpreter",
 29    "CodeInterpreterContainer",
 30    "CodeInterpreterContainerCodeInterpreterToolAuto",
 31    "ImageGeneration",
 32    "ImageGenerationInputImageMask",
 33    "LocalShell",
 34]
 35
 36WebSearchToolFilters = web_search_tool.Filters
 37WebSearchToolUserLocation = web_search_tool.UserLocation
 38
 39
 40class McpAllowedToolsMcpToolFilter(BaseModel):
 41    read_only: Optional[bool] = None
 42    """Indicates whether or not a tool modifies data or is read-only.
 43
 44    If an MCP server is
 45    [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
 46    it will match this filter.
 47    """
 48
 49    tool_names: Optional[List[str]] = None
 50    """List of allowed tool names."""
 51
 52
 53McpAllowedTools: TypeAlias = Union[List[str], McpAllowedToolsMcpToolFilter, None]
 54
 55
 56class McpRequireApprovalMcpToolApprovalFilterAlways(BaseModel):
 57    read_only: Optional[bool] = None
 58    """Indicates whether or not a tool modifies data or is read-only.
 59
 60    If an MCP server is
 61    [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
 62    it will match this filter.
 63    """
 64
 65    tool_names: Optional[List[str]] = None
 66    """List of allowed tool names."""
 67
 68
 69class McpRequireApprovalMcpToolApprovalFilterNever(BaseModel):
 70    read_only: Optional[bool] = None
 71    """Indicates whether or not a tool modifies data or is read-only.
 72
 73    If an MCP server is
 74    [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
 75    it will match this filter.
 76    """
 77
 78    tool_names: Optional[List[str]] = None
 79    """List of allowed tool names."""
 80
 81
 82class McpRequireApprovalMcpToolApprovalFilter(BaseModel):
 83    always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways] = None
 84    """A filter object to specify which tools are allowed."""
 85
 86    never: Optional[McpRequireApprovalMcpToolApprovalFilterNever] = None
 87    """A filter object to specify which tools are allowed."""
 88
 89
 90McpRequireApproval: TypeAlias = Union[McpRequireApprovalMcpToolApprovalFilter, Literal["always", "never"], None]
 91
 92
 93class Mcp(BaseModel):
 94    server_label: str
 95    """A label for this MCP server, used to identify it in tool calls."""
 96
 97    type: Literal["mcp"]
 98    """The type of the MCP tool. Always `mcp`."""
 99
100    allowed_tools: Optional[McpAllowedTools] = None
101    """List of allowed tool names or a filter object."""
102
103    authorization: Optional[str] = None
104    """
105    An OAuth access token that can be used with a remote MCP server, either with a
106    custom MCP server URL or a service connector. Your application must handle the
107    OAuth authorization flow and provide the token here.
108    """
109
110    connector_id: Optional[
111        Literal[
112            "connector_dropbox",
113            "connector_gmail",
114            "connector_googlecalendar",
115            "connector_googledrive",
116            "connector_microsoftteams",
117            "connector_outlookcalendar",
118            "connector_outlookemail",
119            "connector_sharepoint",
120        ]
121    ] = None
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]] = None
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] = None
147    """Specify which of the MCP server's tools require approval."""
148
149    server_description: Optional[str] = None
150    """Optional description of the MCP server, used to provide more context."""
151
152    server_url: Optional[str] = None
153    """The URL for the MCP server.
154
155    One of `server_url` or `connector_id` must be provided.
156    """
157
158
159class CodeInterpreterContainerCodeInterpreterToolAuto(BaseModel):
160    type: Literal["auto"]
161    """Always `auto`."""
162
163    file_ids: Optional[List[str]] = None
164    """An optional list of uploaded files to make available to your code."""
165
166    memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]] = None
167
168
169CodeInterpreterContainer: TypeAlias = Union[str, CodeInterpreterContainerCodeInterpreterToolAuto]
170
171
172class CodeInterpreter(BaseModel):
173    container: 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: Literal["code_interpreter"]
181    """The type of the code interpreter tool. Always `code_interpreter`."""
182
183
184class ImageGenerationInputImageMask(BaseModel):
185    file_id: Optional[str] = None
186    """File ID for the mask image."""
187
188    image_url: Optional[str] = None
189    """Base64-encoded mask image."""
190
191
192class ImageGeneration(BaseModel):
193    type: Literal["image_generation"]
194    """The type of the image generation tool. Always `image_generation`."""
195
196    background: Optional[Literal["transparent", "opaque", "auto"]] = None
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"]] = None
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: Optional[ImageGenerationInputImageMask] = None
211    """Optional mask for inpainting.
212
213    Contains `image_url` (string, optional) and `file_id` (string, optional).
214    """
215
216    model: Optional[Literal["gpt-image-1", "gpt-image-1-mini"]] = None
217    """The image generation model to use. Default: `gpt-image-1`."""
218
219    moderation: Optional[Literal["auto", "low"]] = None
220    """Moderation level for the generated image. Default: `auto`."""
221
222    output_compression: Optional[int] = None
223    """Compression level for the output image. Default: 100."""
224
225    output_format: Optional[Literal["png", "webp", "jpeg"]] = None
226    """The output format of the generated image.
227
228    One of `png`, `webp`, or `jpeg`. Default: `png`.
229    """
230
231    partial_images: Optional[int] = None
232    """
233    Number of partial images to generate in streaming mode, from 0 (default value)
234    to 3.
235    """
236
237    quality: Optional[Literal["low", "medium", "high", "auto"]] = None
238    """The quality of the generated image.
239
240    One of `low`, `medium`, `high`, or `auto`. Default: `auto`.
241    """
242
243    size: Optional[Literal["1024x1024", "1024x1536", "1536x1024", "auto"]] = None
244    """The size of the generated image.
245
246    One of `1024x1024`, `1024x1536`, `1536x1024`, or `auto`. Default: `auto`.
247    """
248
249
250class LocalShell(BaseModel):
251    type: Literal["local_shell"]
252    """The type of the local shell tool. Always `local_shell`."""
253
254
255Tool: TypeAlias = Annotated[
256    Union[
257        FunctionTool,
258        FileSearchTool,
259        ComputerTool,
260        WebSearchTool,
261        Mcp,
262        CodeInterpreter,
263        ImageGeneration,
264        LocalShell,
265        FunctionShellTool,
266        CustomTool,
267        WebSearchPreviewTool,
268        ApplyPatchTool,
269    ],
270    PropertyInfo(discriminator="type"),
271]