Instructor

Instructor

Instructor is the simplest way to get structured, validated outputs from LLMs. It patches openai, anthropic, google-generativeai, and other clients with a single .from_* call, then uses Pydantic models to define the output schema and automatically validates (and retries on failure).

Key Features

• Pydantic-native — define your output as any Pydantic model; Instructor handles schema generation and parsing
• Multi-provider — OpenAI, Anthropic, Google Gemini, Ollama, Cohere, Mistral, and more
• Auto-retry — on validation failure, Instructor feeds the error back to the LLM and retries automatically
• Streaming — stream partial Pydantic objects as they are generated
• Hooks — before/after hooks for logging, caching, and metrics
• Zero prompt engineering — no need to write JSON-formatting instructions in your prompts

Quick Start

pip install instructor

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-mini",
    response_model=User,
    messages=[{"role": "user", "content": "Extract: John is 30 years old."}],
)
print(user)  # User(name='John', age=30)

Install via ai-supply

npx ai-supply add instructor-structured-outputs

Curated mirror of the open-source Instructor project (MIT). Install upstream from the repository.