instructor: Extract Validated Structured Data from LLMs

Overview

Instructor is a Python library for requesting structured data from large language models and validating the result against Pydantic models. It addresses the gap between free-form model responses and application code that expects typed, schema-conforming values.

It suits developers building extraction or classification workflows who want provider flexibility and less custom response parsing. Its focus is schema-first structured outputs rather than general-purpose agent orchestration.

Key Features

• Define desired output with Pydantic models and receive validated, typed objects.
• Use a consistent client interface across supported providers, including OpenAI, Anthropic, Google, Ollama, and Groq.
• Retry responses when validation fails, with configurable retry limits.
• Stream partial objects while a response is being generated.
• Represent nested data structures using model fields.
• Configure provider API keys directly or through environment variables.

Use Cases

• Data extraction: Turn emails, documents, or user messages into typed records for downstream processing.
• Classification pipelines: Return validated categories and attributes instead of parsing free-form text.
• Form and record enrichment: Populate nested application data from natural-language input, with validation constraints.
• Incremental user interfaces: Show partially extracted fields as they arrive through streaming.
• Provider-flexible applications: Keep a schema-oriented calling pattern when trying supported model providers.

Project Facts

• Language: Python
• License: MIT
• Stars: 14k
• Forks: 1.3k
• Topics: openai, openai-function-calli, openai-functions, pydantic-v2, python, validation
• Archived: No

Getting Started

Install with:

pip install instructor

See the README and Python documentation for provider setup and usage details.

Considerations

• This is a Python library and requires using a supported model provider or configuring a local provider such as Ollama.
• Structured results depend on model responses and provider capabilities. Validation and retries help handle failures, but do not guarantee that extracted information is factually correct.
• The project focuses on structured outputs. Applications needing broader agent workflows may want a dedicated agent framework.
• The repository has 136 open issues, so review current issues and documentation when evaluating fit.