models/responses.py

"""Pydantic response models returned by FastAPI routes.

Shared shape: :class:`SourceCitation` appears on ask, summarise, and audit detail responses.
"""

from datetime import datetime

from pydantic import BaseModel, Field


# --- Shared citations (spec-shaped) ---


class SourceCitation(BaseModel):
    document_name: str
    page_number: int
    chunk_text: str
    relevance_score: float


# --- Query: ask ---


class AskQueryResponse(BaseModel):
    query_id: str
    question: str
    answer: str
    sources: list[SourceCitation] = Field(default_factory=list)
    model_used: str
    tokens_used: int
    response_time_ms: int
    timestamp: datetime


# --- Query: summarise ---


class SummariseQueryResponse(BaseModel):
    query_id: str
    summary: str
    document_count: int
    sources: list[SourceCitation] = Field(default_factory=list)
    timestamp: datetime


# --- Ingest ---


class IngestUploadResponse(BaseModel):
    job_id: str
    status: str
    total_files: int
    filenames: list[str]
    message: str


class UrlIngestResponse(BaseModel):
    job_id: str
    status: str
    total_urls: int
    message: str


class CollectionItem(BaseModel):
    name: str
    document_count: int
    created_at: datetime | None = None


class IngestCollectionsResponse(BaseModel):
    collections: list[CollectionItem] = Field(default_factory=list)
    total: int


class IngestDeleteCollectionResponse(BaseModel):
    message: str
    documents_removed: int


# --- Jobs ---


class JobStatusResponse(BaseModel):
    job_id: str
    status: str
    total_files: int
    processed_files: int
    failed_files: int
    progress_percent: int
    started_at: datetime | None
    completed_at: datetime | None
    errors: list[str] = Field(default_factory=list)


class JobListItem(BaseModel):
    job_id: str
    status: str
    total_files: int
    completed_at: datetime | None = None


class JobListResponse(BaseModel):
    jobs: list[JobListItem] = Field(default_factory=list)
    total: int


# --- Audit ---


class AuditLogEntry(BaseModel):
    query_id: str
    user_id: str
    question: str
    answer_summary: str
    sources_count: int
    model_used: str | None
    timestamp: datetime


class AuditLogsResponse(BaseModel):
    logs: list[AuditLogEntry] = Field(default_factory=list)
    total: int
    limit: int
    offset: int


class AuditLogDetailResponse(BaseModel):
    query_id: str
    user_id: str
    question: str
    full_answer: str
    sources: list[SourceCitation] = Field(default_factory=list)
    model_used: str | None
    tokens_used: int | None
    timestamp: datetime