Instructor

Instructor is a Python library that forces LLMs to return valid, validated Pydantic models by patching official provider SDKs — combining JSON mode, function calling, and automatic retry-with-error-feedback into a single decorator-driven interface — making structured LLM output as simple as defining a Python class and as reliable as a typed API endpoint.

What Is Instructor?

• Definition: An open-source Python library (by Jason Liu, 2023) that wraps OpenAI, Anthropic, Google, and other LLM provider SDKs to add a `response_model` parameter — specify any Pydantic BaseModel subclass and Instructor guarantees the LLM response parses into a valid instance of that class.
• Core Mechanism: Instructor uses the provider's native structured output mechanism (OpenAI JSON mode, function calling, or tool use) and adds Pydantic validation on top — if validation fails, it automatically re-prompts the LLM with the validation error message and retries.
• Pydantic Integration: Every field definition, validator, and description in your Pydantic model becomes a prompt signal — `Field(description="Must be a positive integer")` is automatically included in the schema sent to the LLM.
• Automatic Retries: Configure `max_retries=3` and Instructor handles the retry loop — catching Pydantic ValidationErrors, formatting them as feedback to the LLM, and requesting a corrected response.
• Multi-Provider: Supports OpenAI, Anthropic Claude, Google Gemini, Cohere, Mistral, Ollama, and any OpenAI-compatible endpoint — same code, different providers.

Why Instructor Matters

• Developer Ergonomics: Defining a Pydantic model is already standard Python practice — Instructor makes it the complete interface for LLM structured output, requiring zero prompt engineering for format compliance.
• Validation as Specification: Pydantic validators serve as both input specification and output guarantee — `@validator("age") def age_must_be_positive` becomes both documentation and enforcement.
• Streaming Support: Stream Pydantic model instances as they generate — useful for progressive UI updates where you want to show partial results as the LLM generates each field.
• Observability Integration: First-class integration with Langfuse, Logfire, and OpenTelemetry — every Instructor call is automatically traced with input schema, output, validation errors, and retry count.
• Widely Adopted: One of the most-starred structured output libraries on GitHub — used by thousands of production applications for data extraction, classification, and agent tool responses.

Core Usage Pattern

import instructor
from anthropic import Anthropic
from pydantic import BaseModel, Field

client = instructor.from_anthropic(Anthropic())

class Person(BaseModel):
    name: str = Field(description="Full name of the person")
    age: int = Field(ge=0, le=150, description="Age in years")
    occupation: str

person = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=512,
    messages=[{"role": "user", "content": "Extract: John Smith, 34, works as a software engineer"}],
    response_model=Person,
)
# person.name == "John Smith", person.age == 34, always a valid Person

Advanced Instructor Features

Nested Models:

class Address(BaseModel):
    street: str
    city: str
    country: str

class Company(BaseModel):
    name: str
    headquarters: Address   # Nested Pydantic model works automatically
    employees: list[Person] # List of models also works

Partial Streaming:

for partial_person in client.messages.create(..., stream=True, response_model=Iterable[Person]):
    print(partial_person)  # Progressive output as fields generate

Validation with Feedback:
When the LLM outputs `"age": "thirty-four"`, Pydantic raises `ValidationError: age must be int`. Instructor automatically sends: *"The previous response had a validation error: age must be int. Please correct and retry."* — the LLM self-corrects without developer intervention.

Instructor vs Alternatives

Common Use Cases

• Document Extraction: Extract invoices, contracts, and reports into typed Python objects for downstream processing.
• Classification: Multi-label classification with `Literal` type hints — `category: Literal["tech", "sports", "politics"]`.
• Agent Tool Responses: Ensure tool-calling agents return well-formed tool results that downstream functions can consume without error handling.
• Data Pipeline ETL: Transform unstructured text sources into structured database records with guaranteed schema compliance.
• API Response Generation: Build LLM-powered API endpoints that always return valid JSON matching your OpenAPI schema.

Instructor is the simplest path from Pydantic model to reliable structured LLM output — by leveraging the validation infrastructure Python developers already use daily, Instructor makes LLM-powered data extraction and classification as trustworthy and maintainable as any other typed function in a production codebase.