""" api/schemas.py — Sentinel-AI ================================ Pydantic v2 request and response models for all API endpoints. """ from __future__ import annotations from typing import Any, Optional from pydantic import BaseModel, Field # ───────────────────────────────────────────────────────────────────────────── # Shared sub-models # ───────────────────────────────────────────────────────────────────────────── class CascadeflowMetrics(BaseModel): latency_ms: float = Field(..., description="Wall-clock time of the agent call in milliseconds") cost_usd: float = Field(..., description="Estimated LLM API cost in USD for this call") # ───────────────────────────────────────────────────────────────────────────── # POST /api/v1/analyze-frame # ───────────────────────────────────────────────────────────────────────────── class AnalyzeFrameResponse(BaseModel): status: str = Field("success") faces_detected: int = Field(..., ge=0) match_confidence: Optional[float] = Field(None, ge=0.0, le=1.0) matched_attributes: list[str] = Field(default_factory=list) agent_report: Optional[str] = Field(None) cascadeflow_metrics: Optional[CascadeflowMetrics] = Field(None) model_config = {"json_schema_extra": { "example": { "status": "success", "faces_detected": 1, "match_confidence": 0.92, "matched_attributes": ["Male", "Eyeglasses", "Black_Hair"], "agent_report": ( "Alert: Suspect matched with 92.0% confidence. " "Subject is an adult male with black hair and eyeglasses. " "Recommend secondary verification." ), "cascadeflow_metrics": {"latency_ms": 1240, "cost_usd": 0.0001}, } }} # ───────────────────────────────────────────────────────────────────────────── # POST /api/v1/semantic-search # ───────────────────────────────────────────────────────────────────────────── class SemanticSearchRequest(BaseModel): query: str = Field(..., min_length=3, description="Natural-language description of the suspect") top_k: int = Field(10, ge=1, le=100, description="Maximum number of results to return") model_config = {"json_schema_extra": { "example": {"query": "young male with wavy hair and eyeglasses", "top_k": 10} }} class SemanticSearchMatch(BaseModel): image_id: str attributes: list[str] faiss_id: int class SemanticSearchResponse(BaseModel): status: str query: str extracted_attrs: list[str] excluded_attrs: list[str] = Field(default_factory=list) matches: list[SemanticSearchMatch] cascadeflow_metrics: Optional[CascadeflowMetrics] = None model_config = {"json_schema_extra": { "example": { "status": "success", "query": "young male with wavy hair and eyeglasses", "extracted_attrs": ["Young", "Male", "Wavy_Hair", "Eyeglasses"], "excluded_attrs": [], "matches": [ {"image_id": "012345.jpg", "attributes": ["Young", "Male", "Wavy_Hair", "Eyeglasses"], "faiss_id": 12345} ], "cascadeflow_metrics": {"latency_ms": 890, "cost_usd": 0.00005}, } }} # ───────────────────────────────────────────────────────────────────────────── # POST /api/v1/generate-person # ───────────────────────────────────────────────────────────────────────────── class GeneratePersonRequest(BaseModel): prompt: str = Field(..., min_length=3, description="Natural-language description of the person to generate") save_to_disk: bool = Field(False, description="Whether to save the generated image to disk") model_config = {"json_schema_extra": { "example": { "prompt": "a young woman with curly brown hair and glasses, smiling", "save_to_disk": False } }} class GeneratePersonResponse(BaseModel): status: str = Field(..., description="success or error") prompt: str = Field(..., description="Original prompt provided by user") enhanced_prompt: str = Field("", description="Enhanced prompt sent to the image model") image_base64: str = Field("", description="Base64-encoded JPEG image data") file_path: Optional[str] = Field(None, description="Path to saved file if save_to_disk=True") width: Optional[int] = Field(None, description="Image width in pixels") height: Optional[int] = Field(None, description="Image height in pixels") error: Optional[str] = Field(None, description="Error message if generation failed") cascadeflow_metrics: CascadeflowMetrics model_config = {"json_schema_extra": { "example": { "status": "success", "prompt": "a young woman with curly brown hair and glasses, smiling", "enhanced_prompt": "Professional high-quality portrait photograph of a young woman...", "image_base64": "/9j/4AAQSkZJRgABAQEA...", "file_path": "uploads/generated_1704123456.jpg", "width": 1024, "height": 1024, "cascadeflow_metrics": {"latency_ms": 3200, "cost_usd": 0.067} } }} # ───────────────────────────────────────────────────────────────────────────── # Health check # ───────────────────────────────────────────────────────────────────────────── class HealthResponse(BaseModel): status: str = "ok" index_ready: bool index_vectors: Optional[int] = None detector_ready: bool = False embedder_ready: bool = False model: str