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

from __future__ import annotations

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

from .message_type import MessageType
from .tool_return_param import ToolReturnParam
from .text_content_param import TextContentParam
from .image_content_param import ImageContentParam
from ..message_create_param import MessageCreateParam
from .approval_create_param import ApprovalCreateParam
from .reasoning_content_param import ReasoningContentParam
from .tool_call_content_param import ToolCallContentParam
from .tool_return_content_param import ToolReturnContentParam
from .omitted_reasoning_content_param import OmittedReasoningContentParam
from .redacted_reasoning_content_param import RedactedReasoningContentParam

__all__ = [
    "MessageCreateAsyncParams",
    "ClientTool",
    "InputUnionMember1",
    "InputUnionMember1SummarizedReasoningContent",
    "InputUnionMember1SummarizedReasoningContentSummary",
    "Message",
    "MessageToolReturnCreate",
]


class MessageCreateAsyncParams(TypedDict, total=False):
    assistant_message_tool_kwarg: str
    """The name of the message argument in the designated message tool.

    Still supported for legacy agent types, but deprecated for letta_v1_agent
    onward.
    """

    assistant_message_tool_name: str
    """The name of the designated message tool.

    Still supported for legacy agent types, but deprecated for letta_v1_agent
    onward.
    """

    callback_url: Optional[str]
    """Optional callback URL to POST to when the job completes"""

    client_tools: Optional[Iterable[ClientTool]]
    """Client-side tools that the agent can call.

    When the agent calls a client-side tool, execution pauses and returns control to
    the client to execute the tool and provide the result via a ToolReturn.
    """

    enable_thinking: str
    """
    If set to True, enables reasoning before responses or tool calls from the agent.
    """

    include_compaction_messages: bool
    """
    If True, compaction events emit structured `SummaryMessage` and `EventMessage`
    types. If False (default), compaction messages are not included in the response.
    """

    include_return_message_types: Optional[List[MessageType]]
    """Only return specified message types in the response.

    If `None` (default) returns all messages.
    """

    input: Union[str, Iterable[InputUnionMember1], None]
    """Syntactic sugar for a single user message.

    Equivalent to messages=[{'role': 'user', 'content': input}].
    """

    max_steps: int
    """Maximum number of steps the agent should take to process the request."""

    messages: Optional[Iterable[Message]]
    """The messages to be sent to the agent."""

    override_model: Optional[str]
    """Model handle to use for this request instead of the agent's default model.

    This allows sending a message to a different model without changing the agent's
    configuration.
    """

    return_logprobs: bool
    """If True, returns log probabilities of the output tokens in the response.

    Useful for RL training. Only supported for OpenAI-compatible providers
    (including SGLang).
    """

    return_token_ids: bool
    """
    If True, returns token IDs and logprobs for ALL LLM generations in the agent
    step, not just the last one. Uses SGLang native /generate endpoint. Returns
    'turns' field with TurnTokenData for each assistant/tool turn. Required for
    proper multi-turn RL training with loss masking.
    """

    top_logprobs: Optional[int]
    """Number of most likely tokens to return at each position (0-20).

    Requires return_logprobs=True.
    """

    use_assistant_message: bool
    """
    Whether the server should parse specific tool call arguments (default
    `send_message`) as `AssistantMessage` objects. Still supported for legacy agent
    types, but deprecated for letta_v1_agent onward.
    """


class ClientTool(TypedDict, total=False):
    """Schema for a client-side tool passed in the request.

    Client-side tools are executed by the client, not the server. When the agent
    calls a client-side tool, execution pauses and returns control to the client
    to execute the tool and provide the result.
    """

    name: Required[str]
    """The name of the tool function"""

    description: Optional[str]
    """Description of what the tool does"""

    parameters: Optional[Dict[str, object]]
    """JSON Schema for the function parameters"""


class InputUnionMember1SummarizedReasoningContentSummary(TypedDict, total=False):
    index: Required[int]
    """The index of the summary part."""

    text: Required[str]
    """The text of the summary part."""


class InputUnionMember1SummarizedReasoningContent(TypedDict, total=False):
    """The style of reasoning content returned by the OpenAI Responses API"""

    id: Required[str]
    """The unique identifier for this reasoning step."""

    summary: Required[Iterable[InputUnionMember1SummarizedReasoningContentSummary]]
    """Summaries of the reasoning content."""

    encrypted_content: str
    """The encrypted reasoning content."""

    type: Literal["summarized_reasoning"]
    """Indicates this is a summarized reasoning step."""


InputUnionMember1: TypeAlias = Union[
    TextContentParam,
    ImageContentParam,
    ToolCallContentParam,
    ToolReturnContentParam,
    ReasoningContentParam,
    RedactedReasoningContentParam,
    OmittedReasoningContentParam,
    InputUnionMember1SummarizedReasoningContent,
]


class MessageToolReturnCreate(TypedDict, total=False):
    """Submit tool return(s) from client-side tool execution.

    This is the preferred way to send tool results back to the agent after
    client-side tool execution. It is equivalent to sending an ApprovalCreate
    with tool return approvals, but provides a cleaner API for the common case.
    """

    tool_returns: Required[Iterable[ToolReturnParam]]
    """List of tool returns from client-side execution"""

    type: Literal["tool_return"]
    """The message type to be created."""


Message: TypeAlias = Union[MessageCreateParam, ApprovalCreateParam, MessageToolReturnCreate]
