Instructor
Patches LLM clients (OpenAI, Anthropic, Gemini, Cohere, etc.) to return validated Pydantic model instances instead of raw text, with automatic retry on validation failure.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
No network surface; secrets are passed to underlying provider SDKs. Dependency chain includes openai, anthropic, and pydantic — review transitive deps for supply-chain risk.
⚡ Reliability
Best When
You already use OpenAI/Anthropic SDKs and need Pydantic-validated structured outputs with minimal boilerplate and automatic retry logic.
Avoid When
You need guaranteed schema adherence without any LLM retry budget, or when operating at token-level generation constraints.
Use Cases
- • Extracting structured data (entities, dates, relations) from unstructured text with guaranteed schema compliance
- • Building agent pipelines that require typed, validated outputs at each reasoning step
- • Classifying inputs into enum-typed categories with LLM-backed confidence
- • Parsing LLM tool-call responses into strongly-typed Python dataclasses for downstream processing
- • Streaming partial structured responses for real-time UI updates while maintaining type safety
Not For
- • Applications requiring token-level constraint enforcement (use Outlines instead)
- • Non-Python environments or teams wanting a REST API rather than a library
- • Scenarios where LLM provider function-calling / tool-use is unavailable or unsupported
Interface
Authentication
Library — auth via underlying LLM provider credentials (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.).
Pricing
Open source MIT. LLM provider API costs apply separately.
Agent Metadata
Known Gotchas
- ⚠ max_retries default is 1 — agents that need guaranteed output must explicitly set higher values or handle InstructorRetryException
- ⚠ Streaming partial models via Iterable[Model] returns incomplete instances mid-stream; agents must not act on partial data
- ⚠ Provider-patching is mutable global state — patching the same client twice with different modes silently overwrites the first patch
- ⚠ Anthropic and Gemini backends use slightly different function-calling schemas; switching providers may require Pydantic model adjustments
- ⚠ Large Pydantic models with many optional fields can exhaust token budgets on repeated retry attempts — set strict field counts
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for Instructor.
Scores are editorial opinions as of 2026-03-06.