Pydantic, the one that actually validates

This is the most important third-party library in Python for the work you are about to do. FastAPI is built on it, LangChain uses it for every tool schema and every structured output, and it is the only thing in this module that does anything at runtime.

What it is

A class whose annotations are executed rather than ignored.

from pydantic import BaseModel, Field

class SearchQuery(BaseModel):
    query: str
    limit: int = Field(default=10, ge=1, le=100)
    include_archived: bool = False

q = SearchQuery.model_validate({"query": "python", "limit": "25"})
q.limit          # 25, as an int. The string was coerced.

SearchQuery.model_validate({"query": "python", "limit": 500})
# ValidationError: limit -> Input should be less than or equal to 100

Compare with the dataclass from the previous lesson, which would have stored the string "25" and accepted 500 without comment. Same-looking class, completely different runtime contract.

The core API is four methods, and the model_ prefix is deliberate so they cannot collide with your field names:

SearchQuery.model_validate(some_dict)      # parse and validate
SearchQuery.model_validate_json(raw_text)  # straight from a JSON string
q.model_dump()                             # -> dict
q.model_dump_json()                        # -> JSON string
SearchQuery.model_json_schema()            # -> JSON Schema

Coercion, which will surprise you once

The default is lax mode, which converts where the conversion is unambiguous. For an int field, the documented rules are that a str is accepted if it is numeric only, a float is accepted if it has no fractional part, and a bool is accepted.

That is genuinely the right default at a boundary, where a form post or a query string delivers everything as text and you would otherwise write conversion code by hand. It is also genuinely surprising the first time it accepts something you expected it to reject.

from pydantic import ConfigDict, StrictInt

class Strict(BaseModel):
    model_config = ConfigDict(strict=True)
    attempts: int            # now only a real int is accepted

class PartlyStrict(BaseModel):
    attempts: StrictInt      # just this field
    name: str                # still lax

The reason it is a hard dependency of every agent framework

This is worth understanding rather than accepting, because it explains a design decision that otherwise looks like taste.

An LLM tool call needs a JSON Schema describing the tool’s arguments, sent to the model provider. The model’s reply comes back as text, and something has to turn that text into a validated object or reject it.

Annotations alone cannot do either, because the interpreter ignores them. Pydantic reads them and produces both halves from one class definition:

class WeatherArgs(BaseModel):
    city: str = Field(description="City name, e.g. 'London'")
    units: Literal["c", "f"] = "c"

WeatherArgs.model_json_schema()        # -> sent to the model as the tool schema
WeatherArgs.model_validate_json(raw)   # <- validates what came back

The description on a Field is not a comment. It lands in the generated schema and the model reads it, which makes it prompt text disguised as a type annotation. Vague field descriptions produce bad tool calls, and this is one of the highest-leverage places to be specific in the entire agent stack.

This same machinery is what with_structured_output uses in LangChain: you hand it a model class, it generates the schema, constrains the response, and validates the result.

Validators

from pydantic import BaseModel, field_validator, model_validator

class Window(BaseModel):
    start: int
    end: int

    @field_validator("start", "end")
    @classmethod
    def non_negative(cls, v: int) -> int:
        if v < 0:
            raise ValueError("must be non-negative")
        return v

    @model_validator(mode="after")
    def ordered(self) -> "Window":
        if self.start >= self.end:
            raise ValueError("start must be before end")
        return self

@field_validator runs per field and sees one value. @model_validator(mode="after") runs once on the constructed instance and can see every field at once, which is what you need for any rule relating two fields. Both signal failure by raising ValueError, which Pydantic collects into a ValidationError rather than letting it escape.

That collection behaviour is the part worth noticing: a ValidationError carries every failure at once, each with a location path and an error type, so exc.errors() is directly shapeable into an API error response. It does not stop at the first problem.

Reading old answers

Pydantic v2 was a rewrite with a Rust core, and the API was renamed wholesale. Most search results and most model-generated Python still show v1.

The model_ prefix is the tell. One glance at a snippet tells you which era it is from, and that is worth more than memorising the table: you will not remember every row, but you will remember that .dict() means you are reading something old and should go looking for the current spelling.

TypeAdapter, for when there is no class

from pydantic import TypeAdapter

adapter = TypeAdapter(list[SearchQuery])
adapter.validate_python(raw_list)

Any annotation can be validated, not just a BaseModel subclass. This is how you validate a bare list[int], a dict[str, Thing], or a TypedDict without inventing a wrapper model around it. Build the adapter once and reuse it; construction is the expensive part.

Where this goes

That is the type system, honestly described. Module 4 is the four idioms you will meet on your first day in an agent repo, all of which look like syntax and are actually protocols.