src/case_zero/schemas/visual.py

"""The visual descriptor the model emits per character / scene / prop.

It drives the offline PIL compositor: the model creatively specifies appearance and
the code only renders that specification into pixel art.
"""

from __future__ import annotations

from pydantic import BaseModel, ConfigDict

from .enums import SubjectType


class VisualDescriptor(BaseModel):
    model_config = ConfigDict(frozen=True)

    subject_type: SubjectType
    # Free-form, model-authored tags the compositor maps onto its layer library.
    palette: str = "noir"
    gender: str = ""  # "male" / "female" -> gendered sprite features + TTS voice
    age_band: str | None = None
    build: str | None = None
    hair: str | None = None
    attire: str | None = None
    mood: str | None = None
    accent_color: str | None = None
    location_tags: tuple[str, ...] = ()
    prop_tags: tuple[str, ...] = ()
    prompt_hint: str = ""