Pydantic

Pydantic leverages Python's native type hints to define data models, eliminating the need for external schema languages. A model is simply a class inheriting from BaseModel with annotated attributes.

• Automatic Validation: Data is validated against the type hints upon instantiation.
• IDE Support: Standard Python types provide full autocompletion and static analysis.
• Complex Types: Supports nested models, List, Dict, Optional, Union, and constrained types like conint(ge=0).

Pydantic intelligently converts input data to match the declared types where possible, a critical feature when parsing raw string outputs from language models.

• Lax Coercion (Default): A string "123" is automatically converted to an integer 123.
• Strict Mode: Setting strict=True on a field or model raises a ValidationError if types do not match exactly, enforcing rigid API contracts.
• Custom Validators: The @field_validator and @model_validator decorators allow for arbitrary logic beyond simple type checking.

Every Pydantic model can be serialized to a JSON Schema (Draft 2020-12 or OpenAPI-compatible) using the .model_json_schema() method. This is the mechanism by which structured output constraints are communicated to language model APIs.

• Function Calling Integration: The generated schema is passed directly to the functions or tools parameter of OpenAI and compatible APIs.
• Guided Generation: Frameworks like llama.cpp and Outlines consume this schema to perform grammar-constrained decoding.
• Documentation: The schema serves as a self-documenting contract for your API.

Pydantic provides robust, configurable methods for converting between model instances and standard Python primitives or JSON strings.

• model_dump(): Serializes a validated model instance to a dictionary, with options to exclude unset fields, use aliases, or round-trip data.
• model_dump_json(): Directly serializes to a JSON string.
• model_validate(): The primary entry point for parsing a dictionary or object into a model instance, raising a ValidationError with detailed error locations on failure.

The Instructor library patches the OpenAI client to make extracting Pydantic models from language model responses a one-step process. Instead of manually parsing raw JSON, you define the desired output as a Pydantic model.

• Automatic Retries: Instructor can catch ValidationError exceptions and re-prompt the model with the error details for self-correction.
• Streaming Partial Objects: Supports iteratively building a Pydantic model as tokens are generated.
• Mode Flexibility: Works with function calling, tool use, or raw JSON mode depending on the provider.

The Field() function provides fine-grained control over each attribute, essential for guiding language model extraction.

• Descriptions: The description argument is injected into the JSON Schema, serving as a natural language prompt for the model about what to extract.
• Examples: The examples argument provides few-shot guidance within the schema.
• Aliases: The alias parameter allows mapping from inconsistent external field names (e.g., first_name from firstName) to a canonical internal schema.
• Pattern Matching: The pattern argument accepts a regex string to constrain string outputs.

A technique that constrains the token generation process to adhere to a predefined grammar or schema. Unlike post-hoc validation, guided decoding physically prevents the model from sampling tokens that would violate the Pydantic model's structure.

• Uses a Finite State Machine (FSM) to track valid next tokens
• Guarantees syntactically valid output on the first pass
• Implemented in libraries like Outlines and llama.cpp

A capability where an LLM outputs a structured JSON object containing a function name and arguments rather than free text. The schema for these arguments is typically defined using a JSON Schema derived from a Pydantic model.

• Enables deterministic integration with external APIs
• The model signals intent to invoke a tool, not generate prose
• Relies on token masking to enforce parameter types

The act of verifying that a generated data structure strictly conforms to a predefined schema. Pydantic performs this at runtime, raising ValidationError exceptions with precise location data for mismatched types or missing fields.

• Ensures type safety before data enters a database
• Catches LLM hallucinations that produce extra or malformed keys
• Can trigger automatic retry loops with refined prompts