The Instructor Library for Structured LLM Output

What Instructor Does

At its core, Instructor solves one problem: getting a typed, validated data object from a language model call. Without Instructor, you define a schema, call the LLM API with that schema, parse the JSON response, validate it against your data model, and handle validation failures with retry logic that feeds the error back to the model. With Instructor, you define a Pydantic model, call Instructor's patched client, and receive a validated Pydantic object. Everything in between, the schema generation, the API call formatting, the response parsing, the validation, and the retry on failure, is handled by the library.

The library works by patching the provider's client object. You take your existing OpenAI, Anthropic, or other provider client and wrap it with instructor.from_openai(client) or instructor.from_anthropic(client). The patched client has the same API as the original, but it accepts a response_model parameter that specifies the Pydantic model you want. The library converts that model to a JSON schema, includes it in the API call (using either structured output or function calling, depending on the provider and configuration), parses the response, validates it through Pydantic, and returns the validated object.

The key feature that distinguishes Instructor from raw structured output is automatic retry with error context. When a response passes the schema constraint (structural validity) but fails Pydantic validation (semantic validity), Instructor catches the validation error, formats it as a clear message, appends it to the conversation, and calls the model again. The model sees its previous response, the specific validation error, and generates a corrected response. This retry loop typically resolves issues in one attempt, because the validation error tells the model exactly what went wrong.

Provider Support

Instructor supports more than 15 LLM providers through a consistent interface. You change the provider by changing the client initialization; the rest of your code stays the same. The supported providers include:

OpenAI: Full support through instructor.from_openai(). Uses native structured output (json_schema) or function calling, depending on the mode you select. Works with GPT-4o, GPT-5, o-series reasoning models, and all OpenAI models that support structured output.

Anthropic: Full support through instructor.from_anthropic(). Uses tool definitions or native structured output. Works with Claude Opus, Sonnet, and Haiku model families.

Google Gemini: Supported through instructor.from_gemini(). Uses the native response_schema parameter.

Open-source models: Supported through Ollama, LiteLLM, Together AI, Groq, Fireworks, and other inference providers. This means you can use Instructor with Llama, Mistral, Qwen, and other open-source models, though the quality of structured output depends on the model's instruction-following capabilities.

Azure OpenAI: Supported through the Azure OpenAI client, which is compatible with the OpenAI patching.

Amazon Bedrock: Supported for Claude and other Bedrock models.

The multi-provider support is one of Instructor's strongest features. You can build your application with a standard interface and switch between providers without changing your schema definitions, validation logic, or response handling. This is valuable for teams that want to evaluate multiple models or need fallback providers when primary providers are unavailable.

Instructor Modes

Instructor supports several modes that control how it communicates the schema to the LLM:

Tool/function calling mode (the original default) sends the schema as a tool definition and extracts the structured response from the tool call parameters. This works with any model that supports function calling, even if it does not support native structured output. The downside is that it is semantically awkward: you are asking the model to "call a tool" when you actually want it to return data.

JSON mode sends the schema in the system prompt and uses JSON mode to ensure valid JSON output. This is the legacy approach that guarantees JSON syntax but not schema compliance. Instructor adds the Pydantic validation layer on top, catching schema violations through retry.

Structured output mode uses the provider's native structured output feature (json_schema with strict: true). This is the recommended mode in 2026, as it provides the strongest guarantee at the infrastructure level and leaves Instructor's retry logic to handle only semantic validation failures.

The mode you choose affects both the reliability of the initial response and the retry rate. Structured output mode has the lowest retry rate because the schema is enforced during generation. Tool calling mode has a moderate retry rate. JSON mode has the highest retry rate because the model may return structurally invalid JSON on the first attempt. For new projects, use structured output mode unless you have a specific reason not to.

Retry Behavior

Instructor's retry behavior is its most valuable feature for production systems. The retry flow works as follows: the initial response is generated by the model and parsed by Instructor. If Pydantic validation passes, the validated object is returned immediately. If validation fails, Instructor formats the validation error as a message (showing which field failed, what the expected constraint was, and what value was received), appends it to the conversation as an assistant/user exchange, and calls the model again. The model sees its previous attempt and the specific error, which gives it enough context to correct the issue.

The default maximum retry count is configurable, typically set to 2-3 retries. In practice, most validation failures resolve on the first retry, because the error message is specific enough for the model to understand what went wrong. A field that must be positive but was returned as -1 is easily corrected. A date that must be in ISO format but was returned as "January 5th" is easily reformatted. The cases that fail even after retries are usually cases where the input genuinely does not contain the requested information, and the model cannot produce a valid value no matter how many times it tries.

You can customize retry behavior by providing a custom retry handler that decides whether to retry, how to format the error message, or whether to fall back to a different model for the retry attempt. Some teams use a cheaper model for the initial attempt and a more capable model for retries, balancing cost against reliability.

When to Use Instructor vs Raw Structured Output

Use raw structured output (direct API calls without Instructor) when you have simple schemas with no semantic validation beyond types and enums, when you want minimal dependencies, or when you are building in a language that Instructor does not support. In these cases, the structured output guarantee from the provider is sufficient, and there is nothing for Instructor to add.

Use Instructor when you need semantic validation beyond schema compliance (range checks, format checks, cross-field validation), when you want automatic retry on validation failure, when you want a multi-provider interface that lets you switch between OpenAI, Anthropic, and other providers without changing your schema code, or when you want the ergonomic convenience of defining schemas as Pydantic models and receiving validated Python objects.

For most production Python applications, Instructor is worth the dependency. The automatic retry alone justifies it: even a model that gets it right 95% of the time will fail thousands of times per day in a high-volume system, and automatic retry turns those failures into invisible latency bumps instead of broken records. The fact that it also provides a clean multi-provider interface and reduces boilerplate is a bonus.

Instructor and Memory Systems

Instructor is particularly useful in AI memory systems where structured extraction happens at every stage. When a conversation produces new knowledge that should be stored, the memory system needs to extract entities, relationships, and facts in a specific schema. Instructor handles this extraction reliably: define a Pydantic model for a memory record (entity name, entity type, relationship, confidence score, source context), pass the conversation to the model with that response_model, and receive validated memory records ready for storage.

Adaptive Recall uses this pattern for knowledge extraction from conversations, where the model identifies facts worth remembering, extracts them in a structured format with confidence scores, and the memory system stores them. The structured output guarantee ensures that every extracted fact has the required fields, and Pydantic validation ensures the confidence scores are in the valid range and the entity types match the known taxonomy. Without this two-layer validation, the memory system would need defensive code at every insertion point, which adds complexity and maintenance burden.