# 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
from .eval_type import EvalType
from .usage_param import UsageParam

__all__ = [
    "IngestCreateParams",
    "Event",
    "EventIngestTrace",
    "EventIngestTraceEval",
    "EventIngestTraceEvalDefinition",
    "EventIngestTraceEvalDefinitionApplication",
    "EventIngestTraceEvalDefinitionGlobalConfig",
    "EventIngestTraceEvalDefinitionGlobalConfigCriterion",
    "EventIngestTraceEvalDefinitionGlobalConfigGroundTruth",
    "EventIngestTraceEvalDefinitionGlobalConfigOutputMatchStringConfig",
    "EventIngestTraceEvalDefinitionGlobalConfigOutputMatchStringConfigExtract",
    "EventIngestTraceEvalDefinitionGlobalConfigOutputMatchListConfig",
    "EventIngestTraceEvalDefinitionGlobalConfigOutputMatchListConfigExtract",
    "EventIngestTraceEvalResults",
    "EventIngestTraceEvalResultsUnionMember0",
    "EventIngestTraceEvalResultsUnionMember1",
    "EventIngestTraceEvalResultsUnionMember2",
    "EventIngestTraceEvalResultsUnionMember2AnswerRelevancy",
    "EventIngestTraceEvalResultsUnionMember2AnswerRelevancyMetadata",
    "EventIngestTraceEvalResultsUnionMember2AnswerRelevancyMetadataQuestion",
    "EventIngestTraceEvalResultsUnionMember2AnswerRelevancyMetadataSimilarity",
    "EventIngestTraceEvalResultsUnionMember2ContextPrecision",
    "EventIngestTraceEvalResultsUnionMember2ContextPrecisionMetadata",
    "EventIngestTraceEvalResultsUnionMember2ContextRelevancy",
    "EventIngestTraceEvalResultsUnionMember2ContextRelevancyMetadata",
    "EventIngestTraceEvalResultsUnionMember2ContextRelevancyMetadataRelevantSentence",
    "EventIngestTraceEvalResultsUnionMember2Faithfulness",
    "EventIngestTraceEvalResultsUnionMember2FaithfulnessMetadata",
    "EventIngestTraceEvalResultsUnionMember2FaithfulnessMetadataFaithfulness",
    "EventIngestTraceEvalResultsUnionMember3",
    "EventIngestTraceEvalResultsUnionMember3Metadata",
    "EventIngestTraceEvalResultsUnionMember4",
    "EventIngestTraceEvalResultsUnionMember4Classification",
    "EventIngestTraceEvalResultsUnionMember5",
    "EventIngestTraceEvalResultsUnionMember5Missing",
    "EventIngestTraceStep",
    "EventIngestTraceStepLlmStartStep",
    "EventIngestTraceStepLlmEndStep",
    "EventIngestTraceStepToolStep",
    "EventIngestTraceStepRetrieverStep",
    "EventIngestTraceStepLogStep",
    "EventIngestTraceStepGroupStep",
    "EventIngestTraceStepResponseStep",
    "EventIngestTraceStepRequestStep",
    "EventIngestLlmStartStep",
    "EventIngestLlmEndStep",
    "EventIngestToolStep",
    "EventIngestRetrieverStep",
    "EventIngestLogStep",
    "EventIngestGroupStep",
    "EventIngestResponseStep",
    "EventIngestRequestStep",
]


class IngestCreateParams(TypedDict, total=False):
    events: Required[Iterable[Event]]
    """Array of events to be ingested, which can be traces or steps."""


class EventIngestTraceEvalDefinitionApplication(TypedDict, total=False):
    """Application configuration and metadata"""

    id: Required[str]
    """Unique identifier of the application"""

    context: Required[str]
    """Context/instructions for the application"""

    created_at: Required[Annotated[Union[str, datetime], PropertyInfo(alias="createdAt", format="iso8601")]]
    """When the application was created"""

    description: Required[str]
    """Description of the application"""

    language: Required[str]
    """Language of the application"""

    modified_at: Required[Annotated[Union[str, datetime], PropertyInfo(alias="modifiedAt", format="iso8601")]]
    """When the application was last modified"""

    org_id: Required[Annotated[str, PropertyInfo(alias="orgId")]]
    """Organization ID that owns this application"""

    slug: Required[str]
    """URL-friendly slug for the application"""

    title: Required[str]
    """Title of the application"""

    type: Required[Literal["CHATBOT", "AGENT"]]
    """Type of the application. Valid values are CHATBOT or AGENT."""

    environment: Literal["DEV", "PROD"]
    """Environment of the application. Defaults to DEV."""


class EventIngestTraceEvalDefinitionGlobalConfigCriterion(TypedDict, total=False):
    criterion: Required[str]
    """The criterion describes what our evaluation LLM must look for in the response.

    Remember that the answer to the criterion must be as a pass/fail.
    """


class EventIngestTraceEvalDefinitionGlobalConfigGroundTruth(TypedDict, total=False):
    ground_truth: Required[Annotated[str, PropertyInfo(alias="groundTruth")]]
    """
    The ground truth is the most correct answer to the task that we measure the
    response against
    """


class EventIngestTraceEvalDefinitionGlobalConfigOutputMatchStringConfigExtract(TypedDict, total=False):
    flags: Required[str]

    group: Required[Union[int, Iterable[int]]]

    pattern: Required[str]


class EventIngestTraceEvalDefinitionGlobalConfigOutputMatchStringConfig(TypedDict, total=False):
    type: Required[Literal["string"]]

    extract: EventIngestTraceEvalDefinitionGlobalConfigOutputMatchStringConfigExtract


class EventIngestTraceEvalDefinitionGlobalConfigOutputMatchListConfigExtract(TypedDict, total=False):
    flags: Required[str]

    group: Required[Union[int, Iterable[int]]]

    pattern: Required[str]


class EventIngestTraceEvalDefinitionGlobalConfigOutputMatchListConfig(TypedDict, total=False):
    match_mode: Required[Annotated[Literal["exact_unordered", "contains"], PropertyInfo(alias="matchMode")]]

    type: Required[Literal["list"]]

    extract: EventIngestTraceEvalDefinitionGlobalConfigOutputMatchListConfigExtract

    pass_threshold: Annotated[float, PropertyInfo(alias="passThreshold")]

    score_metric: Annotated[Literal["f1", "precision", "recall"], PropertyInfo(alias="scoreMetric")]


EventIngestTraceEvalDefinitionGlobalConfig: TypeAlias = Union[
    EventIngestTraceEvalDefinitionGlobalConfigCriterion,
    EventIngestTraceEvalDefinitionGlobalConfigGroundTruth,
    EventIngestTraceEvalDefinitionGlobalConfigOutputMatchStringConfig,
    EventIngestTraceEvalDefinitionGlobalConfigOutputMatchListConfig,
]


class EventIngestTraceEvalDefinition(TypedDict, total=False):
    id: Required[str]

    created_at: Required[Annotated[Union[str, datetime], PropertyInfo(alias="createdAt", format="iso8601")]]
    """When the eval definition was created"""

    modified_at: Required[Annotated[Union[str, datetime], PropertyInfo(alias="modifiedAt", format="iso8601")]]
    """When the eval definition was last modified"""

    name: Required[str]

    type: Required[EvalType]

    application: Optional[EventIngestTraceEvalDefinitionApplication]
    """Application configuration and metadata"""

    global_config: Annotated[EventIngestTraceEvalDefinitionGlobalConfig, PropertyInfo(alias="globalConfig")]

    style_guide_id: Annotated[Optional[str], PropertyInfo(alias="styleGuideId")]


class EventIngestTraceEvalResultsUnionMember0(TypedDict, total=False):
    analysis: Required[str]

    clarity: Required[float]

    coherence: Required[float]

    engagingness: Required[float]

    naturalness: Required[float]

    relevance: Required[float]


class EventIngestTraceEvalResultsUnionMember1(TypedDict, total=False):
    analysis: Required[str]
    """
    A brief explanation for your rating, referring to specific aspects of the
    response and the query. Make sure that the explanation is formatted as markdown,
    and that it is easy to read and understand.
    """

    score: Required[float]
    """The score of the response based on the style guide from 1-5"""


class EventIngestTraceEvalResultsUnionMember2AnswerRelevancyMetadataQuestion(TypedDict, total=False):
    question: Required[str]


class EventIngestTraceEvalResultsUnionMember2AnswerRelevancyMetadataSimilarity(TypedDict, total=False):
    question: Required[str]

    score: Required[float]


class EventIngestTraceEvalResultsUnionMember2AnswerRelevancyMetadata(TypedDict, total=False):
    questions: Required[Iterable[EventIngestTraceEvalResultsUnionMember2AnswerRelevancyMetadataQuestion]]

    similarity: Required[Iterable[EventIngestTraceEvalResultsUnionMember2AnswerRelevancyMetadataSimilarity]]


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

    score: Required[float]

    error: str

    metadata: EventIngestTraceEvalResultsUnionMember2AnswerRelevancyMetadata


class EventIngestTraceEvalResultsUnionMember2ContextPrecisionMetadata(TypedDict, total=False):
    reason: Required[str]

    verdict: Required[int]


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

    score: Required[float]

    error: str

    metadata: EventIngestTraceEvalResultsUnionMember2ContextPrecisionMetadata


class EventIngestTraceEvalResultsUnionMember2ContextRelevancyMetadataRelevantSentence(TypedDict, total=False):
    reasons: Required[SequenceNotStr[str]]

    sentence: Required[str]


class EventIngestTraceEvalResultsUnionMember2ContextRelevancyMetadata(TypedDict, total=False):
    relevant_sentences: Required[
        Annotated[
            Iterable[EventIngestTraceEvalResultsUnionMember2ContextRelevancyMetadataRelevantSentence],
            PropertyInfo(alias="relevantSentences"),
        ]
    ]


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

    score: Required[float]

    error: str

    metadata: EventIngestTraceEvalResultsUnionMember2ContextRelevancyMetadata


class EventIngestTraceEvalResultsUnionMember2FaithfulnessMetadataFaithfulness(TypedDict, total=False):
    reason: Required[str]

    statement: Required[str]

    verdict: Required[int]

    classification: Literal["UNSUPPORTED_CLAIM", "CONTRADICTION", "PARTIAL_HALLUCINATION", "SCOPE_DRIFT"]
    """Classification of the hallucination type (only present when verdict is 0)"""


class EventIngestTraceEvalResultsUnionMember2FaithfulnessMetadata(TypedDict, total=False):
    faithfulness: Required[Iterable[EventIngestTraceEvalResultsUnionMember2FaithfulnessMetadataFaithfulness]]

    statements: Required[SequenceNotStr[str]]


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

    score: Required[float]

    error: str

    metadata: EventIngestTraceEvalResultsUnionMember2FaithfulnessMetadata


class EventIngestTraceEvalResultsUnionMember2(TypedDict, total=False):
    answer_relevancy: Required[
        Annotated[EventIngestTraceEvalResultsUnionMember2AnswerRelevancy, PropertyInfo(alias="AnswerRelevancy")]
    ]

    context_precision: Required[
        Annotated[EventIngestTraceEvalResultsUnionMember2ContextPrecision, PropertyInfo(alias="ContextPrecision")]
    ]

    context_relevancy: Required[
        Annotated[EventIngestTraceEvalResultsUnionMember2ContextRelevancy, PropertyInfo(alias="ContextRelevancy")]
    ]

    faithfulness: Required[
        Annotated[EventIngestTraceEvalResultsUnionMember2Faithfulness, PropertyInfo(alias="Faithfulness")]
    ]


class EventIngestTraceEvalResultsUnionMember3Metadata(TypedDict, total=False):
    rationale: Required[str]


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

    score: Required[int]

    error: str

    metadata: EventIngestTraceEvalResultsUnionMember3Metadata


class EventIngestTraceEvalResultsUnionMember4Classification(TypedDict, total=False):
    fn: Required[Annotated[SequenceNotStr[str], PropertyInfo(alias="FN")]]
    """False negatives: Statements found in the ground truth but omitted in the answer"""

    fp: Required[Annotated[SequenceNotStr[str], PropertyInfo(alias="FP")]]
    """
    False positives: Statements present in the answer but not found in the ground
    truth
    """

    tp: Required[Annotated[SequenceNotStr[str], PropertyInfo(alias="TP")]]
    """
    True positives: Statements that are present in both the answer and the ground
    truth
    """


class EventIngestTraceEvalResultsUnionMember4(TypedDict, total=False):
    classification: Required[EventIngestTraceEvalResultsUnionMember4Classification]

    score: Required[float]
    """The F1 score of the response based on the fact checker (0-1)"""

    error: str

    metadata: object


class EventIngestTraceEvalResultsUnionMember5Missing(TypedDict, total=False):
    have: Required[float]

    need: Required[float]

    value: Required[str]


class EventIngestTraceEvalResultsUnionMember5(TypedDict, total=False):
    reason: Required[str]

    score: Required[float]

    expected: str

    expected_list: Annotated[SequenceNotStr[str], PropertyInfo(alias="expectedList")]

    f1: float

    got: str

    got_list: Annotated[SequenceNotStr[str], PropertyInfo(alias="gotList")]

    match_mode: Annotated[Literal["exact_unordered", "contains"], PropertyInfo(alias="matchMode")]

    missing: Iterable[EventIngestTraceEvalResultsUnionMember5Missing]

    precision: float

    recall: float

    score_metric: Annotated[Literal["f1", "precision", "recall"], PropertyInfo(alias="scoreMetric")]

    tp: float


EventIngestTraceEvalResults: TypeAlias = Union[
    EventIngestTraceEvalResultsUnionMember0,
    EventIngestTraceEvalResultsUnionMember1,
    EventIngestTraceEvalResultsUnionMember2,
    EventIngestTraceEvalResultsUnionMember3,
    EventIngestTraceEvalResultsUnionMember4,
    EventIngestTraceEvalResultsUnionMember5,
]


class EventIngestTraceEval(TypedDict, total=False):
    """Complete evaluation information"""

    id: Required[str]
    """Unique identifier of the evaluation"""

    created_at: Required[Annotated[Union[str, datetime], PropertyInfo(alias="createdAt", format="iso8601")]]
    """When the evaluation was created"""

    definition: Required[EventIngestTraceEvalDefinition]

    modified_at: Required[Annotated[Union[str, datetime], PropertyInfo(alias="modifiedAt", format="iso8601")]]
    """When the evaluation was last modified"""

    org_id: Required[Annotated[str, PropertyInfo(alias="orgId")]]
    """Organization ID that owns this evaluation"""

    status: Required[Literal["PENDING", "IN_PROGRESS", "COMPLETED", "FAILED"]]
    """Status of the evaluation/test"""

    passed: bool
    """Whether the evaluation passed"""

    results: EventIngestTraceEvalResults
    """Results of the evaluation (structure depends on eval type)."""

    score: float
    """Overall score of the evaluation"""


class EventIngestTraceStepLlmStartStep(TypedDict, total=False):
    """Start of an LLM trace."""

    id: Required[str]
    """UUID for the step."""

    event: Required[Literal["start"]]

    input: Required[str]
    """JSON input for this LLM trace event (e.g., the prompt)."""

    model_id: Required[Annotated[str, PropertyInfo(alias="modelId")]]
    """Model ID or name used for the LLM call."""

    timestamp: Required[Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]]
    """When the step was created"""

    trace_id: Required[Annotated[str, PropertyInfo(alias="traceId")]]
    """UUID referencing the parent trace's ID."""

    type: Required[Literal["llm"]]

    cost_amount: Annotated[float, PropertyInfo(alias="costAmount")]
    """Cost of the step in the configured currency (primarily for LLM steps)"""

    duration_ms: Annotated[int, PropertyInfo(alias="durationMs")]
    """Duration of the step in milliseconds"""

    end_time: Annotated[Union[str, datetime], PropertyInfo(alias="endTime", format="iso8601")]
    """When the step ended (for duration tracking)"""

    error: str
    """Error message or stack trace if the step failed."""

    group: str
    """Optionally, the key for a group step to group the step with."""

    metadata: Union[Dict[str, object], Iterable[object], str]
    """Extra metadata about this trace event.

    String values are parsed as JSON if possible, otherwise wrapped in { raw: val }.
    """

    name: str
    """The name of the step."""

    params: Union[Dict[str, object], Iterable[object], str]
    """Arbitrary params for the step."""

    parent_id: Annotated[str, PropertyInfo(alias="parentId")]
    """Parent step ID for hierarchical span relationships.

    Links this step to its parent in the trace tree.
    """

    status: Literal["success", "error", "timeout", "pending"]
    """Status of the step indicating success or failure. Defaults to 'success'."""

    status_code: Annotated[str, PropertyInfo(alias="statusCode")]
    """
    Status code associated with the step (e.g., HTTP status code for API calls, OTEL
    status code for traced spans).
    """


class EventIngestTraceStepLlmEndStep(TypedDict, total=False):
    """End of an LLM trace."""

    id: Required[str]
    """UUID for the step."""

    event: Required[Literal["end"]]

    model_id: Required[Annotated[str, PropertyInfo(alias="modelId")]]
    """Model ID or name used for the LLM call."""

    timestamp: Required[Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]]
    """When the step was created"""

    trace_id: Required[Annotated[str, PropertyInfo(alias="traceId")]]
    """UUID referencing the parent trace's ID."""

    type: Required[Literal["llm"]]

    cost_amount: Annotated[float, PropertyInfo(alias="costAmount")]
    """Cost of the step in the configured currency (primarily for LLM steps)"""

    duration_ms: Annotated[int, PropertyInfo(alias="durationMs")]
    """Duration of the step in milliseconds"""

    end_time: Annotated[Union[str, datetime], PropertyInfo(alias="endTime", format="iso8601")]
    """When the step ended (for duration tracking)"""

    error: str
    """Error message or stack trace if the step failed."""

    finish_reason: Annotated[str, PropertyInfo(alias="finishReason")]
    """
    The reason the LLM stopped generating, extracted from
    gen_ai.response.finish_reasons.
    """

    group: str
    """Optionally, the key for a group step to group the step with."""

    metadata: Union[Dict[str, object], Iterable[object], str]
    """Extra metadata about this trace event.

    String values are parsed as JSON if possible, otherwise wrapped in { raw: val }.
    """

    name: str
    """The name of the step."""

    output: str
    """JSON describing the output.

    String inputs are parsed or wrapped in { message: val }.
    """

    params: Union[Dict[str, object], Iterable[object], str]
    """Arbitrary params for the step."""

    parent_id: Annotated[str, PropertyInfo(alias="parentId")]
    """Parent step ID for hierarchical span relationships.

    Links this step to its parent in the trace tree.
    """

    status: Literal["success", "error", "timeout", "pending"]
    """Status of the step indicating success or failure. Defaults to 'success'."""

    status_code: Annotated[str, PropertyInfo(alias="statusCode")]
    """
    Status code associated with the step (e.g., HTTP status code for API calls, OTEL
    status code for traced spans).
    """

    usage: UsageParam
    """Number of input and output tokens used by the LLM."""


class EventIngestTraceStepToolStep(TypedDict, total=False):
    """Track all tool calls using the Tool Step event"""

    id: Required[str]
    """UUID for the step."""

    timestamp: Required[Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]]
    """When the step was created"""

    trace_id: Required[Annotated[str, PropertyInfo(alias="traceId")]]
    """UUID referencing the parent trace's ID."""

    type: Required[Literal["tool"]]

    cost_amount: Annotated[float, PropertyInfo(alias="costAmount")]
    """Cost of the step in the configured currency (primarily for LLM steps)"""

    duration_ms: Annotated[int, PropertyInfo(alias="durationMs")]
    """Duration of the step in milliseconds"""

    end_time: Annotated[Union[str, datetime], PropertyInfo(alias="endTime", format="iso8601")]
    """When the step ended (for duration tracking)"""

    error: str
    """Error message or stack trace if the step failed."""

    group: str
    """Optionally, the key for a group step to group the step with."""

    metadata: Union[Dict[str, object], Iterable[object], str]
    """Extra metadata about this trace event.

    String values are parsed as JSON if possible, otherwise wrapped in { raw: val }.
    """

    name: str
    """The name of the step."""

    params: Union[Dict[str, object], Iterable[object], str]
    """Arbitrary params for the step."""

    parent_id: Annotated[str, PropertyInfo(alias="parentId")]
    """Parent step ID for hierarchical span relationships.

    Links this step to its parent in the trace tree.
    """

    status: Literal["success", "error", "timeout", "pending"]
    """Status of the step indicating success or failure. Defaults to 'success'."""

    status_code: Annotated[str, PropertyInfo(alias="statusCode")]
    """
    Status code associated with the step (e.g., HTTP status code for API calls, OTEL
    status code for traced spans).
    """

    tool_call_id: Annotated[str, PropertyInfo(alias="toolCallId")]
    """
    Correlation ID from the LLM's tool_calls response (e.g., OpenAI's call_abc123 or
    Claude's toolu_01A09q). Links tool execution to the originating LLM request in
    parallel tool call scenarios.
    """

    tool_input: Annotated[str, PropertyInfo(alias="toolInput")]
    """JSON input for the tool call."""

    tool_output: Annotated[str, PropertyInfo(alias="toolOutput")]
    """JSON output from the tool call."""


class EventIngestTraceStepRetrieverStep(TypedDict, total=False):
    """Track all retriever (RAG) calls using the Retriever Step event."""

    id: Required[str]
    """UUID for the step."""

    query: Required[str]
    """Query used for RAG."""

    result: Required[str]
    """Retrieved text"""

    timestamp: Required[Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]]
    """When the step was created"""

    trace_id: Required[Annotated[str, PropertyInfo(alias="traceId")]]
    """UUID referencing the parent trace's ID."""

    type: Required[Literal["retriever"]]

    cost_amount: Annotated[float, PropertyInfo(alias="costAmount")]
    """Cost of the step in the configured currency (primarily for LLM steps)"""

    duration_ms: Annotated[int, PropertyInfo(alias="durationMs")]
    """Duration of the step in milliseconds"""

    end_time: Annotated[Union[str, datetime], PropertyInfo(alias="endTime", format="iso8601")]
    """When the step ended (for duration tracking)"""

    error: str
    """Error message or stack trace if the step failed."""

    group: str
    """Optionally, the key for a group step to group the step with."""

    metadata: Union[Dict[str, object], Iterable[object], str]
    """Extra metadata about this trace event.

    String values are parsed as JSON if possible, otherwise wrapped in { raw: val }.
    """

    name: str
    """The name of the step."""

    params: Union[Dict[str, object], Iterable[object], str]
    """Arbitrary params for the step."""

    parent_id: Annotated[str, PropertyInfo(alias="parentId")]
    """Parent step ID for hierarchical span relationships.

    Links this step to its parent in the trace tree.
    """

    status: Literal["success", "error", "timeout", "pending"]
    """Status of the step indicating success or failure. Defaults to 'success'."""

    status_code: Annotated[str, PropertyInfo(alias="statusCode")]
    """
    Status code associated with the step (e.g., HTTP status code for API calls, OTEL
    status code for traced spans).
    """


class EventIngestTraceStepLogStep(TypedDict, total=False):
    """Track all logs using the Log Step event."""

    id: Required[str]
    """UUID for the step."""

    content: Required[str]
    """The actual log message for this trace."""

    timestamp: Required[Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]]
    """When the step was created"""

    trace_id: Required[Annotated[str, PropertyInfo(alias="traceId")]]
    """UUID referencing the parent trace's ID."""

    type: Required[Literal["log"]]

    cost_amount: Annotated[float, PropertyInfo(alias="costAmount")]
    """Cost of the step in the configured currency (primarily for LLM steps)"""

    duration_ms: Annotated[int, PropertyInfo(alias="durationMs")]
    """Duration of the step in milliseconds"""

    end_time: Annotated[Union[str, datetime], PropertyInfo(alias="endTime", format="iso8601")]
    """When the step ended (for duration tracking)"""

    error: str
    """Error message or stack trace if the step failed."""

    group: str
    """Optionally, the key for a group step to group the step with."""

    metadata: Union[Dict[str, object], Iterable[object], str]
    """Extra metadata about this trace event.

    String values are parsed as JSON if possible, otherwise wrapped in { raw: val }.
    """

    name: str
    """The name of the step."""

    params: Union[Dict[str, object], Iterable[object], str]
    """Arbitrary params for the step."""

    parent_id: Annotated[str, PropertyInfo(alias="parentId")]
    """Parent step ID for hierarchical span relationships.

    Links this step to its parent in the trace tree.
    """

    status: Literal["success", "error", "timeout", "pending"]
    """Status of the step indicating success or failure. Defaults to 'success'."""

    status_code: Annotated[str, PropertyInfo(alias="statusCode")]
    """
    Status code associated with the step (e.g., HTTP status code for API calls, OTEL
    status code for traced spans).
    """


class EventIngestTraceStepGroupStep(TypedDict, total=False):
    """
    Use this to group multiple steps together, for example a log, llm start, and llm end.
    """

    id: Required[str]
    """UUID for the step."""

    key: Required[str]
    """
    A unique identifier for the grouping, which must be appended to the
    corresponding steps
    """

    timestamp: Required[Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]]
    """When the step was created"""

    trace_id: Required[Annotated[str, PropertyInfo(alias="traceId")]]
    """UUID referencing the parent trace's ID."""

    type: Required[Literal["group"]]

    cost_amount: Annotated[float, PropertyInfo(alias="costAmount")]
    """Cost of the step in the configured currency (primarily for LLM steps)"""

    duration_ms: Annotated[int, PropertyInfo(alias="durationMs")]
    """Duration of the step in milliseconds"""

    end_time: Annotated[Union[str, datetime], PropertyInfo(alias="endTime", format="iso8601")]
    """When the step ended (for duration tracking)"""

    error: str
    """Error message or stack trace if the step failed."""

    group: str
    """Optionally, the key for a group step to group the step with."""

    metadata: Union[Dict[str, object], Iterable[object], str]
    """Extra metadata about this trace event.

    String values are parsed as JSON if possible, otherwise wrapped in { raw: val }.
    """

    name: str
    """The name of the step."""

    params: Union[Dict[str, object], Iterable[object], str]
    """Arbitrary params for the step."""

    parent_id: Annotated[str, PropertyInfo(alias="parentId")]
    """Parent step ID for hierarchical span relationships.

    Links this step to its parent in the trace tree.
    """

    status: Literal["success", "error", "timeout", "pending"]
    """Status of the step indicating success or failure. Defaults to 'success'."""

    status_code: Annotated[str, PropertyInfo(alias="statusCode")]
    """
    Status code associated with the step (e.g., HTTP status code for API calls, OTEL
    status code for traced spans).
    """


class EventIngestTraceStepResponseStep(TypedDict, total=False):
    """Track AI responses to users using the Response Step event."""

    id: Required[str]
    """UUID for the step."""

    content: Required[str]
    """The response content from the AI to the user."""

    timestamp: Required[Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]]
    """When the step was created"""

    trace_id: Required[Annotated[str, PropertyInfo(alias="traceId")]]
    """UUID referencing the parent trace's ID."""

    type: Required[Literal["response"]]

    cost_amount: Annotated[float, PropertyInfo(alias="costAmount")]
    """Cost of the step in the configured currency (primarily for LLM steps)"""

    duration_ms: Annotated[int, PropertyInfo(alias="durationMs")]
    """Duration of the step in milliseconds"""

    end_time: Annotated[Union[str, datetime], PropertyInfo(alias="endTime", format="iso8601")]
    """When the step ended (for duration tracking)"""

    error: str
    """Error message or stack trace if the step failed."""

    group: str
    """Optionally, the key for a group step to group the step with."""

    metadata: Union[Dict[str, object], Iterable[object], str]
    """Extra metadata about this trace event.

    String values are parsed as JSON if possible, otherwise wrapped in { raw: val }.
    """

    name: str
    """The name of the step."""

    params: Union[Dict[str, object], Iterable[object], str]
    """Arbitrary params for the step."""

    parent_id: Annotated[str, PropertyInfo(alias="parentId")]
    """Parent step ID for hierarchical span relationships.

    Links this step to its parent in the trace tree.
    """

    status: Literal["success", "error", "timeout", "pending"]
    """Status of the step indicating success or failure. Defaults to 'success'."""

    status_code: Annotated[str, PropertyInfo(alias="statusCode")]
    """
    Status code associated with the step (e.g., HTTP status code for API calls, OTEL
    status code for traced spans).
    """


class EventIngestTraceStepRequestStep(TypedDict, total=False):
    """Track user requests to the AI using the Request Step event."""

    id: Required[str]
    """UUID for the step."""

    content: Required[str]
    """The request content from the user to the AI."""

    timestamp: Required[Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]]
    """When the step was created"""

    trace_id: Required[Annotated[str, PropertyInfo(alias="traceId")]]
    """UUID referencing the parent trace's ID."""

    type: Required[Literal["request"]]

    cost_amount: Annotated[float, PropertyInfo(alias="costAmount")]
    """Cost of the step in the configured currency (primarily for LLM steps)"""

    duration_ms: Annotated[int, PropertyInfo(alias="durationMs")]
    """Duration of the step in milliseconds"""

    end_time: Annotated[Union[str, datetime], PropertyInfo(alias="endTime", format="iso8601")]
    """When the step ended (for duration tracking)"""

    error: str
    """Error message or stack trace if the step failed."""

    group: str
    """Optionally, the key for a group step to group the step with."""

    metadata: Union[Dict[str, object], Iterable[object], str]
    """Extra metadata about this trace event.

    String values are parsed as JSON if possible, otherwise wrapped in { raw: val }.
    """

    name: str
    """The name of the step."""

    params: Union[Dict[str, object], Iterable[object], str]
    """Arbitrary params for the step."""

    parent_id: Annotated[str, PropertyInfo(alias="parentId")]
    """Parent step ID for hierarchical span relationships.

    Links this step to its parent in the trace tree.
    """

    status: Literal["success", "error", "timeout", "pending"]
    """Status of the step indicating success or failure. Defaults to 'success'."""

    status_code: Annotated[str, PropertyInfo(alias="statusCode")]
    """
    Status code associated with the step (e.g., HTTP status code for API calls, OTEL
    status code for traced spans).
    """


EventIngestTraceStep: TypeAlias = Union[
    EventIngestTraceStepLlmStartStep,
    EventIngestTraceStepLlmEndStep,
    EventIngestTraceStepToolStep,
    EventIngestTraceStepRetrieverStep,
    EventIngestTraceStepLogStep,
    EventIngestTraceStepGroupStep,
    EventIngestTraceStepResponseStep,
    EventIngestTraceStepRequestStep,
]


class EventIngestTrace(TypedDict, total=False):
    timestamp: Required[Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]]
    """When the trace was created"""

    type: Required[Literal["trace"]]

    evals: Iterable[EventIngestTraceEval]
    """Evaluation results for this trace, joined through the associated test."""

    has_error: Annotated[bool, PropertyInfo(alias="hasError")]
    """Whether any step in this trace has an error status."""

    metadata: Union[str, Dict[str, object], Iterable[object]]
    """Arbitrary metadata for this trace (e.g., userId, source, etc.)."""

    reference_id: Annotated[str, PropertyInfo(alias="referenceId")]
    """
    An optional reference ID to link the trace to an existing conversation or
    interaction in your own database.
    """

    step_count: Annotated[int, PropertyInfo(alias="stepCount")]
    """Total number of steps in this trace."""

    steps: Iterable[EventIngestTraceStep]
    """The steps associated with the trace."""

    test_id: Annotated[str, PropertyInfo(alias="testId")]
    """The associated Test if this was triggered by an Avido eval"""

    total_completion_tokens: Annotated[int, PropertyInfo(alias="totalCompletionTokens")]
    """Total number of completion tokens used across all LLM steps in this trace."""

    total_cost: Annotated[float, PropertyInfo(alias="totalCost")]
    """Total cost of all steps in this trace (sum of step costAmount values)."""

    total_duration_ms: Annotated[int, PropertyInfo(alias="totalDurationMs")]
    """Total duration of the trace in milliseconds (sum of all step durations)."""

    total_prompt_tokens: Annotated[int, PropertyInfo(alias="totalPromptTokens")]
    """Total number of prompt tokens used across all LLM steps in this trace."""

    trace_id: Annotated[str, PropertyInfo(alias="traceId")]
    """Optional trace ID (UUID) for OTEL ingestion.

    If provided and a trace with this ID already exists, the existing trace will be
    reused.
    """


class EventIngestLlmStartStep(TypedDict, total=False):
    event: Required[Literal["start"]]

    input: Required[Union[str, Dict[str, object], Iterable[object]]]
    """The input for the LLM step."""

    model_id: Required[Annotated[str, PropertyInfo(alias="modelId")]]
    """Model ID or name used for the LLM call."""

    timestamp: Required[Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]]
    """When the step was created"""

    type: Required[Literal["llm"]]

    cost_amount: Annotated[float, PropertyInfo(alias="costAmount")]
    """Cost of the step in the configured currency (primarily for LLM steps)"""

    duration_ms: Annotated[int, PropertyInfo(alias="durationMs")]
    """Duration of the step in milliseconds"""

    end_time: Annotated[Union[str, datetime], PropertyInfo(alias="endTime", format="iso8601")]
    """When the step ended (for duration tracking)"""

    error: str
    """Error message or stack trace if the step failed."""

    group: str
    """Optionally, the key for a group step to group the step with."""

    metadata: Union[Dict[str, object], Iterable[object], str]
    """Extra metadata about this trace event.

    String values are parsed as JSON if possible, otherwise wrapped in { raw: val }.
    """

    name: str
    """The name of the step."""

    params: Union[Dict[str, object], Iterable[object], str]
    """Arbitrary params for the step."""

    parent_id: Annotated[str, PropertyInfo(alias="parentId")]
    """Parent step ID for hierarchical span relationships.

    Links this step to its parent in the trace tree.
    """

    status: Literal["success", "error", "timeout", "pending"]
    """Status of the step indicating success or failure. Defaults to 'success'."""

    status_code: Annotated[str, PropertyInfo(alias="statusCode")]
    """
    Status code associated with the step (e.g., HTTP status code for API calls, OTEL
    status code for traced spans).
    """

    trace_id: Annotated[str, PropertyInfo(alias="traceId")]
    """The trace ID (UUID)."""


class EventIngestLlmEndStep(TypedDict, total=False):
    event: Required[Literal["end"]]

    model_id: Required[Annotated[str, PropertyInfo(alias="modelId")]]
    """Model ID or name used for the LLM call."""

    timestamp: Required[Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]]
    """When the step was created"""

    type: Required[Literal["llm"]]

    cost_amount: Annotated[float, PropertyInfo(alias="costAmount")]
    """Cost of the step in the configured currency (primarily for LLM steps)"""

    duration_ms: Annotated[int, PropertyInfo(alias="durationMs")]
    """Duration of the step in milliseconds"""

    end_time: Annotated[Union[str, datetime], PropertyInfo(alias="endTime", format="iso8601")]
    """When the step ended (for duration tracking)"""

    error: str
    """Error message or stack trace if the step failed."""

    finish_reason: Annotated[str, PropertyInfo(alias="finishReason")]
    """
    The reason the LLM stopped generating, extracted from
    gen_ai.response.finish_reasons.
    """

    group: str
    """Optionally, the key for a group step to group the step with."""

    metadata: Union[Dict[str, object], Iterable[object], str]
    """Extra metadata about this trace event.

    String values are parsed as JSON if possible, otherwise wrapped in { raw: val }.
    """

    name: str
    """The name of the step."""

    output: Union[str, Dict[str, object], Iterable[object]]
    """The output for the LLM step."""

    params: Union[Dict[str, object], Iterable[object], str]
    """Arbitrary params for the step."""

    parent_id: Annotated[str, PropertyInfo(alias="parentId")]
    """Parent step ID for hierarchical span relationships.

    Links this step to its parent in the trace tree.
    """

    status: Literal["success", "error", "timeout", "pending"]
    """Status of the step indicating success or failure. Defaults to 'success'."""

    status_code: Annotated[str, PropertyInfo(alias="statusCode")]
    """
    Status code associated with the step (e.g., HTTP status code for API calls, OTEL
    status code for traced spans).
    """

    trace_id: Annotated[str, PropertyInfo(alias="traceId")]
    """The trace ID (UUID)."""

    usage: UsageParam
    """Number of input and output tokens used by the LLM."""


class EventIngestToolStep(TypedDict, total=False):
    timestamp: Required[Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]]
    """When the step was created"""

    type: Required[Literal["tool"]]

    cost_amount: Annotated[float, PropertyInfo(alias="costAmount")]
    """Cost of the step in the configured currency (primarily for LLM steps)"""

    duration_ms: Annotated[int, PropertyInfo(alias="durationMs")]
    """Duration of the step in milliseconds"""

    end_time: Annotated[Union[str, datetime], PropertyInfo(alias="endTime", format="iso8601")]
    """When the step ended (for duration tracking)"""

    error: str
    """Error message or stack trace if the step failed."""

    group: str
    """Optionally, the key for a group step to group the step with."""

    metadata: Union[Dict[str, object], Iterable[object], str]
    """Extra metadata about this trace event.

    String values are parsed as JSON if possible, otherwise wrapped in { raw: val }.
    """

    name: str
    """The name of the step."""

    params: Union[Dict[str, object], Iterable[object], str]
    """Arbitrary params for the step."""

    parent_id: Annotated[str, PropertyInfo(alias="parentId")]
    """Parent step ID for hierarchical span relationships.

    Links this step to its parent in the trace tree.
    """

    status: Literal["success", "error", "timeout", "pending"]
    """Status of the step indicating success or failure. Defaults to 'success'."""

    status_code: Annotated[str, PropertyInfo(alias="statusCode")]
    """
    Status code associated with the step (e.g., HTTP status code for API calls, OTEL
    status code for traced spans).
    """

    tool_call_id: Annotated[str, PropertyInfo(alias="toolCallId")]
    """
    Correlation ID from the LLM's tool_calls response (e.g., OpenAI's call_abc123 or
    Claude's toolu_01A09q). Links tool execution to the originating LLM request in
    parallel tool call scenarios.
    """

    tool_input: Annotated[Union[str, Dict[str, object], Iterable[object]], PropertyInfo(alias="toolInput")]
    """The input for the tool step."""

    tool_output: Annotated[Union[str, Dict[str, object], Iterable[object]], PropertyInfo(alias="toolOutput")]
    """The output for the tool step."""

    trace_id: Annotated[str, PropertyInfo(alias="traceId")]
    """The trace ID (UUID)."""


class EventIngestRetrieverStep(TypedDict, total=False):
    query: Required[Union[str, Dict[str, object], Iterable[object]]]
    """The query for the retriever step."""

    result: Required[Union[str, Dict[str, object], Iterable[object]]]
    """The result for the retriever step."""

    timestamp: Required[Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]]
    """When the step was created"""

    type: Required[Literal["retriever"]]

    cost_amount: Annotated[float, PropertyInfo(alias="costAmount")]
    """Cost of the step in the configured currency (primarily for LLM steps)"""

    duration_ms: Annotated[int, PropertyInfo(alias="durationMs")]
    """Duration of the step in milliseconds"""

    end_time: Annotated[Union[str, datetime], PropertyInfo(alias="endTime", format="iso8601")]
    """When the step ended (for duration tracking)"""

    error: str
    """Error message or stack trace if the step failed."""

    group: str
    """Optionally, the key for a group step to group the step with."""

    metadata: Union[Dict[str, object], Iterable[object], str]
    """Extra metadata about this trace event.

    String values are parsed as JSON if possible, otherwise wrapped in { raw: val }.
    """

    name: str
    """The name of the step."""

    params: Union[str, Dict[str, object], Iterable[object]]
    """Arbitrary params for the step."""

    parent_id: Annotated[str, PropertyInfo(alias="parentId")]
    """Parent step ID for hierarchical span relationships.

    Links this step to its parent in the trace tree.
    """

    status: Literal["success", "error", "timeout", "pending"]
    """Status of the step indicating success or failure. Defaults to 'success'."""

    status_code: Annotated[str, PropertyInfo(alias="statusCode")]
    """
    Status code associated with the step (e.g., HTTP status code for API calls, OTEL
    status code for traced spans).
    """

    trace_id: Annotated[str, PropertyInfo(alias="traceId")]
    """The trace ID (UUID)."""


class EventIngestLogStep(TypedDict, total=False):
    content: Required[str]
    """The actual log message for this trace."""

    timestamp: Required[Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]]
    """When the step was created"""

    type: Required[Literal["log"]]

    cost_amount: Annotated[float, PropertyInfo(alias="costAmount")]
    """Cost of the step in the configured currency (primarily for LLM steps)"""

    duration_ms: Annotated[int, PropertyInfo(alias="durationMs")]
    """Duration of the step in milliseconds"""

    end_time: Annotated[Union[str, datetime], PropertyInfo(alias="endTime", format="iso8601")]
    """When the step ended (for duration tracking)"""

    error: str
    """Error message or stack trace if the step failed."""

    group: str
    """Optionally, the key for a group step to group the step with."""

    metadata: Union[Dict[str, object], Iterable[object], str]
    """Extra metadata about this trace event.

    String values are parsed as JSON if possible, otherwise wrapped in { raw: val }.
    """

    name: str
    """The name of the step."""

    params: Union[Dict[str, object], Iterable[object], str]
    """Arbitrary params for the step."""

    parent_id: Annotated[str, PropertyInfo(alias="parentId")]
    """Parent step ID for hierarchical span relationships.

    Links this step to its parent in the trace tree.
    """

    status: Literal["success", "error", "timeout", "pending"]
    """Status of the step indicating success or failure. Defaults to 'success'."""

    status_code: Annotated[str, PropertyInfo(alias="statusCode")]
    """
    Status code associated with the step (e.g., HTTP status code for API calls, OTEL
    status code for traced spans).
    """

    trace_id: Annotated[str, PropertyInfo(alias="traceId")]
    """The trace ID (UUID)."""


class EventIngestGroupStep(TypedDict, total=False):
    key: Required[str]
    """
    A unique identifier for the grouping, which must be appended to the
    corresponding steps
    """

    timestamp: Required[Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]]
    """When the step was created"""

    type: Required[Literal["group"]]

    cost_amount: Annotated[float, PropertyInfo(alias="costAmount")]
    """Cost of the step in the configured currency (primarily for LLM steps)"""

    duration_ms: Annotated[int, PropertyInfo(alias="durationMs")]
    """Duration of the step in milliseconds"""

    end_time: Annotated[Union[str, datetime], PropertyInfo(alias="endTime", format="iso8601")]
    """When the step ended (for duration tracking)"""

    error: str
    """Error message or stack trace if the step failed."""

    group: str
    """Optionally, the key for a group step to group the step with."""

    metadata: Union[Dict[str, object], Iterable[object], str]
    """Extra metadata about this trace event.

    String values are parsed as JSON if possible, otherwise wrapped in { raw: val }.
    """

    name: str
    """The name of the step."""

    params: Union[Dict[str, object], Iterable[object], str]
    """Arbitrary params for the step."""

    parent_id: Annotated[str, PropertyInfo(alias="parentId")]
    """Parent step ID for hierarchical span relationships.

    Links this step to its parent in the trace tree.
    """

    status: Literal["success", "error", "timeout", "pending"]
    """Status of the step indicating success or failure. Defaults to 'success'."""

    status_code: Annotated[str, PropertyInfo(alias="statusCode")]
    """
    Status code associated with the step (e.g., HTTP status code for API calls, OTEL
    status code for traced spans).
    """

    trace_id: Annotated[str, PropertyInfo(alias="traceId")]
    """The trace ID (UUID)."""


class EventIngestResponseStep(TypedDict, total=False):
    content: Required[Union[str, Dict[str, object], Iterable[object]]]
    """The response content from the AI to the user."""

    timestamp: Required[Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]]
    """When the step was created"""

    type: Required[Literal["response"]]

    cost_amount: Annotated[float, PropertyInfo(alias="costAmount")]
    """Cost of the step in the configured currency (primarily for LLM steps)"""

    duration_ms: Annotated[int, PropertyInfo(alias="durationMs")]
    """Duration of the step in milliseconds"""

    end_time: Annotated[Union[str, datetime], PropertyInfo(alias="endTime", format="iso8601")]
    """When the step ended (for duration tracking)"""

    error: str
    """Error message or stack trace if the step failed."""

    group: str
    """Optionally, the key for a group step to group the step with."""

    metadata: Union[Dict[str, object], Iterable[object], str]
    """Extra metadata about this trace event.

    String values are parsed as JSON if possible, otherwise wrapped in { raw: val }.
    """

    name: str
    """The name of the step."""

    params: Union[Dict[str, object], Iterable[object], str]
    """Arbitrary params for the step."""

    parent_id: Annotated[str, PropertyInfo(alias="parentId")]
    """Parent step ID for hierarchical span relationships.

    Links this step to its parent in the trace tree.
    """

    status: Literal["success", "error", "timeout", "pending"]
    """Status of the step indicating success or failure. Defaults to 'success'."""

    status_code: Annotated[str, PropertyInfo(alias="statusCode")]
    """
    Status code associated with the step (e.g., HTTP status code for API calls, OTEL
    status code for traced spans).
    """

    trace_id: Annotated[str, PropertyInfo(alias="traceId")]
    """The trace ID (UUID)."""


class EventIngestRequestStep(TypedDict, total=False):
    content: Required[Union[str, Dict[str, object], Iterable[object]]]
    """The request content from the user to the AI."""

    timestamp: Required[Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]]
    """When the step was created"""

    type: Required[Literal["request"]]

    cost_amount: Annotated[float, PropertyInfo(alias="costAmount")]
    """Cost of the step in the configured currency (primarily for LLM steps)"""

    duration_ms: Annotated[int, PropertyInfo(alias="durationMs")]
    """Duration of the step in milliseconds"""

    end_time: Annotated[Union[str, datetime], PropertyInfo(alias="endTime", format="iso8601")]
    """When the step ended (for duration tracking)"""

    error: str
    """Error message or stack trace if the step failed."""

    group: str
    """Optionally, the key for a group step to group the step with."""

    metadata: Union[Dict[str, object], Iterable[object], str]
    """Extra metadata about this trace event.

    String values are parsed as JSON if possible, otherwise wrapped in { raw: val }.
    """

    name: str
    """The name of the step."""

    params: Union[Dict[str, object], Iterable[object], str]
    """Arbitrary params for the step."""

    parent_id: Annotated[str, PropertyInfo(alias="parentId")]
    """Parent step ID for hierarchical span relationships.

    Links this step to its parent in the trace tree.
    """

    status: Literal["success", "error", "timeout", "pending"]
    """Status of the step indicating success or failure. Defaults to 'success'."""

    status_code: Annotated[str, PropertyInfo(alias="statusCode")]
    """
    Status code associated with the step (e.g., HTTP status code for API calls, OTEL
    status code for traced spans).
    """

    trace_id: Annotated[str, PropertyInfo(alias="traceId")]
    """The trace ID (UUID)."""


Event: TypeAlias = Union[
    EventIngestTrace,
    EventIngestLlmStartStep,
    EventIngestLlmEndStep,
    EventIngestToolStep,
    EventIngestRetrieverStep,
    EventIngestLogStep,
    EventIngestGroupStep,
    EventIngestResponseStep,
    EventIngestRequestStep,
]
