# 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 datetime import datetime
from typing_extensions import Literal, Required, Annotated, TypeAlias, TypedDict

from .._types import SequenceNotStr
from .._utils import PropertyInfo

__all__ = [
    "CallCreateParams",
    "Assistant",
    "AssistantCalendly",
    "AssistantCallRetryConfig",
    "AssistantCallRetryConfigCallingWindow",
    "AssistantFaqItem",
    "AssistantLlmModel",
    "AssistantLlmModelUnionMember0",
    "AssistantLlmModelUnionMember1",
    "AssistantStructuredOutputConfig",
    "AssistantVoice",
    "Concurrency",
]


class CallCreateParams(TypedDict, total=False):
    phone_number: Required[str]
    """The phone number to call in the E.164 format. Example: +1234567890"""

    assistant: Assistant
    """You can provide a custom assistant configuration here.

    If you don't provide an assistant_id, this assistant object will be used for
    this call.
    """

    assistant_id: str
    """The ID of the assistant to use for this call."""

    concurrency: Concurrency
    """Limit the number of concurrent calls for a given concurrency key."""

    force_now: bool
    """The prompt to use for the call. This will be given to the LLM (gpt-4.1)"""

    from_phone_number: str
    """The phone number to use for making the call (e.g., +1234567890).

    If not provided, uses the default trunk.
    """

    metadata: Dict[str, str]
    """Metadata to store with the call."""

    prompt_variables: Dict[str, str]
    """Variables to interpolate into the prompt.

    Wether you use an assistant_id or an assistant object, this will be used to
    interpolate the variables into the prompt.
    """

    scheduled_at: Annotated[Union[Union[str, datetime], object], PropertyInfo(format="iso8601")]
    """Schedule the call to start at a specific date and time (ISO 8601 format).

    If not provided, the call will start immediately.
    """


class AssistantCalendly(TypedDict, total=False):
    connection_id: Required[str]
    """
    The connection ID representing the link between your Calendly account and Revox.
    """

    event_type_id: Required[str]
    """The event type ID representing the event type to schedule.

    (eg: https://api.calendly.com/event_types/b2330295-2a91-4a1d-bb73-99e7707663d5)
    """


class AssistantCallRetryConfigCallingWindow(TypedDict, total=False):
    calling_window_end_time: Required[str]
    """
    End time for the calling window in the recipient's timezone (or
    timezone_override if provided). Format: 'HH:mm' (24-hour) or 'H:mma' (12-hour).
    Examples: '17:00', '6pm'. Default: '18:00'.
    """

    calling_window_start_time: Required[str]
    """
    Start time for the calling window in the recipient's timezone (or
    timezone_override if provided). Format: 'HH:mm' (24-hour) or 'H:mma' (12-hour).
    Examples: '09:00', '10am'. Default: '10:00'.
    """

    retry_delay_seconds: Required[int]
    """Delay between retry attempts in seconds. Default: 7200 (2 hours)."""


class AssistantCallRetryConfig(TypedDict, total=False):
    """
    Configuration for call retry behavior including time windows, delays, and max iterations. If not provided, defaults will be used.
    """

    calling_windows: Required[Iterable[AssistantCallRetryConfigCallingWindow]]

    max_retry_attempts: Required[int]
    """Maximum number of call retry attempts. Default: 3."""

    timezone: Optional[str]
    """
    Optional IANA timezone identifier to override the automatic timezone detection
    from phone number. If not provided, timezone is determined from the recipient's
    phone number country code. Examples: 'America/New_York', 'Europe/Paris'.
    """


class AssistantFaqItem(TypedDict, total=False):
    answer: Required[str]

    question: Required[str]


class AssistantLlmModelUnionMember0(TypedDict, total=False):
    name: Required[Literal["gpt-4.1", "ministral-3-8b-instruct"]]

    type: Required[Literal["dedicated-instance"]]


class AssistantLlmModelUnionMember1(TypedDict, total=False):
    openrouter_model_id: Required[str]
    """The model ID to use from OpenRouter. eg: openai/gpt-4.1"""

    openrouter_provider: Required[str]
    """The provider to use from OpenRouter. eg: nebius, openai, azure, etc."""

    type: Required[Literal["openrouter"]]
    """Use a model from OpenRouter."""


AssistantLlmModel: TypeAlias = Union[AssistantLlmModelUnionMember0, AssistantLlmModelUnionMember1]


class AssistantStructuredOutputConfig(TypedDict, total=False):
    name: Required[str]

    required: Required[bool]

    type: Required[Literal["string", "number", "boolean", "enum", "date", "datetime"]]

    description: str

    enum_options: SequenceNotStr[str]


class AssistantVoice(TypedDict, total=False):
    """The voice to use for the call.

    You can get the list of voices using the /voices endpoint
    """

    id: Required[str]
    """The ID of the voice."""

    provider: Required[Literal["cartesia", "elevenlabs"]]
    """The provider of the voice."""

    speed: float
    """The speed of the voice.

    Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2. Default is 1.0.
    """


class Assistant(TypedDict, total=False):
    """You can provide a custom assistant configuration here.

    If you don't provide an assistant_id, this assistant object will be used for this call.
    """

    prompt: Required[str]
    """The prompt to use for the call. This will be given to the LLM (gpt-4.1)"""

    background_sound: Optional[Literal["audio/office.ogg"]]
    """The background sound to play during the call.

    Useful to give the impression that your AI agent is in an office, in the street,
    or anywhere else you want.
    """

    calendly: AssistantCalendly

    call_retry_config: AssistantCallRetryConfig
    """
    Configuration for call retry behavior including time windows, delays, and max
    iterations. If not provided, defaults will be used.
    """

    end_of_call_sentence: str
    """Optional message to say when the agent decides to end the call."""

    faq_items: Iterable[AssistantFaqItem]
    """FAQ items to associate with this assistant.

    When provided, replaces all existing FAQ items.
    """

    first_sentence: str
    """The first sentence to use for the call. This will be given to the LLM"""

    first_sentence_delay_ms: int
    """Delay in milliseconds before speaking the first sentence. Default: 400."""

    first_sentence_mode: Literal["generated", "static", "none"]
    """How the first sentence should be handled.

    "generated" means the LLM will generate a response based on the first_sentence
    instruction. "static" means the first_sentence will be spoken exactly as
    provided. "none" means the agent will not speak first and will wait for the
    user.
    """

    ivr_navigation_enabled: bool
    """Enable IVR navigation tools.

    When enabled, the assistant can send DTMF tones and skip turns to navigate phone
    menus.
    """

    llm_model: AssistantLlmModel

    max_call_duration_secs: float
    """The maximum duration of the call in seconds.

    This is the maximum time the call will be allowed to run.
    """

    structured_output_config: Iterable[AssistantStructuredOutputConfig]
    """The structured output config to use for the call.

    This is used to extract the data from the call (like email, name, company name,
    etc.).
    """

    transfer_phone_number: Optional[str]
    """
    Phone number to transfer calls to when users request to speak to a human agent
    in E.164 format (e.g. +1234567890).
    """

    voice: AssistantVoice
    """The voice to use for the call.

    You can get the list of voices using the /voices endpoint
    """

    voicemail_message: Optional[str]
    """
    If set, when voicemail is detected the agent will speak this message then hang
    up; if null, hang up immediately.
    """

    webhook_url: str
    """The webhook URL to call when the call is completed."""


class Concurrency(TypedDict, total=False):
    """Limit the number of concurrent calls for a given concurrency key."""

    key: Required[str]
    """The key for which you want to limit the number of concurrent calls."""

    max: Required[float]
    """The maximum number of concurrent calls to allow for the given concurrency key."""
