from pydantic import BaseModel, Field
from typing import List, Optional, Literal
from .content_reference import ContentReference
import uuid

# Predefined risk types derived from "Who & When" taxonomy (simplified)
RiskType = Literal[
    "AGENT_ERROR",       # incorrect reasoning or knowledge within an agent
    "PLANNING_ERROR",    # wrong high-level plan or task breakdown
    "EXECUTION_ERROR",   # tool call / code execution failure
    "RETRIEVAL_ERROR",   # failed to fetch needed information
    "HALLUCINATION",     # fabricated content or invalid assumption
]

class Failure(BaseModel):
    """Represents a failure / risk event located via ContentReference."""

    id: str = Field(default_factory=lambda: str(uuid.uuid4()), description="Unique identifier for the failure event")
    risk_type: RiskType = Field(..., description="Categorised failure type (predefined list)")
    description: str = Field(..., description="One-sentence explanation of the failure")
    raw_text: str = Field("", description="Exact snippet of trace text that evidences the failure (can be left blank and recovered via raw_text_ref)")
    raw_text_ref: List[ContentReference] = Field(..., description="List of references to every occurrence of the failure evidence in the trace")
    affected_id: str = Field(..., description="ID of related Entity or Relation responsible for or impacted by the failure")