models.py

from typing import Literal
from datetime import date
from pydantic import BaseModel, Field, field_validator

ClassificationType = Literal[
    "zugzwang", "fork", "zwischenzug", "prophylaxis",
    "gambit", "overextension", "tempo_loss"
]

CONFIDENCE_LEVELS = ("low", "medium", "high")

REASONING_MAX_LENGTH = 800


class Diagnosis(BaseModel):
    """Structured output contract for Gemini.

    Field order here is deliberate and matters: Gemini's controlled JSON
    generation fills fields in the order they're declared in the schema.
    `reasoning` is declared FIRST so the model has to articulate its
    analysis before committing to a label — a lightweight chain-of-thought
    effect achieved purely through schema ordering, not extra prompting.
    `classification` comes after reasoning; `confidence_bucket` comes last
    since a confidence assessment naturally follows having already stated
    both the reasoning and the label.

    max_length was originally 500, raised to REASONING_MAX_LENGTH (800)
    after real eval testing showed the more detailed FORK/ZUGZWANG
    tie-breaker instructions (added to fix a separate classification bug)
    made Gemini's typical reasoning length longer, causing repeated
    ValidationErrors that survived all 3 retries — retrying didn't help
    because temperature=0.3 produces consistently similar-length output
    for the same input, so a failure like this repeats instead of clearing
    up on its own. See gemini_client.py for the accompanying prompt
    instruction to keep reasoning brief, and the truncation fallback that
    now handles it locally instead of burning more API calls.
    """
    reasoning: str = Field(max_length=REASONING_MAX_LENGTH)
    classification: ClassificationType
    confidence_bucket: Literal["low", "medium", "high"]


class EntryCreateRequest(BaseModel):
    situation_text: str = Field(min_length=1, max_length=1000)
    entry_date: date

    @field_validator("situation_text")
    @classmethod
    def strip_and_check_not_blank(cls, v: str) -> str:
        stripped = v.strip()
        if not stripped:
            raise ValueError("situation_text cannot be blank or whitespace-only")
        return stripped

    @field_validator("entry_date")
    @classmethod
    def reject_future_dates(cls, v: date) -> date:
        if v > date.today():
            raise ValueError("entry_date cannot be in the future")
        return v