# This file was auto-generated by Fern from our API Definition.

import datetime as dt
import typing

import pydantic
from ..core.pydantic_utilities import IS_PYDANTIC_V2
from ..core.unchecked_base_model import UncheckedBaseModel
from .letta_request_config import LettaRequestConfig
from .run_status import RunStatus
from .stop_reason_type import StopReasonType


class Run(UncheckedBaseModel):
    """
    Representation of a run - a conversation or processing session for an agent.
    Runs track when agents process messages and maintain the relationship between agents, steps, and messages.

    Parameters:
        id (str): The unique identifier of the run (prefixed with 'run-').
        status (JobStatus): The current status of the run.
        created_at (datetime): The timestamp when the run was created.
        completed_at (datetime): The timestamp when the run was completed.
        agent_id (str): The unique identifier of the agent associated with the run.
        stop_reason (StopReasonType): The reason why the run was stopped.
        background (bool): Whether the run was created in background mode.
        metadata (dict): Additional metadata for the run.
        request_config (LettaRequestConfig): The request configuration for the run.
    """

    id: typing.Optional[str] = pydantic.Field(default=None)
    """
    The human-friendly ID of the Run
    """

    status: typing.Optional[RunStatus] = pydantic.Field(default=None)
    """
    The current status of the run.
    """

    created_at: typing.Optional[dt.datetime] = pydantic.Field(default=None)
    """
    The timestamp when the run was created.
    """

    completed_at: typing.Optional[dt.datetime] = pydantic.Field(default=None)
    """
    The timestamp when the run was completed.
    """

    agent_id: str = pydantic.Field()
    """
    The unique identifier of the agent associated with the run.
    """

    background: typing.Optional[bool] = pydantic.Field(default=None)
    """
    Whether the run was created in background mode.
    """

    metadata: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] = pydantic.Field(default=None)
    """
    Additional metadata for the run.
    """

    request_config: typing.Optional[LettaRequestConfig] = pydantic.Field(default=None)
    """
    The request configuration for the run.
    """

    stop_reason: typing.Optional[StopReasonType] = pydantic.Field(default=None)
    """
    The reason why the run was stopped.
    """

    callback_url: typing.Optional[str] = pydantic.Field(default=None)
    """
    If set, POST to this URL when the run completes.
    """

    callback_sent_at: typing.Optional[dt.datetime] = pydantic.Field(default=None)
    """
    Timestamp when the callback was last attempted.
    """

    callback_status_code: typing.Optional[int] = pydantic.Field(default=None)
    """
    HTTP status code returned by the callback endpoint.
    """

    callback_error: typing.Optional[str] = pydantic.Field(default=None)
    """
    Optional error message from attempting to POST the callback endpoint.
    """

    ttft_ns: typing.Optional[int] = pydantic.Field(default=None)
    """
    Time to first token for a run in nanoseconds
    """

    total_duration_ns: typing.Optional[int] = pydantic.Field(default=None)
    """
    Total run duration in nanoseconds
    """

    if IS_PYDANTIC_V2:
        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
    else:

        class Config:
            frozen = True
            smart_union = True
            extra = pydantic.Extra.allow
