Choosing a Data Container

Is the data coming from outside the process (HTTP, LLM output, file, env, queue)?
 ├─ yes -> does it need coercion/validation/error messages or a JSON Schema?
 │         ├─ yes -> pydantic BaseModel (or msgspec.Struct if decode speed dominates)
 │         └─ no, trusted and you only want types -> TypedDict (keeps it a dict)
 └─ no (internal object)
      ├─ is it a tiny immutable record mainly unpacked / indexed? -> NamedTuple
      ├─ do you need converters/validators but no pydantic? -> attrs
      ├─ millions of instances, memory-bound? -> dataclass(slots=True) or columnar arrays
      └─ otherwise -> dataclass (frozen=True when it is a value / key / config)

# dataclass
from dataclasses import dataclass

@dataclass(frozen=True)
class ToolCallDC:
    id: str
    name: str
    arguments: str

# pydantic v2
from pydantic import BaseModel, ConfigDict

class ToolCallPM(BaseModel):
    model_config = ConfigDict(frozen=True, extra="forbid")
    id: str
    name: str
    arguments: str

ToolCallPM.model_validate({"id": "call_1", "name": "search", "arguments": "{}"})

# TypedDict
from typing import TypedDict

class ToolCallTD(TypedDict):
    id: str
    name: str
    arguments: str

call: ToolCallTD = {"id": "call_1", "name": "search", "arguments": "{}"}   # still a dict

# NamedTuple
from typing import NamedTuple

class ToolCallNT(NamedTuple):
    id: str
    name: str
    arguments: str

call_id, name, args = ToolCallNT("call_1", "search", "{}")

# attrs
import attrs

@attrs.frozen
class ToolCallAT:
    id: str
    name: str
    arguments: str = attrs.field(validator=attrs.validators.instance_of(str))

# msgspec
import msgspec

class ToolCallMS(msgspec.Struct, frozen=True):
    id: str
    name: str
    arguments: str

call = msgspec.json.decode(b'{"id":"call_1","name":"search","arguments":"{}"}', type=ToolCallMS)

from dataclasses import dataclass

@dataclass(frozen=True)
class RetryPolicy:
    max_attempts: int = 5
    base_delay_s: float = 0.5
    max_delay_s: float = 30.0

    def __post_init__(self) -> None:
        if self.max_attempts < 1:
            raise ValueError("max_attempts must be >= 1")
        if not 0 < self.base_delay_s <= self.max_delay_s:
            raise ValueError("need 0 < base_delay_s <= max_delay_s")

from typing import Literal, Optional

from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator

class SearchArgs(BaseModel):
    """Arguments the model passes to the search tool."""
    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)

    query: str = Field(min_length=1, max_length=512)
    top_k: int = Field(default=5, ge=1, le=50)
    filters: dict[str, str] = Field(default_factory=dict)
    mode: Literal["dense", "hybrid"] = "hybrid"
    since: Optional[str] = None

    @field_validator("query")
    @classmethod
    def no_wildcards(cls, v: str) -> str:
        if v == "*":
            raise ValueError("wildcard queries are not allowed")
        return v

raw = '{"query": " paris hotels ", "top_k": "10"}'
try:
    args = SearchArgs.model_validate_json(raw)     # "10" coerced to 10 in lax mode
except ValidationError as e:
    print(e.errors())                              # feed back to the LLM for a retry
print(SearchArgs.model_json_schema()["properties"]["top_k"])   # tool schema for function calling

from dataclasses import dataclass
from pydantic import TypeAdapter

@dataclass
class Chunk:
    chunk_id: str
    text: str
    score: float = 0.0

chunks = TypeAdapter(list[Chunk]).validate_json('[{"chunk_id": "a", "text": "x", "score": "0.5"}]')
print(type(chunks[0]), chunks[0].score)   # <class '__main__.Chunk'> 0.5

from typing import Literal, TypedDict

try:
    from typing import NotRequired          # 3.11+
except ImportError:                          # 3.9 / 3.10
    from typing_extensions import NotRequired

class ChatMessageTD(TypedDict):
    role: Literal["system", "user", "assistant", "tool"]
    content: str
    name: NotRequired[str]
    tool_call_id: NotRequired[str]

def user(content: str) -> ChatMessageTD:
    return {"role": "user", "content": content}

from typing import NamedTuple

class Hit(NamedTuple):
    score: float
    index: int
    doc_id: str = ""

hits = sorted([Hit(0.4, 3), Hit(0.9, 1)], reverse=True)
best_score, best_idx, _ = hits[0]
print(hits[0]._replace(doc_id="d1"), hits[0]._asdict())

import attrs

def _to_tuple(v) -> tuple:
    return tuple(v)

@attrs.define(frozen=True)            # slots=True by default with define
class Prompt:
    template: str = attrs.field(validator=attrs.validators.min_len(1))
    stop: tuple = attrs.field(factory=tuple, converter=_to_tuple)
    temperature: float = attrs.field(default=0.7, validator=[attrs.validators.ge(0), attrs.validators.le(2)])

p = Prompt("Answer: {q}", stop=["\n"])   # list converted to tuple

from typing import Optional

import msgspec

class Usage(msgspec.Struct):
    prompt_tokens: int
    completion_tokens: int

class Completion(msgspec.Struct, rename="camel"):   # Python snake_case, JSON camelCase
    request_id: str
    finish_reason: Optional[str] = None
    usage: Optional[Usage] = None

decoder = msgspec.json.Decoder(Completion)          # reuse the decoder
c = decoder.decode(b'{"requestId": "r1", "finishReason": "stop", "usage": {"prompt_tokens": 3, "completion_tokens": 5}}')
print(msgspec.json.encode(c))

HTTP / LLM output / files / env
        │  pydantic BaseModel (validate, coerce, clear errors)  or msgspec for speed
        ▼
  convert once: Model -> dataclass   (or validate straight into dataclasses with TypeAdapter)
        ▼
  core logic: frozen dataclasses for values/configs, slots dataclasses for bulk records
        ▼
  serialize at the edge: asdict / custom to_dict / model_dump

from dataclasses import dataclass

from pydantic import BaseModel, Field

class IngestRequest(BaseModel):               # edge
    doc_id: str
    text: str = Field(min_length=1)
    chunk_size: int = Field(default=800, ge=100, le=4000)

@dataclass(frozen=True, slots=True)           # core (3.10+ for slots)
class IngestJob:
    doc_id: str
    text: str
    chunk_size: int

def to_job(req: IngestRequest) -> IngestJob:
    return IngestJob(**req.model_dump())