"""Public API schemas for the copilot and plugin endpoint."""

from __future__ import annotations

from typing import Literal

from pydantic import BaseModel, Field, field_validator


Mode = Literal["brainstorm", "critique", "balance", "level_design", "gm_session"]


class ChatRequest(BaseModel):
    """Plugin-facing chat request."""

    message: str = Field(..., min_length=1, max_length=8000)
    project_context: str = Field(default="", max_length=12000)
    mode: Mode = "brainstorm"
    retrieval_k: int = Field(default=4, ge=0, le=10)

    @field_validator("message", "project_context", mode="before")
    @classmethod
    def normalize_text(cls, value: object) -> str:
        if value is None:
            return ""
        return str(value).strip()


class Citation(BaseModel):
    """Source citation surfaced to the UI and plugin."""

    source_id: str
    title: str
    url: str | None = None
    license: str
    attribution: str | None = None


class RetrievedChunk(BaseModel):
    """Retrieved source chunk with enough metadata for debugging."""

    chunk_id: str
    source_id: str
    title: str
    text: str
    score: float
    url: str | None = None
    license: str
    tags: list[str] = Field(default_factory=list)


class ChatResponse(BaseModel):
    """Plugin-facing chat response."""

    answer: str
    citations: list[Citation] = Field(default_factory=list)
    retrieved_chunks: list[RetrievedChunk] = Field(default_factory=list)
    warnings: list[str] = Field(default_factory=list)