How to Intermediate · 3 min read

How to use Pydantic validators with Instructor

Q: How to use Pydantic validators with Instructor

Use Instructor with Pydantic by defining a BaseModel that includes @validator methods for field validation. Pass this model as the response_model parameter in client.chat.completions.create to automatically validate and parse AI responses.

Quick answer

Use Instructor with Pydantic by defining a BaseModel that includes @validator methods for field validation. Pass this model as the response_model parameter in client.chat.completions.create to automatically validate and parse AI responses.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install openai>=1.0 instructor pydantic

Setup

Install the required packages and set your OpenAI API key as an environment variable.

bash

pip install openai instructor pydantic

Step by step

Define a Pydantic BaseModel with validators, then use Instructor to call the OpenAI chat completion API with the model as response_model. The response is automatically validated and parsed.

python

import os
from pydantic import BaseModel, validator, ValidationError
from openai import OpenAI
import instructor

# Initialize OpenAI client
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# Create Instructor client from OpenAI
instructor_client = instructor.from_openai(client)

# Define Pydantic model with validators
class User(BaseModel):
    name: str
    age: int

    @validator('name')
    def name_must_be_alpha(cls, v):
        if not v.isalpha():
            raise ValueError('Name must contain only letters')
        return v

    @validator('age')
    def age_must_be_positive(cls, v):
        if v <= 0:
            raise ValueError('Age must be positive')
        return v

# Prompt to extract structured data
messages = [{"role": "user", "content": "Extract: John is 30 years old"}]

try:
    # Call chat completion with response_model for validation
    user = instructor_client.chat.completions.create(
        model="gpt-4o-mini",
        response_model=User,
        messages=messages
    )
    print(f"Name: {user.name}, Age: {user.age}")
except ValidationError as e:
    print("Validation failed:", e)

output

Name: John, Age: 30

Common variations

Use async calls with await instructor_client.chat.completions.acreate(...) for asynchronous workflows.
Change the model parameter to other OpenAI models like gpt-4o for higher quality.
Customize validators to enforce complex constraints or transformations on extracted fields.

python

import asyncio

async def async_example():
    user = await instructor_client.chat.completions.acreate(
        model="gpt-4o-mini",
        response_model=User,
        messages=messages
    )
    print(f"Async Name: {user.name}, Age: {user.age}")

asyncio.run(async_example())

output

Async Name: John, Age: 30

Troubleshooting

If you see ValidationError, check your Pydantic validators for strictness and ensure the AI output matches expected formats.
Use print(e.json()) on the exception to get detailed validation error info.
Ensure your environment variable OPENAI_API_KEY is set correctly to avoid authentication errors.

python

try:
    user = instructor_client.chat.completions.create(
        model="gpt-4o-mini",
        response_model=User,
        messages=[{"role": "user", "content": "Extract: John123 is -5 years old"}]
    )
except ValidationError as e:
    print("Validation errors:", e.json())

output

[{"loc": ["name"], "msg": "Name must contain only letters", "type": "value_error"}, {"loc": ["age"], "msg": "Age must be positive", "type": "value_error"}]

✅

Key Takeaways

Define Pydantic models with @validator to enforce field validation on AI responses.
Pass the Pydantic model as response_model in Instructor chat calls for automatic parsing and validation.
Use ValidationError exceptions to handle and debug invalid AI outputs.
Async calls and different OpenAI models are fully supported with the same validation pattern.

Verified 2026-04 · gpt-4o-mini

Verify ↗