from typing import Optional, Any, Dict
from pydantic import BaseModel, Field

class StandardError(BaseModel):
    """
    Standardized machine-readable error structure for Aether.
    Helps the frontend decide how to handle failures.
    """
    category: str = Field(..., description="Error category (e.g., 'database', 'validation', 'security')")
    code: Optional[int] = Field(None, description="Specific error code (e.g., MariaDB error code)")
    message: str = Field(..., description="Developer-friendly error message")
    recoverable: bool = Field(False, description="If True, the frontend might want to retry or ask for user input")
    details: Optional[Any] = Field(None, description="Raw technical details or traceback (if permitted)")

    class Config:
        schema_extra = {
            "example": {
                "category": "database",
                "code": 1062,
                "message": "Duplicate entry for key 'id_random'",
                "recoverable": False
            }
        }