# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

from __future__ import annotations

from typing import Dict, List, Union, Optional
from typing_extensions import Literal, Required, TypeAlias, TypedDict

from . import web_search_tool_param
from ..chat import ChatCompletionFunctionToolParam
from ..._types import SequenceNotStr
from .custom_tool_param import CustomToolParam
from .computer_tool_param import ComputerToolParam
from .function_tool_param import FunctionToolParam
from .namespace_tool_param import NamespaceToolParam
from .web_search_tool_param import WebSearchToolParam
from .apply_patch_tool_param import ApplyPatchToolParam
from .file_search_tool_param import FileSearchToolParam
from .tool_search_tool_param import ToolSearchToolParam
from .function_shell_tool_param import FunctionShellToolParam
from .web_search_preview_tool_param import WebSearchPreviewToolParam
from .computer_use_preview_tool_param import ComputerUsePreviewToolParam
from .container_network_policy_disabled_param import ContainerNetworkPolicyDisabledParam
from .container_network_policy_allowlist_param import ContainerNetworkPolicyAllowlistParam

__all__ = [
    "ToolParam",
    "Mcp",
    "McpAllowedTools",
    "McpAllowedToolsMcpToolFilter",
    "McpRequireApproval",
    "McpRequireApprovalMcpToolApprovalFilter",
    "McpRequireApprovalMcpToolApprovalFilterAlways",
    "McpRequireApprovalMcpToolApprovalFilterNever",
    "CodeInterpreter",
    "CodeInterpreterContainer",
    "CodeInterpreterContainerCodeInterpreterToolAuto",
    "CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy",
    "ProgrammaticToolCalling",
    "ImageGeneration",
    "ImageGenerationInputImageMask",
    "LocalShell",
]

WebSearchTool = web_search_tool_param.WebSearchToolParam
WebSearchToolFilters = web_search_tool_param.Filters
WebSearchToolUserLocation = web_search_tool_param.UserLocation


class McpAllowedToolsMcpToolFilter(TypedDict, total=False):
    """A filter object to specify which tools are allowed."""

    read_only: bool
    """Indicates whether or not a tool modifies data or is read-only.

    If an MCP server is
    [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
    it will match this filter.
    """

    tool_names: SequenceNotStr[str]
    """List of allowed tool names."""


McpAllowedTools: TypeAlias = Union[SequenceNotStr[str], McpAllowedToolsMcpToolFilter]


class McpRequireApprovalMcpToolApprovalFilterAlways(TypedDict, total=False):
    """A filter object to specify which tools are allowed."""

    read_only: bool
    """Indicates whether or not a tool modifies data or is read-only.

    If an MCP server is
    [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
    it will match this filter.
    """

    tool_names: SequenceNotStr[str]
    """List of allowed tool names."""


class McpRequireApprovalMcpToolApprovalFilterNever(TypedDict, total=False):
    """A filter object to specify which tools are allowed."""

    read_only: bool
    """Indicates whether or not a tool modifies data or is read-only.

    If an MCP server is
    [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
    it will match this filter.
    """

    tool_names: SequenceNotStr[str]
    """List of allowed tool names."""


class McpRequireApprovalMcpToolApprovalFilter(TypedDict, total=False):
    """Specify which of the MCP server's tools require approval.

    Can be
    `always`, `never`, or a filter object associated with tools
    that require approval.
    """

    always: McpRequireApprovalMcpToolApprovalFilterAlways
    """A filter object to specify which tools are allowed."""

    never: McpRequireApprovalMcpToolApprovalFilterNever
    """A filter object to specify which tools are allowed."""


McpRequireApproval: TypeAlias = Union[McpRequireApprovalMcpToolApprovalFilter, Literal["always", "never"]]


class Mcp(TypedDict, total=False):
    """
    Give the model access to additional tools via remote Model Context Protocol
    (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp).
    """

    server_label: Required[str]
    """A label for this MCP server, used to identify it in tool calls."""

    type: Required[Literal["mcp"]]
    """The type of the MCP tool. Always `mcp`."""

    allowed_callers: Optional[List[Literal["direct", "programmatic"]]]
    """The tool invocation context(s)."""

    allowed_tools: Optional[McpAllowedTools]
    """List of allowed tool names or a filter object."""

    authorization: str
    """
    An OAuth access token that can be used with a remote MCP server, either with a
    custom MCP server URL or a service connector. Your application must handle the
    OAuth authorization flow and provide the token here.
    """

    connector_id: Literal[
        "connector_dropbox",
        "connector_gmail",
        "connector_googlecalendar",
        "connector_googledrive",
        "connector_microsoftteams",
        "connector_outlookcalendar",
        "connector_outlookemail",
        "connector_sharepoint",
    ]
    """Identifier for service connectors, like those available in ChatGPT.

    One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more
    about service connectors
    [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors).

    Currently supported `connector_id` values are:

    - Dropbox: `connector_dropbox`
    - Gmail: `connector_gmail`
    - Google Calendar: `connector_googlecalendar`
    - Google Drive: `connector_googledrive`
    - Microsoft Teams: `connector_microsoftteams`
    - Outlook Calendar: `connector_outlookcalendar`
    - Outlook Email: `connector_outlookemail`
    - SharePoint: `connector_sharepoint`
    """

    defer_loading: bool
    """Whether this MCP tool is deferred and discovered via tool search."""

    headers: Optional[Dict[str, str]]
    """Optional HTTP headers to send to the MCP server.

    Use for authentication or other purposes.
    """

    require_approval: Optional[McpRequireApproval]
    """Specify which of the MCP server's tools require approval."""

    server_description: str
    """Optional description of the MCP server, used to provide more context."""

    server_url: str
    """The URL for the MCP server.

    One of `server_url`, `connector_id`, or `tunnel_id` must be provided.
    """

    tunnel_id: str
    """The Secure MCP Tunnel ID to use instead of a direct server URL.

    One of `server_url`, `connector_id`, or `tunnel_id` must be provided.
    """


CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy: TypeAlias = Union[
    ContainerNetworkPolicyDisabledParam, ContainerNetworkPolicyAllowlistParam
]


class CodeInterpreterContainerCodeInterpreterToolAuto(TypedDict, total=False):
    """Configuration for a code interpreter container.

    Optionally specify the IDs of the files to run the code on.
    """

    type: Required[Literal["auto"]]
    """Always `auto`."""

    file_ids: SequenceNotStr[str]
    """An optional list of uploaded files to make available to your code."""

    memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]
    """The memory limit for the code interpreter container."""

    network_policy: CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy
    """Network access policy for the container."""


CodeInterpreterContainer: TypeAlias = Union[str, CodeInterpreterContainerCodeInterpreterToolAuto]


class CodeInterpreter(TypedDict, total=False):
    """A tool that runs Python code to help generate a response to a prompt."""

    container: Required[CodeInterpreterContainer]
    """The code interpreter container.

    Can be a container ID or an object that specifies uploaded file IDs to make
    available to your code, along with an optional `memory_limit` setting.
    """

    type: Required[Literal["code_interpreter"]]
    """The type of the code interpreter tool. Always `code_interpreter`."""

    allowed_callers: Optional[List[Literal["direct", "programmatic"]]]
    """The tool invocation context(s)."""


class ProgrammaticToolCalling(TypedDict, total=False):
    type: Required[Literal["programmatic_tool_calling"]]
    """The type of the tool. Always `programmatic_tool_calling`."""


class ImageGenerationInputImageMask(TypedDict, total=False):
    """Optional mask for inpainting.

    Contains `image_url`
    (string, optional) and `file_id` (string, optional).
    """

    file_id: str
    """File ID for the mask image."""

    image_url: str
    """Base64-encoded mask image."""


class ImageGeneration(TypedDict, total=False):
    """A tool that generates images using the GPT image models."""

    type: Required[Literal["image_generation"]]
    """The type of the image generation tool. Always `image_generation`."""

    action: Literal["generate", "edit", "auto"]
    """Whether to generate a new image or edit an existing image. Default: `auto`."""

    background: Literal["transparent", "opaque", "auto"]
    """
    Allows to set transparency for the background of the generated image(s). This
    parameter is only supported for GPT image models that support transparent
    backgrounds. Must be one of `transparent`, `opaque`, or `auto` (default value).
    When `auto` is used, the model will automatically determine the best background
    for the image.

    `gpt-image-2` and `gpt-image-2-2026-04-21` do not support transparent
    backgrounds. Requests with `background` set to `transparent` will return an
    error for these models; use `opaque` or `auto` instead.

    If `transparent`, the output format needs to support transparency, so it should
    be set to either `png` (default value) or `webp`.
    """

    input_fidelity: Optional[Literal["high", "low"]]
    """
    Control how much effort the model will exert to match the style and features,
    especially facial features, of input images. This parameter is only supported
    for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for
    `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.
    """

    input_image_mask: ImageGenerationInputImageMask
    """Optional mask for inpainting.

    Contains `image_url` (string, optional) and `file_id` (string, optional).
    """

    model: Union[
        str,
        Literal[
            "gpt-image-1",
            "gpt-image-1-mini",
            "gpt-image-2",
            "gpt-image-2-2026-04-21",
            "gpt-image-1.5",
            "chatgpt-image-latest",
        ],
    ]
    """The image generation model to use. Default: `gpt-image-1`."""

    moderation: Literal["auto", "low"]
    """Moderation level for the generated image. Default: `auto`."""

    output_compression: int
    """Compression level for the output image. Default: 100."""

    output_format: Literal["png", "webp", "jpeg"]
    """The output format of the generated image.

    One of `png`, `webp`, or `jpeg`. Default: `png`.
    """

    partial_images: int
    """
    Number of partial images to generate in streaming mode, from 0 (default value)
    to 3.
    """

    quality: Literal["low", "medium", "high", "auto"]
    """The quality of the generated image.

    One of `low`, `medium`, `high`, or `auto`. Default: `auto`.
    """

    size: Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"]]
    """The size of the generated images.

    For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are
    supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height
    must both be divisible by 16 and the requested aspect ratio must be between 1:3
    and 3:1. Resolutions above `2560x1440` are experimental, and the maximum
    supported resolution is `3840x2160`. The requested size must also satisfy the
    model's current pixel and edge limits. The standard sizes `1024x1024`,
    `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is
    supported for models that allow automatic sizing. For `dall-e-2`, use one of
    `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`,
    `1792x1024`, or `1024x1792`.
    """


class LocalShell(TypedDict, total=False):
    """A tool that allows the model to execute shell commands in a local environment."""

    type: Required[Literal["local_shell"]]
    """The type of the local shell tool. Always `local_shell`."""


ToolParam: TypeAlias = Union[
    FunctionToolParam,
    FileSearchToolParam,
    ComputerToolParam,
    ComputerUsePreviewToolParam,
    WebSearchToolParam,
    Mcp,
    CodeInterpreter,
    ProgrammaticToolCalling,
    ImageGeneration,
    LocalShell,
    FunctionShellToolParam,
    CustomToolParam,
    NamespaceToolParam,
    ToolSearchToolParam,
    WebSearchPreviewToolParam,
    ApplyPatchToolParam,
]


ParseableToolParam: TypeAlias = Union[ToolParam, ChatCompletionFunctionToolParam]
