from pydantic import BaseModel


class FaceDetection(BaseModel):
    """A single detected and (optionally) recognized face in a frame.

    Returned as part of the WebSocket JSON response array.

    Args:
        identity: Gallery name of the recognized face, or None if unknown.
        confidence: Face recognition match score from gallery cosine similarity
                    (not the detector confidence). 0.0 when identity is unknown.
        bbox: Bounding box in [x1, y1, x2, y2] pixel coordinates (top-left, bottom-right).
    """

    identity: str | None
    confidence: float
    bbox: list[float]


class InferenceResponse(BaseModel):
    """WebSocket response for a single frame.

    Serialized as JSON and sent back over the WebSocket connection.
    """

    timestamp: float
    detections: list[FaceDetection]