app/models/response.py

"""
Response models for VoiceAuth API.

Defines Pydantic models for API responses.

PHASE 1 ENHANCED: Includes Risk Score, Quality Score, Temporal Analysis.
"""

from typing import Annotated
from typing import Any
from typing import Literal
from typing import Optional

from pydantic import BaseModel
from pydantic import ConfigDict
from pydantic import Field

from app.models.enums import Classification


class VoiceDetectionResponse(BaseModel):
    """
    Successful voice detection response.

    Contains classification result, confidence score, explanation,
    and comprehensive analysis data.
    
    PHASE 1 FEATURES:
    - deepfakeRiskScore: Business-friendly risk rating
    - audioQuality: Input quality assessment
    - temporalAnalysis: Breathing, pauses, rhythm analysis
    - audioForensics: Spectral and energy analysis
    - performanceMetrics: Processing time breakdown
    """

    model_config = ConfigDict(
        json_schema_extra={
            "example": {
                "status": "success",
                "language": "Tamil",
                "classification": "AI_GENERATED",
                "confidenceScore": 0.91,
                "explanation": "Strong evidence of AI-generated speech: absence of natural breathing sounds and mechanically consistent pause patterns detected",
                "deepfakeRiskScore": {
                    "score": 87,
                    "level": "HIGH",
                    "recommendation": "Manual review required before approval",
                },
                "audioQuality": {
                    "score": 85,
                    "rating": "GOOD",
                    "reliability": "High confidence in detection results",
                },
                "temporalAnalysis": {
                    "breathingDetected": False,
                    "breathingNaturalness": 0.0,
                    "pauseMechanicalScore": 0.78,
                    "rhythmConsistency": 0.85,
                    "anomalyScore": 0.72,
                    "verdict": "HIGH_ANOMALY",
                },
                "audioForensics": {
                    "spectralCentroid": 1523.45,
                    "pitchStability": 0.89,
                    "jitter": 0.0021,
                    "energyConsistency": 0.92,
                    "silenceRatio": 0.08,
                    "aiLikelihood": 0.76,
                },
                "performanceMetrics": {
                    "audioProcessingMs": 45.23,
                    "forensicsAnalysisMs": 12.87,
                    "temporalAnalysisMs": 8.45,
                    "modelInferenceMs": 127.45,
                    "totalProcessingMs": 193.00,
                },
            }
        }
    )

    status: Annotated[
        Literal["success"],
        Field(description="Response status, always 'success' for successful detections"),
    ] = "success"

    language: Annotated[
        str,
        Field(description="Language of the analyzed audio"),
    ]

    classification: Annotated[
        Classification,
        Field(description="Classification result: AI_GENERATED or HUMAN"),
    ]

    confidenceScore: Annotated[
        float,
        Field(
            ge=0.0,
            le=1.0,
            description="Calibrated confidence score between 0.0 and 1.0",
        ),
    ]

    explanation: Annotated[
        str,
        Field(
            max_length=250,
            description="Human-readable explanation based on comprehensive analysis",
        ),
    ]

    # NEW: Deepfake Risk Score
    deepfakeRiskScore: Annotated[
        Optional[dict[str, Any]],
        Field(
            default=None,
            description="Business-friendly risk score (0-100) with level and recommendation",
        ),
    ] = None

    # NEW: Audio Quality Score
    audioQuality: Annotated[
        Optional[dict[str, Any]],
        Field(
            default=None,
            description="Input audio quality assessment affecting detection reliability",
        ),
    ] = None

    # NEW: Temporal Analysis
    temporalAnalysis: Annotated[
        Optional[dict[str, Any]],
        Field(
            default=None,
            description="Temporal anomaly analysis (breathing, pauses, rhythm)",
        ),
    ] = None

    # Audio Forensics
    audioForensics: Annotated[
        Optional[dict[str, float]],
        Field(
            default=None,
            description="Detailed audio forensics analysis metrics",
        ),
    ] = None

    # Performance Metrics
    performanceMetrics: Annotated[
        Optional[dict[str, float]],
        Field(
            default=None,
            description="Performance timing breakdown",
        ),
    ] = None


class ErrorResponse(BaseModel):
    """
    Error response model.

    Returned when the API encounters an error.
    """

    model_config = ConfigDict(
        json_schema_extra={
            "example": {
                "status": "error",
                "message": "Invalid API key or malformed request",
            }
        }
    )

    status: Annotated[
        Literal["error"],
        Field(description="Response status, always 'error' for error responses"),
    ] = "error"

    message: Annotated[
        str,
        Field(description="Human-readable error message"),
    ]

    details: Annotated[
        Optional[dict[str, Any]],
        Field(default=None, description="Additional error details if available"),
    ] = None


class HealthResponse(BaseModel):
    """
    Health check response model.

    Returned by health check endpoints.
    """

    model_config = ConfigDict(
        json_schema_extra={
            "example": {
                "status": "healthy",
                "version": "1.0.0",
                "model_loaded": True,
                "model_name": "facebook/wav2vec2-base",
                "device": "cuda",
                "supported_languages": ["Tamil", "English", "Hindi", "Malayalam", "Telugu"],
                "features": [
                    "audio_forensics",
                    "temporal_anomaly_detection",
                    "deepfake_risk_score",
                    "audio_quality_score",
                ],
            }
        }
    )

    status: Annotated[
        str,
        Field(description="Health status: 'healthy' or 'unhealthy'"),
    ]

    version: Annotated[
        str,
        Field(description="API version"),
    ]

    model_loaded: Annotated[
        bool,
        Field(description="Whether the ML model is loaded and ready"),
    ]

    model_name: Annotated[
        Optional[str],
        Field(default=None, description="Name of the loaded model"),
    ] = None

    device: Annotated[
        Optional[str],
        Field(default=None, description="Device used for inference (cpu/cuda)"),
    ] = None

    supported_languages: Annotated[
        list[str],
        Field(description="List of supported languages"),
    ]

    features: Annotated[
        Optional[list[str]],
        Field(default=None, description="List of enabled features"),
    ] = None


class LanguagesResponse(BaseModel):
    """Response model for supported languages endpoint."""

    languages: Annotated[
        list[str],
        Field(description="List of supported language names"),
    ]

    count: Annotated[
        int,
        Field(description="Number of supported languages"),
    ]