"""Pydantic models for the SafeClaw FastAPI gateway.

Covers request/response schemas for /query endpoint
including the user confirmation flow for Grok fallback.
"""

from typing import List, Optional, Literal

from pydantic import BaseModel, Field


class QueryRequest(BaseModel):
    """Inbound query to the SafeClaw gateway."""
    query: str = Field(..., min_length=1, max_length=4000)
    mode: Optional[Literal["auto", "semantic", "keyword", "hybrid"]] = "auto"
    user_confirmed_online: Optional[bool] = None  # For Grok gate confirmation flow


class SourceInfo(BaseModel):
    """Provenance metadata for a single retrieved chunk."""
    source: str
    score: float
    chunk_id: int
    stem_tags: List[str] = Field(default_factory=list)


class QueryResponse(BaseModel):
    """Response from the SafeClaw gateway."""
    answer: str
    sources: List[SourceInfo] = Field(default_factory=list)
    retrieval_mode: str = "hybrid"
    hit_count: int = 0
    model_used: str = "local"
    needs_confirm: bool = False
    confirm_message: Optional[str] = None
    error: Optional[str] = None


class ErrorResponse(BaseModel):
    """Structured error response."""
    error: str
    code: str
    details: Optional[dict] = None


class HealthResponse(BaseModel):
    """Health check response."""
    status: str
    mode: str
    dependencies: List[dict] = Field(default_factory=list)