Free-form model output is harder to trust than data that must pass a schema.
This project is a small set of notebooks showing how Pydantic models can validate application data, define structured LLM outputs, and provide typed schemas for tool calling. The examples include OpenAI tool calling and experiments with pydanticai, Anthropic, and Instructor.
Quick start
Start with main.ipynb for Pydantic validation, then open toolcalling.ipynb for LLM tool-schema examples.
Expected result: the notebooks define typed models, reject invalid values, turn schemas into model/tool contracts, and validate returned arguments before application code uses them.
API-backed examples require the corresponding provider credentials in your local environment.
The problem
LLMs naturally return text, while application code usually needs typed, bounded data. Parsing ad-hoc JSON is not enough if fields can be missing, malformed, or semantically invalid.
These notebooks demonstrate using Pydantic as the boundary between model output and application logic.
What is covered
BaseModel schemas and typed fields;
validation errors and custom validators;
constrained user/application inputs;
structured model output;
deriving tool schemas from Pydantic models;
validating tool-call arguments before execution;
OpenAI tool-calling examples;
related experiments with pydanticai, Anthropic, and Instructor.
One example validates an order ID against a fixed ABC-12345-style pattern before it reaches downstream logic.
Current state
Implemented
main.ipynb — foundational Pydantic validation examples.
toolcalling.ipynb — Pydantic-backed LLM tool calling.
api.ipynb — API-oriented examples.
faq.csv — small example data source used by the exercises.
Implemented but not packaged
The material is notebook-based rather than a reusable Python package.
Provider-backed cells depend on local API credentials and current SDK versions.
There is no repository-level automated test suite or CI workflow proving every notebook cell still runs against the latest provider APIs.
Planned
No formal roadmap is tracked. The useful next improvement would be a minimal locked environment and automated notebook execution check.
Intentionally unsupported / not claimed
This is not a Pydantic replacement or wrapper library.
It is not a production tool-calling framework.
It does not benchmark provider reliability or structured-output accuracy.
What sets this repository apart
The repository is intentionally small: it shows the boundary between untrusted model-generated arguments and validated Python objects without hiding that boundary behind a large framework.
The important idea is reusable beyond any provider: validate generated structure before application code trusts it.
Evals and test series
There is currently no automated repository-level verification.
The smallest useful test for these examples is straightforward:
construct a valid model instance and confirm it passes;
provide malformed fields and confirm Pydantic rejects them;
run a tool-call example;
validate the returned arguments against the same Pydantic model before invoking the Python function.
A future CI check should execute the provider-independent notebook cells automatically and keep API-backed examples isolated behind optional credentials.
Repository map
Future development
Add reproducible dependencies and notebook smoke tests before expanding the tutorial surface.