Instructor
By Instructor (open-source project)
Instructor is an open-source Python library for obtaining structured, validated outputs from large language models by defining the desired response shape as a Pydantic model, then having the library manage prompting, calling the model, and…
Definition
Instructor is an open-source Python library for obtaining structured, validated outputs from large language models by defining the desired response shape as a Pydantic model, then having the library manage prompting, calling the model, and parsing and validating the result into that schema. It focuses narrowly on the structured-output problem rather than broader agent orchestration, and can automatically retry a call with the validation error fed back to the model when the first response does not conform.
Overview
A common difficulty in working with LLMs is getting output in a reliable, machine-parseable format, since models generate free-form text by default and may deviate from a requested schema. Instructor addresses this by letting developers define a Pydantic model describing the fields, types, and validation rules of the desired output, then wrapping an LLM client so that calls automatically request output matching that schema and validate the response against it. When the model's initial output fails validation, Instructor can automatically retry the call, feeding the validation error back to the model so it can correct its response, which improves the reliability of getting well-formed structured data without the developer writing custom parsing or retry logic by hand. This validation-and-retry loop is one of the library's most cited practical benefits. Instructor supports multiple LLM providers by patching their respective client libraries, so the same Pydantic-model-based interface can be used across different underlying models with minimal code changes when switching providers. This has made it a popular lightweight choice for extraction and structured-generation tasks that do not require a full agent framework. Because Instructor is scoped specifically to structured output rather than multi-step orchestration, memory, or tool use, it is often used as a building block within larger applications or frameworks rather than as the sole framework for an entire LLM application. Teams needing broader orchestration typically pair Instructor with another framework or write their own surrounding logic. As an open-source library with a narrow, well-defined scope, Instructor has a comparatively small learning curve for Python developers already familiar with Pydantic, which is part of why it has been widely adopted for structured extraction tasks. Because the retry mechanism sends the original prompt plus the validation error back to the model, each failed validation round adds both latency and token cost, so teams working with strict schemas sometimes tune validation rules to be forgiving enough to reduce unnecessary retries while still catching outputs that would actually break downstream processing. Instructor's provider-patching approach means upgrades to the underlying LLM client libraries can occasionally require corresponding updates to Instructor itself, a minor maintenance consideration compared to writing bespoke parsing code but still a dependency to track. Many teams treat Instructor as a default first choice for structured extraction specifically because its scope is narrow enough to reason about quickly, reserving broader frameworks like LangChain or LlamaIndex for the surrounding retrieval, memory, or multi-step logic that a given application also needs.
Key Features
- Pydantic-model-based definition of desired LLM output schema
- Automatic validation of model output against the defined schema
- Automatic retry with validation error feedback when output fails validation
- Support for multiple LLM providers through client library patching
- Narrow scope focused specifically on structured output extraction
- Minimal learning curve for developers familiar with Pydantic
- Commonly used as a building block within larger LLM applications