Instructor

// Overview

Instructor is a library for getting structured, validated data out of large language models. You define the shape you want as a Pydantic model, pass it as a response_model, and Instructor returns a typed object instead of raw text you have to parse yourself. It is built on Pydantic, so you get validation, type hints, and IDE autocompletion for the result.

It is aimed at developers who call an LLM to extract or classify information and need the output to match a fixed schema every time. Instead of writing JSON schemas by hand, parsing responses, and handling validation errors, you write one model and let the library handle the rest. When a response fails validation, Instructor retries the call automatically with the error attached.

As a structured-output tool, it wraps the provider client rather than replacing it. The same code works across OpenAI, Anthropic, Google, Ollama, and others through a single from_provider interface, and the project ships SDKs for Python, TypeScript, Ruby, Go, Elixir, and Rust.

// What it does

• Define output shape as a Pydantic model and get a validated, typed object back
• One from_provider interface works across OpenAI, Anthropic, Google, Ollama, Groq, and more
• Automatic retries that re-send the validation error when output fails to validate
• Streaming support via Partial[Model] to receive fields as they are generated
• Extracts nested and list-based structures, not just flat objects
• Available in Python, TypeScript, Ruby, Go, Elixir, and Rust

// Getting started

Install the package, define a model for the data you want, and call the client with response_model set to that model.

pip install instructor

import instructor
from pydantic import BaseModel

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

client = instructor.from_provider("openai/gpt-4o-mini")
user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "John is 25 years old"}],
)

print(user)  # User(name='John', age=25)

from pydantic import BaseModel, field_validator

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

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

user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "..."}],
    max_retries=3,
)

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Pull structured fields (name, price, in-stock status) out of free-form product or document text
• Build extraction pipelines that must return data matching a fixed schema on every call
• Swap LLM providers without rewriting parsing code, since the same model and call work across providers
• Stream partial results into a UI as the model fills in each field

// How Instructor compares

Instructor alongside other open-source structured output tools AI/TLDR tracks, ranked by GitHub stars.