Skip to content

Migration Guide

This guide helps you migrate from older Instructor patterns to from_provider, the recommended approach for all providers.

Why Migrate?

  • Simpler code: Less boilerplate, easier to read
  • Consistent interface: Same pattern works for all providers
  • Better type safety: Improved IDE support
  • Future-proof: Recommended pattern going forward

Quick Reference

Old Pattern New Pattern
instructor.patch(openai.OpenAI()) instructor.from_provider("openai/model")
instructor.apatch(openai.AsyncOpenAI()) instructor.from_provider("openai/model", async_client=True)
from_openai(client) instructor.from_provider("openai/model")
from_anthropic(client) instructor.from_provider("anthropic/model")
from_genai(client) instructor.from_provider("google/model")
client.chat.completions.create(...) client.create(...)
client.messages.create(...) client.create(...)

Basic Migration

Before:

import openai
import instructor
from pydantic import BaseModel


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


openai_client = openai.OpenAI()
client = instructor.patch(openai_client)

user = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=User,
    messages=[{"role": "user", "content": "Extract: John is 30"}],
)

After:

import instructor
from pydantic import BaseModel


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


client = instructor.from_provider("openai/gpt-4o-mini")

user = client.create(
    response_model=User,
    messages=[{"role": "user", "content": "Extract: John is 30"}],
)

Async Migration

Before:

import openai
import instructor

openai_client = openai.AsyncOpenAI()
client = instructor.apatch(openai_client)

user = await client.chat.completions.create(...)

After:

import instructor

client = instructor.from_provider("openai/gpt-4o-mini", async_client=True)

user = await client.create(...)

Provider-Specific Migrations

Anthropic

# Before (removed)
import anthropic
from instructor import from_anthropic

client = from_anthropic(anthropic.Anthropic())
user = client.messages.create(model="claude-3-5-sonnet", ...)

# After
client = instructor.from_provider("anthropic/claude-3-5-sonnet")
user = client.create(...)

Google/Gemini

# Before (removed)
import google.genai as genai
from instructor import from_genai

client = from_genai(genai.Client(), model="gemini-pro")
user = client.generate_content(...)

# After
client = instructor.from_provider("google/gemini-pro")
user = client.create(messages=[...])

Configuration Options

Pass configuration directly to from_provider:

import instructor

# Mode configuration
client = instructor.from_provider("openai/gpt-4o-mini", mode=instructor.Mode.JSON)

# Custom API settings
client = instructor.from_provider(
    "openai/gpt-4o-mini",
    api_key="custom-key",
    organization="org-id",
    timeout=30.0,
)

Multiple Providers

Before:

import openai
import anthropic
import instructor
from instructor import from_anthropic

openai_client = instructor.patch(openai.OpenAI())
anthropic_client = from_anthropic(anthropic.Anthropic())

After:

import instructor

openai_client = instructor.from_provider("openai/gpt-4o-mini")
anthropic_client = instructor.from_provider("anthropic/claude-3-5-sonnet")

Migration Checklist

  1. Identify your current pattern: patch(), apatch(), or from_*() functions
  2. Find your model name: e.g., gpt-4o-mini, claude-3-5-sonnet
  3. Replace client creation: Use from_provider("provider/model")
  4. Update method calls: Change to client.create(...)
  5. Use standard message format: [{"role": "user", "content": "..."}]
  6. Test your code

Troubleshooting

Error Cause Solution
'Instructor' object has no attribute 'chat' Using old method call Use client.create() instead of client.chat.completions.create()
Invalid model string Wrong format Use "provider/model-name" format
Message format error Provider-specific format Use standard messages list format

Backward Compatibility

Legacy helpers have been removed:

  • instructor.patch() → Use from_provider instead
  • instructor.apatch() → Use from_provider with async_client=True
  • from_openai(), from_anthropic(), etc. → Use from_provider

Update all call sites before upgrading.

See Also