schemas.py

"""Pydantic schemas for request and response models."""

from typing import Any, Optional

from pydantic import BaseModel, Field


# Request Schemas
class VerifyRequest(BaseModel):
    """Request schema for face verification."""

    img1: str = Field(..., description="First image as base64 string or file path")
    img2: str = Field(..., description="Second image as base64 string or file path")
    model_name: Optional[str] = Field(None, description="Face recognition model to use")
    detector_backend: Optional[str] = Field(None, description="Detector backend to use")
    distance_metric: Optional[str] = Field(None, description="Distance metric to use")
    enforce_detection: bool = Field(True, description="Raise error if no face detected")


class AnalyzeRequest(BaseModel):
    """Request schema for facial analysis."""

    img: str = Field(..., description="Image as base64 string or file path")
    actions: list[str] = Field(
        default=["age", "gender", "race", "emotion"],
        description="Analysis actions to perform",
    )
    detector_backend: Optional[str] = Field(None, description="Detector backend to use")
    enforce_detection: bool = Field(True, description="Raise error if no face detected")


class EmbedRequest(BaseModel):
    """Request schema for face embedding generation."""

    img: str = Field(..., description="Image as base64 string or file path")
    model_name: Optional[str] = Field(None, description="Face recognition model to use")
    detector_backend: Optional[str] = Field(None, description="Detector backend to use")
    enforce_detection: bool = Field(True, description="Raise error if no face detected")


class RecognizeRequest(BaseModel):
    """Request schema for face recognition."""

    img: str = Field(..., description="Image as base64 string or file path")
    person_id: Optional[str] = Field(None, description="Specific person to match against")
    threshold: Optional[float] = Field(None, description="Custom similarity threshold")
    model_name: Optional[str] = Field(None, description="Face recognition model to use")
    detector_backend: Optional[str] = Field(None, description="Detector backend to use")


class StoreFaceRequest(BaseModel):
    """Request schema for storing face embeddings."""

    person_id: str = Field(..., description="Unique identifier for the person")
    img: str = Field(..., description="Image as base64 string or file path")
    metadata: Optional[dict[str, Any]] = Field(None, description="Additional metadata")
    model_name: Optional[str] = Field(None, description="Face recognition model to use")
    detector_backend: Optional[str] = Field(None, description="Detector backend to use")


# Response Schemas
class VerifyResponse(BaseModel):
    """Response schema for face verification."""

    verified: bool = Field(..., description="Whether faces match")
    distance: float = Field(..., description="Distance between faces")
    threshold: float = Field(..., description="Threshold used")
    model: str = Field(..., description="Model used")
    detector_backend: str = Field(..., description="Detector backend used")
    distance_metric: str = Field(..., description="Distance metric used")
    facial_areas: dict[str, Any] = Field(..., description="Detected facial areas")


class AnalyzeResponse(BaseModel):
    """Response schema for facial analysis."""

    results: list[dict[str, Any]] = Field(..., description="Analysis results for each face detected")
    detector_backend: str = Field(..., description="Detector backend used")


class EmbedResponse(BaseModel):
    """Response schema for face embedding."""

    embedding: list[float] = Field(..., description="Face embedding vector")
    facial_area: dict[str, Any] = Field(..., description="Detected facial area")
    model: str = Field(..., description="Model used")
    detector_backend: str = Field(..., description="Detector backend used")


class RecognizeResponse(BaseModel):
    """Response schema for face recognition."""

    matches: list[dict[str, Any]] = Field(..., description="Matching faces from database")
    total_matches: int = Field(..., description="Total number of matches found")
    query_embedding: Optional[list[float]] = Field(None, description="Query face embedding")


class StoreFaceResponse(BaseModel):
    """Response schema for storing face embeddings."""

    id: int = Field(..., description="Database record ID")
    person_id: str = Field(..., description="Person identifier")
    message: str = Field(..., description="Success message")


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

    error: str = Field(..., description="Error type")
    message: str = Field(..., description="Error message")
    details: Optional[dict[str, Any]] = Field(None, description="Additional error details")