Instructor — Structured Outputs for LLMs
by 567-labs
Pydantic models as your LLM's output contract, with validation-driven retries across 15+ providers.
Overview
Instructor is a library for getting validated, typed data out of LLMs by making a Pydantic model the response contract, and its documentation is organised as a progressive curriculum rather than an API reference. The navigation runs Introduction (getting started, installation, architecture, debugging), a Learning path of progressive tutorials, Integrations covering each provider, a Cookbook of practical recipes, Concepts explaining the core patterns, a Prompt Engineering section, a CLI reference and a blog. The core API is deliberately small: instructor.from_provider("openai/gpt-4o-mini") wraps a client, and a normal completion call takes response_model=YourModel plus max_retries, so when the model returns something that fails Pydantic validation the validation error is fed back and the call is retried automatically. Beyond that the docs cover streaming partial objects as they arrive, iterables for extracting lists of records, nested and recursive models, custom validators that encode business rules, and per-provider behaviour — because structured output is implemented differently by each vendor and that is where naive JSON parsing breaks. Supported providers span 15-plus, including OpenAI, Anthropic, Google Gemini, Mistral, Cohere, DeepSeek, Vertex AI, LiteLLM, llama-cpp-python and Ollama for local models, so the same model definition survives a provider switch. The project is MIT-licensed with roughly 13.7k GitHub stars, 1.2k forks and over a thousand contributors, and the README reports more than 3 million monthly downloads. Ports exist for TypeScript, Ruby, Go, Elixir and Rust, which matters if your extraction schema has to be shared across a polyglot service boundary.
At a Glance
- Topic
- Frameworks
- Level
- Intermediate
- Format
- Documentation
- Cost
- Free
- Duration
- ~2-3 hours to work through the Learning path; the Cookbook is reference you return to
- Provider
- 567-labs
- Hands-on
- Yes — code/exercises
- Certificate
- None
What You’ll Learn
- ✓Define a Pydantic response_model that acts as a hard contract on LLM output
- ✓Use max_retries so validation failures self-correct instead of crashing downstream code
- ✓Write custom Pydantic validators that encode business rules the model must satisfy
- ✓Stream partial objects and iterables for responsive UIs and long extraction jobs
- ✓Extract nested and recursive structures without hand-written JSON repair logic
- ✓Swap between OpenAI, Anthropic, Gemini, DeepSeek, Ollama and 10+ more without rewriting schemas
- ✓Debug why a specific provider mangles structured output and pick the right extraction mode
- ✓Apply the documented prompt-engineering patterns that raise extraction accuracy
Highlights
- •Solves the single most common production failure — the model returned almost-JSON — with a pattern rather than a parser
- •Provider-agnostic by design: one Pydantic model works across 15+ providers including local Ollama
- •Documentation is a learning path with a large cookbook, not an autogenerated API dump
- •MIT-licensed with ~13.7k stars, 1000+ contributors and 3M+ monthly downloads, so the integration surface is genuinely maintained
- •Ports to TypeScript, Ruby, Go, Elixir and Rust keep the same schema pattern across a polyglot stack
- •Reads as the practical companion to a provider's own structured-output guide, which only covers that provider
Who It’s For
Best For
- ✓Engineers building extraction, classification or enrichment pipelines on top of LLMs
- ✓Teams that need the same output schema to work across multiple model providers
- ✓Agent developers who want typed, validated tool arguments and results
- ✓Anyone who has written JSON-repair code once and does not want to write it again
Prerequisites
- •Working Python and familiarity with Pydantic models and type hints
- •Experience calling at least one LLM chat completions API
FAQ
What is Instructor — Structured Outputs for LLMs?
Instructor's documentation teaches the pattern most production LLM code eventually converges on: declare a Pydantic model, pass it as response_model, and let validation failures trigger automatic retries instead of writing JSON-repair code by hand. It is written for engineers who need reliable extraction, classification or tool arguments from any provider, and it covers streaming partials, nested objects, validators and the provider-specific quirks that break naive structured output.
Is Instructor — Structured Outputs for LLMs free?
Instructor — Structured Outputs for LLMs is free to access.
What level is Instructor — Structured Outputs for LLMs for?
Instructor — Structured Outputs for LLMs is aimed at a intermediate audience. Recommended background: Working Python and familiarity with Pydantic models and type hints, Experience calling at least one LLM chat completions API.
How long does Instructor — Structured Outputs for LLMs take?
Expect roughly ~2-3 hours to work through the Learning path; the Cookbook is reference you return to. Most learners work through it at their own pace.
What will I learn from Instructor — Structured Outputs for LLMs?
You'll learn: Define a Pydantic response_model that acts as a hard contract on LLM output; Use max_retries so validation failures self-correct instead of crashing downstream code; Write custom Pydantic validators that encode business rules the model must satisfy; Stream partial objects and iterables for responsive UIs and long extraction jobs; Extract nested and recursive structures without hand-written JSON repair logic; Swap between OpenAI, Anthropic, Gemini, DeepSeek, Ollama and 10+ more without rewriting schemas; Debug why a specific provider mangles structured output and pick the right extraction mode; Apply the documented prompt-engineering patterns that raise extraction accuracy.
Topics
Sources
This page was written from 2 sources, 1 on domains other than python.useinstructor.com.