Instructor

Instructor is the most popular Python library for extracting structured, validated data from Large Language Models, transforming unreliable text outputs into type-safe Python objects through Pydantic model definitions. With over 3 million monthly downloads and 11,000+ GitHub stars, it has become the de facto standard for reliable LLM output processing in production applications.\n\nBuilt on Pydantic's validation framework, Instructor patches LLM client libraries to add a responsemodel parameter that defines the expected output structure. When you call client.create(responsemodel=MyModel, ...), Instructor automatically handles function-calling schema generation, response parsing, validation, and intelligent retry logic when the LLM output doesn't match the specified schema.\n\nThe library's core innovation lies in its automatic retry mechanism with validation feedback. When Pydantic validation fails, Instructor feeds specific error messages back to the LLM and retries the request. This feedback loop enables models to self-correct, achieving 99%+ success rates even with complex schemas that would otherwise fail frequently.\n\nInstructor supports 15+ LLM providers through its unified fromprovider() interface, including OpenAI, Anthropic, Google Gemini, Mistral, Cohere, DeepSeek, Ollama, and local models. This provider-agnostic approach prevents vendor lock-in and enables easy A/B testing across different models for specific extraction tasks without code changes.\n\nAdvanced features include streaming partial objects where Pydantic fields populate incrementally as the LLM generates tokens, iterable responses for extracting lists of objects, union types for classification tasks, and custom validators with arbitrary logic. Multiple extraction modes (TOOLS, JSON, MDJSON, PARALLEL) optimize for different model capabilities and use cases.\n\nThe library's focused scope as an extraction tool rather than a full agent framework is intentional. Instructor excels at the specific problem of getting reliable structured data from single LLM calls without the complexity of agent loops, tool calling, or conversation management. For complete agent workflows, the Instructor team recommends complementary tools like PydanticAI.\n\nCompared to alternatives, Instructor sits between raw function calling (which requires manual JSON parsing and error handling) and heavy agent frameworks. It provides more reliability than raw OpenAI function calls through validation and retries, but remains simpler than LangChain or other comprehensive frameworks by focusing solely on structured extraction.\n\nInstructor has expanded beyond Python with official ports to TypeScript, Go, Ruby, Elixir, and Rust, maintaining consistent APIs across languages. This multi-language support enables teams to use the same extraction patterns across different technology stacks while preserving the benefits of type safety and validation.\n\nCompanies using Instructor include teams at OpenAI, Google, Microsoft, AWS, and numerous Y Combinator startups. The library's production-ready status is evidenced by its extensive test suite, comprehensive documentation, and active community of 100+ contributors maintaining integrations and examples.