Skip to content
MyEngineeringPath

Pydantic for AI Engineers — Data Validation & Structured Outputs (2026)

1. Why Pydantic Matters for AI Engineers

Section titled “1. Why Pydantic Matters for AI Engineers”

LLMs produce untyped string outputs. You ask for JSON — you get a string that might be JSON. You ask for structured data — you get text that might parse correctly, or might contain a missing field, a wrong type, or a hallucinated key that does not exist in your schema.

This is the central problem Pydantic solves for AI engineers. It takes raw, untrusted data — from LLM responses, API payloads, configuration files, or user inputs — and validates it against a schema you define using Python type hints. If the data conforms, you get a typed Python object with autocomplete, static analysis, and guaranteed field access. If it does not conform, you get a structured error explaining exactly what failed and where.

Without Pydantic, a single malformed LLM response can crash your entire pipeline. A missing source_documents key, a confidence score returned as a string instead of a float, or an unexpected null value propagates silently through your code until it causes an error far from the original fault. With Pydantic, validation happens at the boundary — the moment data enters your system — and failures are caught immediately with actionable error messages.

For GenAI engineers specifically, Pydantic is not optional tooling. It is infrastructure. OpenAI’s structured output mode, Anthropic’s tool use, LangChain’s output parsers, and FastAPI’s request/response handling all use Pydantic as their schema definition layer. Understanding Pydantic deeply means understanding the data contract layer that connects every component in a modern AI stack.

2. When to Use Pydantic in AI Projects

Section titled “2. When to Use Pydantic in AI Projects”

Pydantic applies wherever untrusted or untyped data crosses a boundary in your system. In AI applications, those boundaries are everywhere.

Structured LLM Outputs

Section titled “Structured LLM Outputs”

When you prompt an LLM to return JSON, you need to validate that the response conforms to your expected schema before passing it downstream. Pydantic models define what “correct” looks like, and model_validate_json() enforces it at runtime.

Tool and Function Call Schemas

Section titled “Tool and Function Call Schemas”

LLM function calling requires JSON Schema definitions for each tool. Pydantic’s model_json_schema() generates compliant schemas directly from your model definitions, keeping tool schemas and validation logic in a single source of truth.

API Request and Response Contracts

Section titled “API Request and Response Contracts”

FastAPI uses Pydantic models as its native schema layer. Define your AI endpoint’s input parameters and output structure as Pydantic models, and FastAPI handles validation, serialization, and OpenAPI documentation automatically.

Configuration and Settings Management

Section titled “Configuration and Settings Management”

BaseSettings validates environment variables and configuration files at application startup. API keys, model names, temperature values, and token limits are validated before your first LLM call — not when a production request fails at 3 AM.

Data Pipeline Validation

Section titled “Data Pipeline Validation”

RAG pipelines ingest documents, chunk text, embed vectors, and store metadata. Pydantic models at each stage validate that data flows correctly — that embeddings have the right dimensionality, that metadata fields exist, and that chunk sizes fall within bounds.

3. How Pydantic Works — Architecture

Section titled “3. How Pydantic Works — Architecture”

Pydantic validates data through a pipeline that transforms raw input into typed, validated Python objects.

Pydantic Validation Pipeline

Raw data enters, typed models exit. Validation failures are caught at the boundary.

Raw Data
Dict, JSON string, or keyword arguments from LLM output or API request
JSON string
Python dict
Keyword args
Schema Definition
BaseModel subclass with type annotations, Field metadata, and validators
Type hints
Field constraints
Custom validators
Validation Engine
Rust-based pydantic-core — type checking, coercion, and constraint enforcement
Type coercion
Constraint checks
Validator execution
Typed Model
Validated Python object with autocomplete, attribute access, and type safety
Typed attributes
Method access
IDE support
Serialization
model_dump() for dict, model_dump_json() for JSON, model_json_schema() for schema
To dict
To JSON
To JSON Schema
Idle

The Validation Flow

Section titled “The Validation Flow”

When you call Model(field="value") or Model.model_validate(data):

  1. Input normalization — Raw data is converted to a consistent internal format. JSON strings are parsed. Dictionaries are passed through. Keyword arguments are collected.
  2. Type checking and coercion — Each field is checked against its type annotation. Compatible types are coerced (string "123" becomes integer 123). Incompatible types raise a ValidationError.
  3. Constraint enforcement — Field constraints (gt, lt, min_length, max_length, pattern) are applied. Values outside bounds are rejected.
  4. Custom validators — @field_validator functions run on individual fields. @model_validator functions run on the complete model, enabling cross-field validation.
  5. Object construction — If all checks pass, a typed Python object is returned with validated attributes.

The entire validation pipeline runs through pydantic-core, which is written in Rust. This means validation is fast enough to run on every request in a production API without measurable overhead.

4. Pydantic Tutorial for AI Engineers

Section titled “4. Pydantic Tutorial for AI Engineers”

This section covers the Pydantic patterns that appear most frequently in AI codebases: BaseModel definitions, field validation, nested models, and custom types for AI-specific data.

BaseModel Fundamentals

Section titled “BaseModel Fundamentals”

Every Pydantic schema starts with a BaseModel subclass. Type annotations define the expected shape. Default values make fields optional.

from pydantic import BaseModel, Field
from typing import Optional


class LLMResponse(BaseModel):
    """Schema for validating structured LLM output."""
    answer: str = Field(min_length=1, description="The generated answer")
    confidence: float = Field(ge=0.0, le=1.0, description="Confidence score")
    sources: list[str] = Field(default_factory=list, description="Source document IDs")
    model_name: Optional[str] = None


# Validate from a dict (e.g., parsed LLM JSON output)
data = {"answer": "RAG combines retrieval with generation.", "confidence": 0.92}
response = LLMResponse.model_validate(data)
print(response.answer)       # RAG combines retrieval with generation.
print(response.confidence)   # 0.92
print(response.sources)      # []

Field Validators

Section titled “Field Validators”

@field_validator runs custom logic on individual fields. Use it to normalize, transform, or enforce domain-specific rules.

from pydantic import BaseModel, Field, field_validator


class SearchQuery(BaseModel):
    query: str = Field(min_length=1, max_length=1000)
    top_k: int = Field(default=5, ge=1, le=100)
    threshold: float = Field(default=0.7, ge=0.0, le=1.0)


    @field_validator("query")
    @classmethod
    def strip_and_validate_query(cls, v: str) -> str:
        v = v.strip()
        if not v:
            raise ValueError("Query cannot be empty or whitespace-only")
        return v

Model Validators for Cross-Field Logic

Section titled “Model Validators for Cross-Field Logic”

@model_validator validates relationships between fields — something @field_validator cannot do because it sees only one field at a time.

from typing_extensions import Self
from pydantic import BaseModel, model_validator


class GenerationConfig(BaseModel):
    temperature: float = 0.7
    top_p: float = 1.0
    max_tokens: int = 1024
    stream: bool = False


    @model_validator(mode="after")
    def validate_sampling_params(self) -> Self:
        if self.temperature == 0.0 and self.top_p < 1.0:
            raise ValueError(
                "top_p has no effect when temperature is 0 (greedy decoding)"
            )
        return self

Nested Models for Hierarchical Data

Section titled “Nested Models for Hierarchical Data”

AI pipelines produce hierarchical outputs. Define nested models to validate the full structure recursively.

from pydantic import BaseModel, Field


class SourceDocument(BaseModel):
    doc_id: str
    title: str
    relevance_score: float = Field(ge=0.0, le=1.0)
    chunk_text: str = Field(min_length=1)


class RAGResponse(BaseModel):
    query: str
    answer: str
    sources: list[SourceDocument] = Field(min_length=1)
    total_tokens: int = Field(ge=0)
    latency_ms: float = Field(ge=0.0)


# A malformed source document inside an otherwise valid response
# is caught with the exact path to the error

5. Pydantic in the AI Stack

Section titled “5. Pydantic in the AI Stack”

Pydantic operates at the data contract layer — the boundary between every major component in a GenAI application. From the API framework down to the tool execution layer, Pydantic schemas define what valid data looks like.

Pydantic in the GenAI Application Stack

Pydantic defines the data contract at every layer boundary.

Application Layer
User interface, chat UI, API clients
API Layer (FastAPI)
Request/response validation via Pydantic models
Data Models (Pydantic)
Shared schemas — LLM outputs, tool args, pipeline state
LLM Integration
Structured output parsing, response validation, retries
Tool Schemas
Function calling schemas generated from model_json_schema()
Validation Layer
Config validation (BaseSettings), embedding dimensions, chunk bounds
Idle

Where Pydantic Sits

Section titled “Where Pydantic Sits”

At the API layer, FastAPI uses Pydantic models to validate incoming requests and serialize outgoing responses. Your LLM endpoint receives a validated SearchQuery and returns a validated RAGResponse.

At the data model layer, shared Pydantic schemas act as contracts between pipeline stages. The retrieval stage produces SourceDocument objects. The generation stage consumes them. If the contract changes, validation catches the mismatch immediately.

At the LLM integration layer, Pydantic validates raw LLM outputs before they enter your application logic. A malformed JSON response from the LLM triggers a ValidationError rather than propagating through your codebase.

At the tool schema layer, model_json_schema() generates the JSON Schema that LLMs need for function calling. The same model that validates incoming tool arguments also defines the schema sent to the LLM.

At the validation layer, BaseSettings validates configuration at startup. Embedding dimensions, chunk size limits, API endpoints, and model parameters are checked before the first request arrives.

6. Pydantic AI Code Examples

Section titled “6. Pydantic AI Code Examples”

Three complete, annotated examples that demonstrate the most common Pydantic patterns in production AI code.

Example 1: Validating LLM JSON Output

Section titled “Example 1: Validating LLM JSON Output”

Parse and validate structured output from an LLM call. Handle validation failures with retries.

import json
from pydantic import BaseModel, Field, ValidationError
from openai import OpenAI


class ExtractedEntity(BaseModel):
    name: str = Field(min_length=1)
    entity_type: str = Field(description="person, organization, or location")
    confidence: float = Field(ge=0.0, le=1.0)


class ExtractionResult(BaseModel):
    entities: list[ExtractedEntity]
    raw_text: str
    model_used: str


def extract_entities(text: str, max_retries: int = 2) -> ExtractionResult:
    client = OpenAI()


    for attempt in range(max_retries + 1):
        response = client.chat.completions.create(
            model="gpt-4o",
            messages=[
                {"role": "system", "content": "Extract entities as JSON."},
                {"role": "user", "content": text}
            ],
            response_format={"type": "json_object"}
        )


        raw_json = response.choices[0].message.content
        try:
            parsed = json.loads(raw_json)
            result = ExtractionResult.model_validate({
                "entities": parsed.get("entities", []),
                "raw_text": text,
                "model_used": "gpt-4o"
            })
            return result
        except (json.JSONDecodeError, ValidationError) as e:
            if attempt == max_retries:
                raise ValueError(f"Validation failed after {max_retries + 1} attempts: {e}")
            # Retry — LLM may produce valid output on next attempt
            continue

Example 2: Defining Tool Schemas for Function Calling

Section titled “Example 2: Defining Tool Schemas for Function Calling”

Generate JSON Schema for LLM function calling directly from Pydantic models.

from pydantic import BaseModel, Field


class WeatherQuery(BaseModel):
    """Get current weather for a location."""
    location: str = Field(description="City and state, e.g. 'San Francisco, CA'")
    unit: str = Field(
        default="fahrenheit",
        description="Temperature unit",
        pattern="^(celsius|fahrenheit)$"
    )


class DatabaseQuery(BaseModel):
    """Search the knowledge base for relevant documents."""
    query: str = Field(description="Natural language search query")
    top_k: int = Field(default=5, ge=1, le=20, description="Number of results")
    filter_metadata: dict[str, str] = Field(
        default_factory=dict,
        description="Key-value filters on document metadata"
    )


# Generate schemas for function calling
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": WeatherQuery.__doc__,
            "parameters": WeatherQuery.model_json_schema()
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_knowledge_base",
            "description": DatabaseQuery.__doc__,
            "parameters": DatabaseQuery.model_json_schema()
        }
    }
]


# When the LLM returns tool arguments, validate them
def execute_tool(tool_name: str, raw_args: dict):
    schemas = {"get_weather": WeatherQuery, "search_knowledge_base": DatabaseQuery}
    validated_args = schemas[tool_name].model_validate(raw_args)
    # Execute with validated, typed arguments
    return call_tool(tool_name, validated_args)

Example 3: Typed RAG Response Model

Section titled “Example 3: Typed RAG Response Model”

A complete response model for a production RAG endpoint with nested validation.

from datetime import datetime
from pydantic import BaseModel, Field, field_validator, model_validator
from typing import Optional
from typing_extensions import Self


class RetrievedChunk(BaseModel):
    chunk_id: str
    document_title: str
    text: str = Field(min_length=1)
    score: float = Field(ge=0.0, le=1.0)
    metadata: dict[str, str] = Field(default_factory=dict)


class RAGPipelineResponse(BaseModel):
    query: str
    answer: str = Field(min_length=10)
    chunks: list[RetrievedChunk] = Field(min_length=1)
    confidence: float = Field(ge=0.0, le=1.0)
    model: str
    total_tokens: int = Field(ge=0)
    latency_ms: float = Field(ge=0.0)
    timestamp: datetime = Field(default_factory=datetime.utcnow)
    cached: bool = False
    error: Optional[str] = None


    @field_validator("answer")
    @classmethod
    def answer_not_refusal(cls, v: str) -> str:
        refusal_phrases = ["i cannot", "i'm unable", "as an ai"]
        if any(phrase in v.lower() for phrase in refusal_phrases):
            raise ValueError("LLM returned a refusal instead of an answer")
        return v


    @model_validator(mode="after")
    def confidence_matches_sources(self) -> Self:
        if self.confidence > 0.9 and len(self.chunks) < 2:
            raise ValueError(
                "High confidence requires at least 2 supporting chunks"
            )
        return self

7. Pydantic v2 vs v1

Section titled “7. Pydantic v2 vs v1”

Pydantic v2 rewrote the validation engine in Rust (pydantic-core), delivering significant performance gains and a cleaner API. If you are starting a new AI project, use v2 exclusively. If you are maintaining a v1 codebase, the migration path is well-documented.

Pydantic v2 vs v1

Pydantic v2
Rust core, modern API, 5-50x faster
VS
Pydantic v1
Pure Python, legacy API, widespread adoption
Verdict: Use Pydantic v2 for all new AI projects. The performance gains compound at scale — batch validation of thousands of LLM outputs runs in milliseconds instead of seconds.
Use case
v1 code still works via deprecation compatibility, but migrate to v2 API for long-term support and performance.

Key Migration Changes

Section titled “Key Migration Changes”

The most common changes when migrating AI code from v1 to v2:

v1 Patternv2 PatternNotes
@validator("field")@field_validator("field")Classmethod required, ValidationInfo replaces values
@root_validator@model_validator(mode="after")Returns Self, not a dict
.dict().model_dump()Identical behavior, new name
.json().model_dump_json()Direct JSON string output
.parse_obj(data).model_validate(data)Dict or object validation
.parse_raw(json_str).model_validate_json(json_str)JSON string validation
class Config:model_config = ConfigDict(...)Dict-based config
orm_mode = Truefrom_attributes = TrueIn ConfigDict

8. Pydantic Interview Questions for AI Engineers

Section titled “8. Pydantic Interview Questions for AI Engineers”

These questions test practical understanding of Pydantic in AI contexts — not syntax recall.

“Why would you use Pydantic instead of a try/except around json.loads for LLM output?”

json.loads only checks that the string is valid JSON. It does not verify the structure. A valid JSON object with a missing required field, a score of "high" instead of 0.95, or a nested array where you expected an object all pass json.loads without error. Pydantic validates the schema — field presence, types, constraints, and cross-field relationships. In production, the difference between “valid JSON” and “valid data” is the difference between a working pipeline and a silent data corruption bug.

“How does Pydantic integrate with OpenAI’s structured output mode?”

OpenAI’s API accepts a JSON Schema to constrain the model’s output format. Pydantic’s model_json_schema() generates exactly this schema from your model definition. You define the expected output as a Pydantic model, generate the schema, pass it to the API, and validate the response with model_validate_json(). The same model serves as schema definition, API contract, and validation logic — a single source of truth.

“Explain the difference between mode='before' and mode='after' in @model_validator.”

mode='before' receives the raw input data (usually a dict) before any type coercion or field validation. Use it to restructure data, rename fields, or apply defaults that depend on other input values. mode='after' receives the fully constructed model instance after all field validators have passed. Use it for cross-field validation — for example, ensuring that a high confidence score is supported by a minimum number of source documents.

“When should you use strict mode vs default coercion in an AI pipeline?”

Default coercion ("123" becomes 123) is useful when parsing LLM output, because LLMs sometimes return numbers as strings. Strict mode rejects any type mismatch — useful at internal boundaries where you expect code, not LLMs, to produce data. A common pattern: use coercion at the LLM output boundary, strict mode at internal service-to-service boundaries.

9. Pydantic in Production

Section titled “9. Pydantic in Production”

Production AI applications handle thousands of validation operations per second. Pydantic v2’s performance characteristics, serialization modes, and settings management make it production-ready without additional infrastructure.

Performance (v2 Rust Core)

Section titled “Performance (v2 Rust Core)”

Pydantic v2’s pydantic-core is written in Rust and compiled as a Python extension. Validation runs 5-50x faster than v1 depending on model complexity. For AI workloads:

  • Simple models (5-10 fields, no nesting): validation completes in microseconds, adding negligible overhead to LLM calls that take hundreds of milliseconds
  • Complex nested models (RAG responses with 20+ retrieved chunks): validation completes in low milliseconds, still insignificant compared to retrieval and generation latency
  • Batch validation (validating thousands of extracted entities): v2’s Rust core processes batches that would take seconds in v1 in under 100ms

The performance gain matters most in batch processing pipelines — embedding workflows, document ingestion, and evaluation harnesses where you validate thousands of items per run.

Serialization Modes

Section titled “Serialization Modes”

Pydantic v2 provides fine-grained control over serialization:

from pydantic import BaseModel, Field
from datetime import datetime


class PipelineMetrics(BaseModel):
    query: str
    latency_ms: float
    timestamp: datetime
    token_count: int


metrics = PipelineMetrics(
    query="What is RAG?",
    latency_ms=245.3,
    timestamp=datetime(2026, 3, 19),
    token_count=1024
)


# Python dict — for internal use
metrics.model_dump()


# JSON string — for API responses and logging
metrics.model_dump_json()


# Exclude fields — for client-facing output
metrics.model_dump(exclude={"token_count"})


# JSON Schema — for documentation and tool definitions
PipelineMetrics.model_json_schema()

Settings Management with BaseSettings

Section titled “Settings Management with BaseSettings”

BaseSettings validates configuration from environment variables at application startup:

from pydantic_settings import BaseSettings
from pydantic import Field


class AIConfig(BaseSettings):
    openai_api_key: str
    model_name: str = "gpt-4o"
    temperature: float = Field(default=0.7, ge=0.0, le=2.0)
    max_tokens: int = Field(default=1024, ge=1, le=128000)
    embedding_model: str = "text-embedding-3-small"
    vector_db_url: str = "http://localhost:6333"
    log_level: str = "INFO"


    model_config = {"env_prefix": "AI_"}


# Reads AI_OPENAI_API_KEY, AI_MODEL_NAME, etc. from environment
# Raises ValidationError at startup if required vars are missing
# or values are out of range
config = AIConfig()

A missing API key or an invalid temperature value is caught at startup — not when a production request fails during an LLM call.

10. Summary and Key Takeaways

Section titled “10. Summary and Key Takeaways”

Pydantic is the data validation layer for modern AI applications. It validates LLM outputs, defines tool schemas, enforces API contracts, and manages configuration — all through Python type hints.

The core principle: validate at the boundary. Every point where untrusted data enters your system — LLM responses, API requests, configuration files, external service outputs — should pass through a Pydantic model. This catches malformed data before it propagates through your pipeline.

The key patterns for AI engineers:

  • BaseModel with Field constraints for schema definition
  • model_validate_json() for parsing LLM structured output
  • model_json_schema() for generating function calling schemas
  • @field_validator for per-field validation logic
  • @model_validator for cross-field constraints
  • BaseSettings for validated configuration management
  • Nested models for hierarchical data (RAG responses, agent tool results)

Pydantic v2 is the standard. The Rust core makes validation fast enough to run on every request, every LLM response, and every batch item without performance concerns. Use v2 for all new projects. Migrate v1 code using the documented API mapping.

Pydantic connects the AI stack. FastAPI uses it for API validation. OpenAI uses it for structured outputs. LangChain uses it for output parsing. Your own pipeline stages use it for data contracts. Learning Pydantic deeply means learning the common language that every component in your AI stack speaks.

Section titled “Related”

Frequently Asked Questions

Why is Pydantic important for AI engineers?

LLMs generate untyped string outputs that can contain malformed JSON, missing fields, or wrong data types. Pydantic validates these outputs at runtime against a defined schema, converting raw LLM responses into typed Python objects. Without Pydantic, a single malformed LLM response can crash downstream systems.

How does Pydantic validate LLM structured outputs?

Define a Pydantic BaseModel matching your expected output schema. Parse the LLM's JSON response using model_validate_json(). Pydantic checks every field against its type annotation, runs custom validators, and either returns a typed model instance or raises a ValidationError with specific details about what failed.

What changed between Pydantic v1 and v2?

Pydantic v2 rewrote the validation engine in Rust, delivering 5-50x faster validation. Key API changes: @validator becomes @field_validator, @root_validator becomes @model_validator, .dict() becomes .model_dump(), and .parse_obj() becomes .model_validate().

How do you use Pydantic with FastAPI for AI applications?

FastAPI uses Pydantic models directly as request and response schemas. Define a Pydantic model for your API input and another for the response. FastAPI automatically validates incoming requests, generates OpenAPI documentation, and serializes responses — your LLM pipeline receives validated, typed inputs.

How does Pydantic help with function calling and tool schemas?

Pydantic's model_json_schema() generates compliant JSON Schema from any BaseModel. Define tool parameters as a Pydantic model, generate the schema, and pass it to the LLM's function calling API. When the LLM returns arguments, validate them with model_validate() before executing the tool.

What is the difference between field_validator and model_validator?

A @field_validator validates a single field in isolation. A @model_validator validates the entire model and can enforce cross-field constraints. Use mode='before' to validate raw input before type coercion, or mode='after' to validate the fully constructed model instance.

Can Pydantic validate nested LLM outputs?

Yes. Define nested Pydantic models for hierarchical LLM outputs — for example, a RAGResponse containing a list of SourceDocument models. Pydantic recursively validates the entire nested structure and reports errors with the exact path to the invalid field.

How do you handle LLM outputs that fail Pydantic validation?

Catch ValidationError and implement a retry strategy. Log the raw LLM output and specific validation errors. Retry the LLM call with a more explicit prompt or include the validation error in the retry prompt for self-correction. Set a maximum retry count (typically 2-3) and fall back to a default response if validation continues to fail.

What is Pydantic BaseSettings and why use it for AI apps?

BaseSettings extends BaseModel to load and validate configuration from environment variables. For AI applications, use it to manage API keys, model names, temperature settings, and token limits. A misspelled boolean or out-of-range temperature is caught at application startup rather than failing during an LLM call in production.

How does Pydantic compare to dataclasses for AI development?

Python dataclasses define data structures but do not validate data at runtime. Pydantic models validate every field on instantiation, coerce compatible types, and provide detailed error messages. For AI development where inputs come from unpredictable LLM outputs, runtime validation is essential.