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

from __future__ import annotations

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

from ..._types import SequenceNotStr
from ..shared_params import mcp_servers as _mcp_servers
from .tool_choice_any_param import ToolChoiceAnyParam
from .tool_choice_auto_param import ToolChoiceAutoParam
from .tool_choice_none_param import ToolChoiceNoneParam
from .tool_choice_tool_param import ToolChoiceToolParam
from .prediction_content_param import PredictionContentParam
from ..shared_params.credential import Credential
from .chat_completion_tool_param import ChatCompletionToolParam
from .chat_completion_audio_param import ChatCompletionAudioParam
from .thinking_config_enabled_param import ThinkingConfigEnabledParam
from ..shared_params.mcp_credentials import MCPCredentials
from ..shared_params.mcp_server_spec import MCPServerSpec
from .thinking_config_disabled_param import ThinkingConfigDisabledParam
from .chat_completion_functions_param import ChatCompletionFunctionsParam
from .chat_completion_tool_message_param import ChatCompletionToolMessageParam
from .chat_completion_user_message_param import ChatCompletionUserMessageParam
from ..shared_params.response_format_text import ResponseFormatText
from .chat_completion_system_message_param import ChatCompletionSystemMessageParam
from .chat_completion_function_message_param import ChatCompletionFunctionMessageParam
from .chat_completion_assistant_message_param import ChatCompletionAssistantMessageParam
from .chat_completion_developer_message_param import ChatCompletionDeveloperMessageParam
from ..shared_params.response_format_json_object import ResponseFormatJSONObject
from ..shared_params.response_format_json_schema import ResponseFormatJSONSchema

__all__ = [
    "CompletionCreateParamsBase",
    "Model",
    "Credentials",
    "MCPServers",
    "Message",
    "ResponseFormat",
    "SafetySetting",
    "Thinking",
    "ThinkingThinkingConfigAdaptive",
    "ToolChoice",
    "CompletionCreateParamsNonStreaming",
    "CompletionCreateParamsStreaming",
]


class CompletionCreateParamsBase(TypedDict, total=False):
    model: Required[Model]
    """Model identifier.

    Accepts model ID strings, lists for routing, or DedalusModel objects with
    per-model settings.
    """

    agent_attributes: Optional[Dict[str, float]]
    """Agent attributes. Values in [0.0, 1.0]."""

    audio: Optional[ChatCompletionAudioParam]
    """Parameters for audio output.

    Required when audio output is requested with `modalities: ["audio"]`.
    [Learn more](/docs/guides/audio).

    Fields:

    - voice (required): VoiceIdsOrCustomVoice
    - format (required): Literal["wav", "aac", "mp3", "flac", "opus", "pcm16"]
    """

    automatic_tool_execution: bool
    """Execute tools server-side.

    If false, returns raw tool calls for manual handling.
    """

    cached_content: Optional[str]
    """Optional.

    The name of the content [cached](https://ai.google.dev/gemini-api/docs/caching)
    to use as context to serve the prediction. Format:
    `cachedContents/{cachedContent}`
    """

    correlation_id: Optional[str]
    """Stable session ID for resuming a previous handoff.

    Returned by the server on handoff; echo it on the next request to resume.
    """

    credentials: Optional[Credentials]
    """Credentials for MCP server authentication.

    Each credential is matched to servers by connection name.
    """

    deferred: Optional[bool]
    """If set to `true`, the request returns a `request_id`.

    You can then get the deferred response by GET
    `/v1/chat/deferred-completion/{request_id}`.
    """

    deferred_calls: Optional[Iterable["DeferredCallResponseParam"]]
    """Tier 2 stateless resumption.

    Deferred tool specs from a previous handoff response, sent back verbatim so the
    server can resume without Redis.
    """

    frequency_penalty: Optional[float]
    """Number between -2.0 and 2.0.

    Positive values penalize new tokens based on their existing frequency in the
    text so far, decreasing the model's likelihood to repeat the same line verbatim.
    """

    function_call: Optional[str]
    """Deprecated in favor of `tool_choice`.

    Controls which (if any) function is called by the model. `none` means the model
    will not call a function and instead generates a message. `auto` means the model
    can pick between generating a message or calling a function. Specifying a
    particular function via `{"name": "my_function"}` forces the model to call that
    function. `none` is the default when no functions are present. `auto` is the
    default if functions are present.
    """

    functions: Optional[Iterable[ChatCompletionFunctionsParam]]
    """Deprecated in favor of `tools`.

    A list of functions the model may generate JSON inputs for.
    """

    generation_config: Optional["JSONObjectInput"]
    """Generation parameters wrapper (Google-specific)"""

    guardrails: Optional[Iterable[Dict[str, object]]]
    """Content filtering and safety policy configuration."""

    handoff_config: Optional[Dict[str, object]]
    """Configuration for multi-model handoffs."""

    handoff_mode: Optional[bool]
    """Handoff control.

    None or omitted: auto-detect. true: structured handoff (SDK). false: drop-in
    (LLM re-run for mixed turns).
    """

    inference_geo: Optional[str]
    """Specifies the geographic region for inference processing.

    If not specified, the workspace's `default_inference_geo` is used.
    """

    logit_bias: Optional[Dict[str, int]]
    """Modify the likelihood of specified tokens appearing in the completion.

    Accepts a JSON object that maps tokens (specified by their token ID in the
    tokenizer) to an associated bias value from -100 to 100. Mathematically, the
    bias is added to the logits generated by the model prior to sampling. The exact
    effect will vary per model, but values between -1 and 1 should decrease or
    increase likelihood of selection; values like -100 or 100 should result in a ban
    or exclusive selection of the relevant token.
    """

    logprobs: Optional[bool]
    """Whether to return log probabilities of the output tokens or not.

    If true, returns the log probabilities of each output token returned in the
    `content` of `message`.
    """

    max_completion_tokens: Optional[int]
    """Maximum tokens in completion (newer parameter name)"""

    max_tokens: Optional[int]
    """Maximum tokens in completion"""

    max_turns: Optional[int]
    """Maximum conversation turns."""

    mcp_servers: Optional[MCPServers]
    """MCP server identifiers.

    Accepts marketplace slugs, URLs, or MCPServerSpec objects. MCP tools are
    executed server-side and billed separately.
    """

    messages: Optional[Iterable[Message]]
    """Conversation history (OpenAI: messages, Google: contents, Responses: input)"""

    metadata: Optional["JSONObjectInput"]
    """Set of 16 key-value pairs that can be attached to an object.

    This can be useful for storing additional information about the object in a
    structured format, and querying for objects via API or the dashboard. Keys are
    strings with a maximum length of 64 characters. Values are strings with a
    maximum length of 512 characters.
    """

    modalities: Optional[SequenceNotStr[str]]
    """Output types that you would like the model to generate.

    Most models are capable of generating text, which is the default: `["text"]` The
    `gpt-4o-audio-preview` model can also be used to
    [generate audio](/docs/guides/audio). To request that this model generate both
    text and audio responses, you can use: `["text", "audio"]`
    """

    model_attributes: Optional[Dict[str, Dict[str, float]]]
    """Model attributes for routing.

    Maps model IDs to attribute dictionaries with values in [0.0, 1.0].
    """

    n: Optional[int]
    """How many chat completion choices to generate for each input message.

    Note that you will be charged based on the number of generated tokens across all
    of the choices. Keep `n` as `1` to minimize costs.
    """

    output_config: Optional["JSONObjectInput"]

    parallel_tool_calls: Optional[bool]
    """Whether to enable parallel tool calls (Anthropic uses inverted polarity)."""

    prediction: Optional[PredictionContentParam]
    """
    Static predicted output content, such as the content of a text file that is
    being regenerated.

    Fields:

    - type (required): Literal["content"]
    - content (required): str |
      Annotated[list[ChatCompletionRequestMessageContentPartText], MinLen(1),
      ArrayTitle("PredictionContentArray")]
    """

    presence_penalty: Optional[float]
    """Number between -2.0 and 2.0.

    Positive values penalize new tokens based on whether they appear in the text so
    far, increasing the model's likelihood to talk about new topics.
    """

    prompt_cache_key: Optional[str]
    """
    Used by OpenAI to cache responses for similar requests to optimize your cache
    hit rates. Replaces the `user` field. [Learn more](/docs/guides/prompt-caching).
    """

    prompt_cache_retention: Optional[str]
    """The retention policy for the prompt cache.

    Set to `24h` to enable extended prompt caching, which keeps cached prefixes
    active for longer, up to a maximum of 24 hours.
    [Learn more](/docs/guides/prompt-caching#prompt-cache-retention).
    """

    prompt_mode: Optional[Literal["reasoning"]]
    """Allows toggling between the reasoning mode and no system prompt.

    When set to `reasoning` the system prompt for reasoning models will be used.
    """

    reasoning_effort: Optional[str]
    """
    Constrains effort on reasoning for
    [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently
    supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`.
    Reducing reasoning effort can result in faster responses and fewer tokens used
    on reasoning in a response. - `gpt-5.1` defaults to `none`, which does not
    perform reasoning. The supported reasoning values for `gpt-5.1` are `none`,
    `low`, `medium`, and `high`. Tool calls are supported for all reasoning values
    in gpt-5.1. - All models before `gpt-5.1` default to `medium` reasoning effort,
    and do not support `none`. - The `gpt-5-pro` model defaults to (and only
    supports) `high` reasoning effort. - `xhigh` is supported for all models after
    `gpt-5.1-codex-max`.
    """

    response_format: Optional[ResponseFormat]
    """An object specifying the format that the model must output.

    Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured
    Outputs which ensures the model will match your supplied JSON schema. Learn more
    in the [Structured Outputs guide](/docs/guides/structured-outputs). Setting to
    `{ "type": "json_object" }` enables the older JSON mode, which ensures the
    message the model generates is valid JSON. Using `json_schema` is preferred for
    models that support it.
    """

    safe_prompt: Optional[bool]
    """Whether to inject a safety prompt before all conversations."""

    safety_identifier: Optional[str]
    """
    A stable identifier used to help detect users of your application that may be
    violating OpenAI's usage policies. The IDs should be a string that uniquely
    identifies each user. We recommend hashing their username or email address, in
    order to avoid sending us any identifying information.
    [Learn more](/docs/guides/safety-best-practices#safety-identifiers).
    """

    safety_settings: Optional[Iterable[SafetySetting]]
    """Safety/content filtering settings (Google-specific)"""

    search_parameters: Optional["JSONObjectInput"]
    """Set the parameters to be used for searched data.

    If not set, no data will be acquired by the model.
    """

    seed: Optional[int]
    """Random seed for deterministic output"""

    service_tier: Optional[str]
    """Service tier for request processing"""

    speed: Optional[Literal["standard", "fast"]]
    """The inference speed mode for this request.

    `"fast"` enables high output-tokens-per-second inference.
    """

    stop: Union[SequenceNotStr[str], str, None]
    """Sequences that stop generation"""

    store: Optional[bool]
    """
    Whether or not to store the output of this chat completion request for use in
    our [model distillation](/docs/guides/distillation) or
    [evals](/docs/guides/evals) products. Supports text and image inputs. Note:
    image inputs over 8MB will be dropped.
    """

    stream_options: Optional["JSONObjectInput"]
    """Options for streaming response. Only set this when you set `stream: true`."""

    system_instruction: Union["JSONObjectInput", str, None]
    """System instruction/prompt"""

    temperature: Optional[float]
    """Sampling temperature (0-2 for most providers)"""

    thinking: Optional[Thinking]
    """Extended thinking configuration (Anthropic-specific)"""

    tool_choice: Optional[ToolChoice]
    """Controls which (if any) tool is called by the model.

    `none` means the model will not call any tool and instead generates a message.
    `auto` means the model can pick between generating a message or calling one or
    more tools. `required` means the model must call one or more tools. Specifying a
    particular tool via `{"type": "function", "function": {"name": "my_function"}}`
    forces the model to call that tool. `none` is the default when no tools are
    present. `auto` is the default if tools are present.
    """

    tool_config: Optional["JSONObjectInput"]
    """Tool calling configuration (Google-specific)"""

    tools: Optional[Iterable[ChatCompletionToolParam]]
    """Available tools/functions for the model"""

    top_k: Optional[int]
    """Top-k sampling parameter"""

    top_logprobs: Optional[int]
    """
    An integer between 0 and 20 specifying the number of most likely tokens to
    return at each token position, each with an associated log probability.
    `logprobs` must be set to `true` if this parameter is used.
    """

    top_p: Optional[float]
    """Nucleus sampling threshold"""

    user: Optional[str]
    """This field is being replaced by `safety_identifier` and `prompt_cache_key`.

    Use `prompt_cache_key` instead to maintain caching optimizations. A stable
    identifier for your end-users. Used to boost cache hit rates by better bucketing
    similar requests and to help OpenAI detect and prevent abuse.
    [Learn more](/docs/guides/safety-best-practices#safety-identifiers).
    """

    verbosity: Optional[str]
    """Constrains the verbosity of the model's response.

    Lower values will result in more concise responses, while higher values will
    result in more verbose responses. Currently supported values are `low`,
    `medium`, and `high`.
    """

    web_search_options: Optional["JSONObjectInput"]
    """This tool searches the web for relevant results to use in a response.

    Learn more about the
    [web search tool](/docs/guides/tools-web-search?api-mode=chat).
    """


Model: TypeAlias = Union[str, "DedalusModel", SequenceNotStr["DedalusModelChoice"]]

Credentials: TypeAlias = Union[Credential, MCPCredentials]

MCPServers: TypeAlias = Union[str, MCPServerSpec, _mcp_servers.MCPServers]

Message: TypeAlias = Union[
    ChatCompletionDeveloperMessageParam,
    ChatCompletionSystemMessageParam,
    ChatCompletionUserMessageParam,
    ChatCompletionAssistantMessageParam,
    ChatCompletionToolMessageParam,
    ChatCompletionFunctionMessageParam,
]

ResponseFormat: TypeAlias = Union[ResponseFormatText, ResponseFormatJSONSchema, ResponseFormatJSONObject]


class SafetySetting(TypedDict, total=False):
    """Safety setting, affecting the safety-blocking behavior.

    Passing a safety setting for a category changes the allowed probability that
    content is blocked.

    Fields:
    - threshold (required): Literal["HARM_BLOCK_THRESHOLD_UNSPECIFIED", "BLOCK_LOW_AND_ABOVE", "BLOCK_MEDIUM_AND_ABOVE", "BLOCK_ONLY_HIGH", "BLOCK_NONE", "OFF"]
    - category (required): HarmCategory
    """

    category: Required[
        Literal[
            "HARM_CATEGORY_UNSPECIFIED",
            "HARM_CATEGORY_DEROGATORY",
            "HARM_CATEGORY_TOXICITY",
            "HARM_CATEGORY_VIOLENCE",
            "HARM_CATEGORY_SEXUAL",
            "HARM_CATEGORY_MEDICAL",
            "HARM_CATEGORY_DANGEROUS",
            "HARM_CATEGORY_HARASSMENT",
            "HARM_CATEGORY_HATE_SPEECH",
            "HARM_CATEGORY_SEXUALLY_EXPLICIT",
            "HARM_CATEGORY_DANGEROUS_CONTENT",
            "HARM_CATEGORY_CIVIC_INTEGRITY",
        ]
    ]
    """Required. The category for this setting."""

    threshold: Required[
        Literal[
            "HARM_BLOCK_THRESHOLD_UNSPECIFIED",
            "BLOCK_LOW_AND_ABOVE",
            "BLOCK_MEDIUM_AND_ABOVE",
            "BLOCK_ONLY_HIGH",
            "BLOCK_NONE",
            "OFF",
        ]
    ]
    """Required. Controls the probability threshold at which harm is blocked."""


class ThinkingThinkingConfigAdaptive(TypedDict, total=False):
    """Schema for ThinkingConfigAdaptive.

    Fields:
    - type (required): Literal["adaptive"]
    """

    type: Required[Literal["adaptive"]]


Thinking: TypeAlias = Union[ThinkingConfigEnabledParam, ThinkingConfigDisabledParam, ThinkingThinkingConfigAdaptive]

ToolChoice: TypeAlias = Union[str, ToolChoiceAutoParam, ToolChoiceAnyParam, ToolChoiceToolParam, ToolChoiceNoneParam]


class CompletionCreateParamsNonStreaming(CompletionCreateParamsBase, total=False):
    stream: Optional[Literal[False]]
    """Enable streaming response"""


class CompletionCreateParamsStreaming(CompletionCreateParamsBase):
    stream: Required[Literal[True]]
    """Enable streaming response"""


CompletionCreateParams = Union[CompletionCreateParamsNonStreaming, CompletionCreateParamsStreaming]

from ..shared_params.dedalus_model import DedalusModel
from .deferred_call_response_param import DeferredCallResponseParam
from ..shared_params.json_object_input import JSONObjectInput
from ..shared_params.dedalus_model_choice import DedalusModelChoice
