Structured data extraction from LLMs via Pydantic models. Patches or wraps provider clients (OpenAI, Anthropic, Gemini, Cohere, Mistral, Groq, Ollama, and 15+ others) to add response_model, automatic validation, and retry logic. Uses tool-calling or JSON mode depending on provider. Core interface: client.chat.completions.create(response_model=MyModel, ...) returns a validated Pydantic instance. Maintained by Jason Liu / jxnl.
pip install instructorVerified import paths — ran on the pinned version, not inferred.
from_provider() is the 1.x unified interface. For per-provider clients use instructor.from_openai(), instructor.from_anthropic(), etc.
Replace instructor.patch(openai.OpenAI()) with instructor.from_openai(openai.OpenAI()). For Anthropic: instructor.from_anthropic(anthropic.Anthropic()).
Migrate models to Pydantic v2. The @validator decorator is replaced by @field_validator; Config class is replaced by model_config = ConfigDict(...).
Install the appropriate extra for your provider: instructor[anthropic], instructor[google-genai], instructor[groq], instructor[cohere], instructor[mistral], instructor[litellm], etc.
Use prefixed strings: 'openai/gpt-4o', 'anthropic/claude-3-5-sonnet-latest', 'google/gemini-2.0-flash', 'ollama/llama3.2', 'groq/llama-3.1-8b-instant'.
Check the mode comparison table at python.useinstructor.com/modes-comparison/. Pass mode=instructor.Mode.JSON explicitly if the provider doesn't support tool-calling.
Set max_retries=3 or higher for unreliable models. Catch instructor.exceptions.InstructorRetryException explicitly. Simplify schemas to reduce retry rate.
Only access fields after the final yielded object. Use create_iterable() for extracting multiple complete objects instead of partial streaming.
Expected behavior. Do not attempt to uninstall openai when using other providers.
Upgrade your Python environment to version 3.10 or newer.
Set the OPENAI_API_KEY environment variable or pass `api_key` directly to the `openai.OpenAI` client when initializing it for instructor (e.g., `instructor.from_openai(openai.OpenAI(api_key='YOUR_KEY'))`).
Install the library using pip: `pip install instructor`.
Update your code to use `instructor.from_openai(OpenAI())` for OpenAI clients or `instructor.from_provider('your_provider/model_name')` for other providers:
```python
import instructor
from openai import OpenAI
# Old (will cause error)
# client = instructor.patch(OpenAI())
# New way for OpenAI
client = instructor.from_openai(OpenAI())
# Or for other providers, e.g., Anthropic
# import anthropic
# client = instructor.from_provider(anthropic.Anthropic())
```Review your Pydantic model definition for correctness and ensure it accurately reflects the expected output structure. Provide clearer or more specific instructions in your LLM prompt to guide the model towards generating output that matches the schema. You can also inspect `e.failed_attempts` if catching `InstructorRetryException` (or `e` directly if `ValidationError`) for the raw LLM output that caused the failure to debug. Consider simplifying the model or adding more robust Pydantic validators.
Access the original client via `client.client` (e.g., `client.client.moderations.create(...)`) or ensure the method you're trying to call is part of the `chat.completions` API that `instructor` directly enhances. Instructor primarily extends `client.chat.completions.create` to include `response_model`.
Check the specific integration documentation for the LLM provider you are using with `instructor` to understand the expected input format. You might need to manually map your `messages` to the provider's specific content structure (e.g., `contents` for Gemini/Vertex AI) or ensure you're using a compatible `mode` for that provider (e.g., `instructor.Mode.VERTEXAI_TOOLS` or `instructor.Mode.VERTEXAI_JSON`). Ensure your client is initialized with the correct `from_provider` function for the specific LLM.