"""AI Response Schema - Defines the structure for AI explanations."""

from typing import List, Dict, Any, Literal
from pydantic import BaseModel, Field


Urgency = Literal["high", "medium", "low"]


class IssueExplanation(BaseModel):
    """Schema for a single issue explanation."""
    
    name: str = Field(..., description="Short name of the issue")
    urgency: Urgency = Field(..., description="Urgency level: high, medium, or low")
    explanation: str = Field(..., description="Plain English explanation of what's happening")
    likely_causes: List[str] = Field(
        default_factory=list,
        description="List of likely causes, ranked by probability"
    )
    recommendations: List[str] = Field(
        default_factory=list,
        description="List of safe, manual recommendations (no commands or scripts)"
    )
    confidence: float = Field(
        ...,
        ge=0.0,
        le=1.0,
        description="Confidence level from 0.0 to 1.0"
    )


class DiagnosticReport(BaseModel):
    """Schema for the complete diagnostic report."""
    
    summary: str = Field(
        ...,
        description="Brief summary of system health status"
    )
    issues: List[IssueExplanation] = Field(
        default_factory=list,
        description="List of detected issues with explanations"
    )
    not_checked: List[str] = Field(
        default_factory=list,
        description="List of things that were not checked (for transparency)"
    )


def validate_report(data: Dict[str, Any]) -> DiagnosticReport:
    """
    Validate and parse diagnostic report data.
    
    Args:
        data: Dictionary containing report data.
        
    Returns:
        Validated DiagnosticReport instance.
        
    Raises:
        ValidationError: If data doesn't match schema.
    """
    return DiagnosticReport(**data)
