"""Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT."""

from __future__ import annotations
from openrouter.types import BaseModel, UnrecognizedStr
from openrouter.utils import validate_open_enum
from pydantic.functional_validators import PlainValidator
from typing import List, Literal, Optional, Union
from typing_extensions import Annotated, NotRequired, TypedDict


ChatWebSearchShorthandType = Union[
    Literal[
        "web_search",
        "web_search_preview",
        "web_search_preview_2025_03_11",
        "web_search_2025_08_26",
    ],
    UnrecognizedStr,
]


ChatWebSearchShorthandEngine = Union[
    Literal[
        "auto",
        "native",
        "exa",
        "firecrawl",
        "parallel",
    ],
    UnrecognizedStr,
]
r"""Which search engine to use. \"auto\" (default) uses native if the provider supports it, otherwise Exa. \"native\" forces the provider's built-in search. \"exa\" forces the Exa search API. \"firecrawl\" uses Firecrawl (requires BYOK). \"parallel\" uses the Parallel search API."""


ChatWebSearchShorthandSearchContextSize = Union[
    Literal[
        "low",
        "medium",
        "high",
    ],
    UnrecognizedStr,
]
r"""How much context to retrieve per result. Defaults to medium (15000 chars). Only applies when using the Exa engine; ignored with native provider search."""


ChatWebSearchShorthandTypeApproximate = Literal["approximate",]


class ChatWebSearchShorthandUserLocationTypedDict(TypedDict):
    r"""Approximate user location for location-biased results."""

    type: NotRequired[ChatWebSearchShorthandTypeApproximate]
    city: NotRequired[str]
    region: NotRequired[str]
    country: NotRequired[str]
    timezone: NotRequired[str]


class ChatWebSearchShorthandUserLocation(BaseModel):
    r"""Approximate user location for location-biased results."""

    type: Optional[ChatWebSearchShorthandTypeApproximate] = None

    city: Optional[str] = None

    region: Optional[str] = None

    country: Optional[str] = None

    timezone: Optional[str] = None


ChatWebSearchShorthandParametersEngine = Union[
    Literal[
        "auto",
        "native",
        "exa",
        "firecrawl",
        "parallel",
    ],
    UnrecognizedStr,
]
r"""Which search engine to use. \"auto\" (default) uses native if the provider supports it, otherwise Exa. \"native\" forces the provider's built-in search. \"exa\" forces the Exa search API. \"firecrawl\" uses Firecrawl (requires BYOK). \"parallel\" uses the Parallel search API."""


ChatWebSearchShorthandParametersSearchContextSize = Union[
    Literal[
        "low",
        "medium",
        "high",
    ],
    UnrecognizedStr,
]
r"""How much context to retrieve per result. Defaults to medium (15000 chars). Only applies when using the Exa engine; ignored with native provider search."""


ChatWebSearchShorthandParametersType = Literal["approximate",]


class ChatWebSearchShorthandParametersUserLocationTypedDict(TypedDict):
    r"""Approximate user location for location-biased results."""

    type: NotRequired[ChatWebSearchShorthandParametersType]
    city: NotRequired[str]
    region: NotRequired[str]
    country: NotRequired[str]
    timezone: NotRequired[str]


class ChatWebSearchShorthandParametersUserLocation(BaseModel):
    r"""Approximate user location for location-biased results."""

    type: Optional[ChatWebSearchShorthandParametersType] = None

    city: Optional[str] = None

    region: Optional[str] = None

    country: Optional[str] = None

    timezone: Optional[str] = None


class ChatWebSearchShorthandParametersTypedDict(TypedDict):
    engine: NotRequired[ChatWebSearchShorthandParametersEngine]
    r"""Which search engine to use. \"auto\" (default) uses native if the provider supports it, otherwise Exa. \"native\" forces the provider's built-in search. \"exa\" forces the Exa search API. \"firecrawl\" uses Firecrawl (requires BYOK). \"parallel\" uses the Parallel search API."""
    max_results: NotRequired[float]
    r"""Maximum number of search results to return per search call. Defaults to 5. Applies to Exa, Firecrawl, and Parallel engines; ignored with native provider search."""
    max_total_results: NotRequired[float]
    r"""Maximum total number of search results across all search calls in a single request. Once this limit is reached, the tool will stop returning new results. Useful for controlling cost and context size in agentic loops."""
    search_context_size: NotRequired[ChatWebSearchShorthandParametersSearchContextSize]
    r"""How much context to retrieve per result. Defaults to medium (15000 chars). Only applies when using the Exa engine; ignored with native provider search."""
    user_location: NotRequired[ChatWebSearchShorthandParametersUserLocationTypedDict]
    r"""Approximate user location for location-biased results."""
    allowed_domains: NotRequired[List[str]]
    r"""Limit search results to these domains. Applies to Exa and Parallel engines. Not supported with Firecrawl or native provider search."""
    excluded_domains: NotRequired[List[str]]
    r"""Exclude search results from these domains. Applies to Exa and Parallel engines. Not supported with Firecrawl or native provider search."""


class ChatWebSearchShorthandParameters(BaseModel):
    engine: Annotated[
        Optional[ChatWebSearchShorthandParametersEngine],
        PlainValidator(validate_open_enum(False)),
    ] = None
    r"""Which search engine to use. \"auto\" (default) uses native if the provider supports it, otherwise Exa. \"native\" forces the provider's built-in search. \"exa\" forces the Exa search API. \"firecrawl\" uses Firecrawl (requires BYOK). \"parallel\" uses the Parallel search API."""

    max_results: Optional[float] = None
    r"""Maximum number of search results to return per search call. Defaults to 5. Applies to Exa, Firecrawl, and Parallel engines; ignored with native provider search."""

    max_total_results: Optional[float] = None
    r"""Maximum total number of search results across all search calls in a single request. Once this limit is reached, the tool will stop returning new results. Useful for controlling cost and context size in agentic loops."""

    search_context_size: Annotated[
        Optional[ChatWebSearchShorthandParametersSearchContextSize],
        PlainValidator(validate_open_enum(False)),
    ] = None
    r"""How much context to retrieve per result. Defaults to medium (15000 chars). Only applies when using the Exa engine; ignored with native provider search."""

    user_location: Optional[ChatWebSearchShorthandParametersUserLocation] = None
    r"""Approximate user location for location-biased results."""

    allowed_domains: Optional[List[str]] = None
    r"""Limit search results to these domains. Applies to Exa and Parallel engines. Not supported with Firecrawl or native provider search."""

    excluded_domains: Optional[List[str]] = None
    r"""Exclude search results from these domains. Applies to Exa and Parallel engines. Not supported with Firecrawl or native provider search."""


class ChatWebSearchShorthandTypedDict(TypedDict):
    r"""Web search tool using OpenAI Responses API syntax. Automatically converted to openrouter:web_search."""

    type: ChatWebSearchShorthandType
    engine: NotRequired[ChatWebSearchShorthandEngine]
    r"""Which search engine to use. \"auto\" (default) uses native if the provider supports it, otherwise Exa. \"native\" forces the provider's built-in search. \"exa\" forces the Exa search API. \"firecrawl\" uses Firecrawl (requires BYOK). \"parallel\" uses the Parallel search API."""
    max_results: NotRequired[float]
    r"""Maximum number of search results to return per search call. Defaults to 5. Applies to Exa, Firecrawl, and Parallel engines; ignored with native provider search."""
    max_total_results: NotRequired[float]
    r"""Maximum total number of search results across all search calls in a single request. Once this limit is reached, the tool will stop returning new results. Useful for controlling cost and context size in agentic loops."""
    search_context_size: NotRequired[ChatWebSearchShorthandSearchContextSize]
    r"""How much context to retrieve per result. Defaults to medium (15000 chars). Only applies when using the Exa engine; ignored with native provider search."""
    user_location: NotRequired[ChatWebSearchShorthandUserLocationTypedDict]
    r"""Approximate user location for location-biased results."""
    allowed_domains: NotRequired[List[str]]
    r"""Limit search results to these domains. Applies to Exa and Parallel engines. Not supported with Firecrawl or native provider search."""
    excluded_domains: NotRequired[List[str]]
    r"""Exclude search results from these domains. Applies to Exa and Parallel engines. Not supported with Firecrawl or native provider search."""
    parameters: NotRequired[ChatWebSearchShorthandParametersTypedDict]


class ChatWebSearchShorthand(BaseModel):
    r"""Web search tool using OpenAI Responses API syntax. Automatically converted to openrouter:web_search."""

    type: Annotated[
        ChatWebSearchShorthandType, PlainValidator(validate_open_enum(False))
    ]

    engine: Annotated[
        Optional[ChatWebSearchShorthandEngine],
        PlainValidator(validate_open_enum(False)),
    ] = None
    r"""Which search engine to use. \"auto\" (default) uses native if the provider supports it, otherwise Exa. \"native\" forces the provider's built-in search. \"exa\" forces the Exa search API. \"firecrawl\" uses Firecrawl (requires BYOK). \"parallel\" uses the Parallel search API."""

    max_results: Optional[float] = None
    r"""Maximum number of search results to return per search call. Defaults to 5. Applies to Exa, Firecrawl, and Parallel engines; ignored with native provider search."""

    max_total_results: Optional[float] = None
    r"""Maximum total number of search results across all search calls in a single request. Once this limit is reached, the tool will stop returning new results. Useful for controlling cost and context size in agentic loops."""

    search_context_size: Annotated[
        Optional[ChatWebSearchShorthandSearchContextSize],
        PlainValidator(validate_open_enum(False)),
    ] = None
    r"""How much context to retrieve per result. Defaults to medium (15000 chars). Only applies when using the Exa engine; ignored with native provider search."""

    user_location: Optional[ChatWebSearchShorthandUserLocation] = None
    r"""Approximate user location for location-biased results."""

    allowed_domains: Optional[List[str]] = None
    r"""Limit search results to these domains. Applies to Exa and Parallel engines. Not supported with Firecrawl or native provider search."""

    excluded_domains: Optional[List[str]] = None
    r"""Exclude search results from these domains. Applies to Exa and Parallel engines. Not supported with Firecrawl or native provider search."""

    parameters: Optional[ChatWebSearchShorthandParameters] = None
