Instructor — Structured LLM Outputs with Pydantic

What it is

Instructor is a Python library that patches LLM client libraries to return structured data validated by Pydantic models. Instead of parsing raw text or hoping for valid JSON, you define a Pydantic schema and Instructor ensures the LLM output matches it. It works with OpenAI, Anthropic, Google Gemini, and local models.

It targets developers building applications that need reliable, typed data extraction from LLM responses — classification, entity extraction, data transformation, and structured summarization.

How it saves time or tokens

Instructor handles retries, validation, and schema enforcement automatically. When the LLM returns malformed data, Instructor re-prompts with the validation error, fixing the output without manual intervention. This reduces debugging time and wasted tokens on malformed responses. Estimated token usage is around 4,200 tokens.

How to use

1. Install Instructor:

pip install instructor

1. Patch your client and define a model:

import instructor
from openai import OpenAI
from pydantic import BaseModel

client = instructor.from_openai(OpenAI())

class User(BaseModel):
    name: str
    age: int

user = client.chat.completions.create(
    model='gpt-4o',
    response_model=User,
    messages=[{'role': 'user', 'content': 'Extract: John is 25 years old'}]
)
print(user.name, user.age)

1. The response is a validated Pydantic object, not raw text.

Example

import instructor
from openai import OpenAI
from pydantic import BaseModel
from typing import List

client = instructor.from_openai(OpenAI())

class Contact(BaseModel):
    name: str
    email: str
    company: str

class ContactList(BaseModel):
    contacts: List[Contact]

result = client.chat.completions.create(
    model='gpt-4o',
    response_model=ContactList,
    messages=[{'role': 'user', 'content': 'Extract contacts from this email thread...'}]
)
for c in result.contacts:
    print(f'{c.name} at {c.company}')

Related on TokRepo

• AI Tools for Coding — Developer tools for LLM application development
• AI Tools for API — API integration and structured output tools

Key considerations

When evaluating Instructor for your workflow, consider the following factors. First, assess whether your team has the technical prerequisites to adopt this tool effectively. Second, evaluate the maintenance burden against the productivity gains. Third, check community activity and documentation quality to ensure long-term viability. Integration with your existing toolchain matters more than feature count alone. Start with a small pilot project before rolling out across the organization. Monitor resource usage during the initial adoption phase to identify bottlenecks early. Document your configuration decisions so team members can onboard independently.

Common pitfalls

• Complex nested Pydantic models increase the chance of validation failures; keep schemas as flat as possible.
• Retry logic consumes additional tokens; set a max_retries limit to avoid runaway costs.
• Not all model providers support function calling natively; Instructor uses different strategies (JSON mode, tool calling) depending on the provider.