Library of the Week — Instructor

Instructor — Structured outputs from LLMs, without the boilerplate

GitHub · Stars: ~10k · Language: Python · License: MIT

What it does

Instructor wraps LLM API calls to guarantee structured, typed outputs using Pydantic models — no manual JSON parsing, no fragile regex, no prompt engineering gymnastics. It’s built for developers who need reliable data extraction from frontier models and are tired of babysitting output formats in production.

Why it stands out

• Validation-driven retries: If the model returns malformed output, Instructor automatically re-prompts with the validation error as feedback — turning a one-shot gamble into a retry loop with actual signal.
• Provider-agnostic: Works with OpenAI, Anthropic (Claude Sonnet 4.6, Opus 4.6), Google (Gemini 3.1 Pro), Groq, and local models via OpenAI-compatible endpoints — one API across your whole stack.
• First-class async support: AsyncInstructor drops into async FastAPI or worker pipelines with zero friction, and streaming partial models let you start processing before the full response lands.
• Minimal abstraction tax: Unlike LangChain, there’s no new mental model. It’s a thin patch over the client you already use — instructor.from_openai(client) and you’re done.

Quick start

import instructor
from openai import OpenAI
from pydantic import BaseModel

class MovieReview(BaseModel):
    title: str
    sentiment: str  # "positive" | "negative" | "mixed"
    score: float    # 0.0 – 10.0
    summary: str

client = instructor.from_openai(OpenAI())

review = client.chat.completions.create(
    model="gpt-5.4",
    response_model=MovieReview,
    messages=[{"role": "user", "content": "Review: 'Dune 3 was visually stunning but narratively thin.'"}],
)

print(review.score)    # 6.5
print(review.sentiment) # "mixed"

When to use it

• You’re building pipelines that extract structured data (entities, classifications, scores) from unstructured text at scale and need guaranteed schema compliance.
• You want typed outputs without switching to a heavier framework — Instructor composes with your existing OpenAI or Anthropic client rather than replacing it.
• You’re iterating fast on schemas; Pydantic validators let you encode business logic directly into the output contract and get automatic re-prompting when it breaks.

When to skip it

• If your provider natively exposes a JSON schema mode you fully control (e.g., OpenAI’s strict response_format), and your schemas are simple and stable, the raw API plus a thin parsing layer may be sufficient.
• Instructor’s retry logic adds latency and token cost — if you’re running high-throughput, latency-sensitive inference where a failed parse should just fail fast, the retry wrapper works against you.

The verdict

Instructor is the right default for any LLM application that consumes structured data. It threads the needle between raw API calls (brittle) and full orchestration frameworks (heavy), and the Pydantic-native design means your output schemas double as runtime validation and documentation. If you’re still hand-parsing JSON from model outputs in 2026, this is the fix.