Python Structure and Models

Core Rule

Use both Pydantic models and dataclasses.

• Use Pydantic BaseModel at system boundaries where data is parsed, validated, serialized, deserialized, stored, sent, received, or treated as a stable contract.
• Use standard-library dataclass for internal runtime state, temporary grouping objects, simple helper returns, and mutable state machines that never need JSON schema or external validation.

Dataclasses mainly reduce boilerplate by generating methods such as __init__, __repr__, and comparisons. Standard dataclasses do not deeply validate field types at runtime.

Pydantic BaseModel provides runtime validation, serialization, model_validate, model_dump, and JSON-schema-related functionality.

Decision Table