Instructor

Warnings

• breaking instructor.patch() removed in 1.0.0. All pre-1.0 code using instructor.patch(openai.OpenAI()) breaks with AttributeError.
  Fix: Replace instructor.patch(openai.OpenAI()) with instructor.from_openai(openai.OpenAI()). For Anthropic: instructor.from_anthropic(anthropic.Anthropic()).
• breaking Pydantic v1 not supported. instructor requires Pydantic v2.
  Fix: Migrate models to Pydantic v2. The @validator decorator is replaced by @field_validator; Config class is replaced by model_config = ConfigDict(...).
• breaking Provider-specific extras required for non-OpenAI backends. Using instructor.from_anthropic() without pip install 'instructor[anthropic]' raises ImportError.
  Fix: Install the appropriate extra for your provider: instructor[anthropic], instructor[google-genai], instructor[groq], instructor[cohere], instructor[mistral], instructor[litellm], etc.
• breaking from_provider() requires 'provider/model' string format. Bare model names raise ValueError.
  Fix: 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'.
• gotcha Each provider uses a different default Mode (tool-calling vs JSON). Anthropic uses ANTHROPIC_TOOLS by default; OpenAI uses TOOLS. Mixing providers without checking mode compatibility causes silent output degradation or errors.
  Fix: 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.
• gotcha max_retries controls validation retry attempts, not HTTP retries. Default is 1 retry on Pydantic validation failure. Complex schemas with small models frequently exhaust retries silently and raise InstructorRetryException.
  Fix: Set max_retries=3 or higher for unreliable models. Catch instructor.exceptions.InstructorRetryException explicitly. Simplify schemas to reduce retry rate.
• gotcha Streaming with create_partial() returns Partial[T] objects where fields are None until generated. Accessing fields before the stream completes returns None — not an error.
  Fix: Only access fields after the final yielded object. Use create_iterable() for extracting multiple complete objects instead of partial streaming.
• gotcha openai is a required dependency even when using non-OpenAI providers (Anthropic, Gemini, etc.). This is by design — instructor proxies through OpenAI's interface structure.
  Fix: Expected behavior. Do not attempt to uninstall openai when using other providers.

Install

• pip install instructor Base (OpenAI only)
• pip install 'instructor[anthropic]' Anthropic
• pip install 'instructor[google-genai]' Google Gemini
• pip install 'instructor[groq]' Groq
• pip install 'instructor[litellm]' LiteLLM (any provider)

Imports

• from_openai

  import instructor; import openai; client = instructor.from_openai(openai.OpenAI())

  instructor.patch() removed in 1.0.0. Replace with instructor.from_openai(). The patched client is now a proper wrapper, not a monkey-patch.
• from_provider

  import instructor; client = instructor.from_provider('openai/gpt-4o')

  from_provider() requires provider-prefixed model strings in 'provider/model' format. Bare model names like 'gpt-4o' raise errors — must be 'openai/gpt-4o', 'anthropic/claude-3-5-sonnet', 'ollama/llama3.2', etc.

Quickstart

from_provider() is the 1.x unified interface. For per-provider clients use instructor.from_openai(), instructor.from_anthropic(), etc.

import instructor
from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int

# Unified provider interface (1.x recommended)
client = instructor.from_provider('openai/gpt-4o-mini')

user = client.chat.completions.create(
    response_model=User,
    messages=[{'role': 'user', 'content': 'John is 25 years old'}],
)
print(user)  # User(name='John', age=25)