Imported from drdave-flexnetos/ai-top-utility (backend/models/AGENTS.md). Install upstream with npx skills add drdave-flexnetos/ai-top-utility --skill models. Copyright stays with the author.

backend/models (Pydantic schemas)

Purpose

Pydantic v2 request / response schemas — one file per router + the ws_events.py discriminated union that types every event broadcast over /ws. Disk-resident model weights live under /mnt/aitop-data/, NOT here — this directory is exclusively the wire-format schemas.

Key Files

For AI Agents

Working In This Directory

• Pydantic v2 only. BaseModel.model_validate / model_dump, not the v1 spellings. Field default factories use default_factory=....
• ws_events.py discriminated union: add new events by appending a new BaseModel with type: Literal["..."] AND adding to the WsEvent = Annotated[Union[...], Field(discriminator="type")] declaration. The router / service code dispatches via the discriminator.
• Schemas mirror the renderer's wire contract. Field names match what the renderer sends — don't rename to snake-case if the renderer uses camelCase (some legacy routes do; check ../API_SURFACE.md).
• Validators at the schema boundary. Don't push input validation into routers / services if a Pydantic validator can express it.

Testing

The smoke test (tests/test_routes_smoke.py) asserts every models/*.py file is importable without torch being loaded. Don't add import torch here — same lazy-import discipline as routers.

Common Patterns

• Optional vs Required: Use Optional[X] = None for fields the renderer sometimes omits; use X for fields the renderer always sends. Don't use X | None (PEP 604) without verifying the codebase's mypy / pydantic versions accept it.
• Literal["..."] for event types — ws_events.py uses literal tags as the discriminator.

Things to NOT do

• Don't import torch / transformers / diffusers here. Schemas describe shapes, not behavior.
• Don't add new schema files outside the per-domain-router convention.
• Don't add validators that round-trip through the database — that's service logic, not schema logic.

Dependencies

Internal

• Consumed by every router in ../routers/.
• ws_events.py is consumed by ../ws.py::ConnectionManager.broadcast.

External

• pydantic 2.x.
• typing (stdlib) for Literal, Annotated, Optional.