### Setup and Installation

Source: https://python.useinstructor.com/integrations/writer

Configure the API key and install the necessary Python package.

```bash
export WRITER_API_KEY=<your-api-key-here>
pip install "instructor[writer]"
```

--------------------------------

### Complete Implementation Example

Source: https://python.useinstructor.com/blog/2024/09/14/why-should-i-use-prompt-caching

A consolidated view of the full implementation including imports and setup.

```python
from instructor import Instructor, Mode, patch
from anthropic import Anthropic
from pydantic import BaseModel

client = Instructor(
    client=Anthropic(),
    create=patch(
        create=Anthropic().beta.prompt_caching.messages.create,
        mode=Mode.TOOLS,
    ),
    mode=Mode.TOOLS,
)


class Character(BaseModel):
    name: str
    description: str


with open("./book.txt") as f:
    book = f.read()

for _ in range(2):
```

--------------------------------

### Manually Setup Provider Client

Source: https://python.useinstructor.com/integrations?q=

Install dependencies and manually patch a provider client for use with Instructor.

```bash
pip install "instructor[provider]"  # e.g., instructor[anthropic]
```

```python
import instructor
from provider_package import Client

client = instructor.from_provider(Client())
```

```python
response = client.create(
    response_model=YourModel,
    messages=[{"role": "user", "content": "Your prompt"}]
)
```

--------------------------------

### Install Instructor with Google Generative AI Support

Source: https://python.useinstructor.com/blog/page/4

Installs the Instructor library with dependencies for the Google Generative AI SDK. Recommended for easier setup and a free daily token quota.

```bash
pip install "instructor[google-generativeai]"

```

--------------------------------

### Verify Instructor Setup with OpenAI Example

Source: https://python.useinstructor.com/learning/getting_started/installation

A Python example demonstrating Instructor's ability to extract structured data using Pydantic models and an OpenAI model.

```python
import instructor
from pydantic import BaseModel

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

client = instructor.from_provider("openai/gpt-5-nano")
person = client.create(
    model="gpt-3.5-turbo",
    response_model=Person,
    messages=[
        {"role": "user", "content": "John Doe is 30 years old"}
    ]
)

print(f"Name: {person.name}, Age: {person.age}")

```

--------------------------------

### Install Instructor

Source: https://python.useinstructor.com/

Install the Instructor library using pip, uv, or poetry.

```bash
pip install instructor

```

```bash
uv add instructor

```

```bash
poetry add instructor

```

--------------------------------

### Setup Async Client and Data Models with Instructor

Source: https://python.useinstructor.com/blog/2023/11/13/learn-async

Initializes an asynchronous Instructor client and defines a Pydantic BaseModel for data extraction. Ensure the 'instructor' library and 'pydantic' are installed.

```python
import instructor
from pydantic import BaseModel

# Set up the async client with Instructor
client = instructor.from_provider("openai/gpt-5-nano", async_client=True)


class Person(BaseModel):
    name: str
    age: int
    occupation: str


async def extract_person(text: str) -> Person:
    """Extract person information from text using LLM."""
    return await client.create(
        model="gpt-4o-mini",
        response_model=Person,
        messages=[{"role": "user", "content": f"Extract person info: {text}"}]
    )


# Sample dataset
dataset = [
    "John Smith is a 30-year-old software engineer",
    "Sarah Johnson is a 25-year-old data scientist",
    "Mike Davis is a 35-year-old product manager",
    "Lisa Wilson is a 28-year-old UX designer",
    "Tom Brown is a 32-year-old DevOps engineer",
    "Emma Garcia is a 27-year-old frontend developer",
    "David Lee is a 33-year-old backend developer",
]
```

--------------------------------

### Install Instructor

Source: https://python.useinstructor.com/getting-started

Install the Instructor library using pip. For specific providers, install with extras.

```bash
pip install instructor
```

```bash
pip install "instructor[anthropic]"
```

```bash
pip install "instructor[google-genai]"         # For Google/Gemini
```

```bash
pip install "instructor[vertexai]"             # For Vertex AI
```

```bash
pip install "instructor[cohere]"               # For Cohere
```

```bash
pip install "instructor[litellm]"              # For LiteLLM (multiple providers)
```

```bash
pip install "instructor[mistralai]"            # For Mistral
```

```bash
pip install "instructor[xai]"                  # For xAI
```

--------------------------------

### Install Instructor Dependencies

Source: https://python.useinstructor.com/tutorials?q=

Standard installation command for the Instructor library with all optional dependencies.

```bash
pip install "instructor[all]"
```

--------------------------------

### Install Instructor with LiteLLM

Source: https://python.useinstructor.com/examples/watsonx?q=

Install the necessary dependencies using poetry.

```bash
poetry install instructor --with litellm
```

--------------------------------

### Setup Instructor Client and Prefix

Source: https://python.useinstructor.com/prompting/decomposition/program_of_thought

Initializes the instructor client and defines a prefix for generated Python code. This prefix ensures that the generated code starts with specific comments and structure.

```python
from pydantic import BaseModel, Field, field_validator
import instructor
from textwrap import dedent
from typing import Literal
client = instructor.from_provider("openai/gpt-5-nano")

prefix = """
# Answer this question by implementing a solver()
# function, use for loop if necessary.
def solver():
    # Let's write a Python program step by step,
    # and then return the answer
    # Firstly, we need to define the following
    # variable:
""".strip()
```

--------------------------------

### Install Instructor

Source: https://python.useinstructor.com/getting-started?q=

Install the core Instructor library using pip. For specific LLM providers, install optional extras.

```bash
pip install instructor

```

```bash
# For Anthropic
pip install "instructor[anthropic]"

```

```bash
# For other providers
pip install "instructor[google-genai]"         # For Google/Gemini
pip install "instructor[vertexai]"             # For Vertex AI
pip install "instructor[cohere]"               # For Cohere
pip install "instructor[litellm]"              # For LiteLLM (multiple providers)
pip install "instructor[mistralai]"            # For Mistral
pip install "instructor[xai]"                  # For xAI

```

--------------------------------

### Install Instructor with Writer Support

Source: https://python.useinstructor.com/blog/category/writer-sdk

Install the instructor library with specific support for Writer's LLMs. Ensure you have Python and pip installed.

```bash
pip install instructor[writer]
```

--------------------------------

### Install instructor dependencies

Source: https://python.useinstructor.com/blog/2024/09/03/structured-outputs-for-gemini-now-supported

Install the necessary packages for Gemini or VertexAI integration.

```bash
pip install "instructor[google-generativeai]"
```

```bash
pip install "instructor[vertexai]"
```

--------------------------------

### Install Instructor Dependencies

Source: https://python.useinstructor.com/integrations/truefoundry?q=

Install the necessary libraries for Instructor, OpenAI, and Pydantic.

```bash
pip install instructor openai pydantic
```

--------------------------------

### Install Instructor

Source: https://python.useinstructor.com/installation?q=

Use this command to install the Instructor library using pip. Ensure you have Python 3.9+ and pip installed.

```bash
pip install instructor

```

--------------------------------

### Install Project Dependencies

Source: https://python.useinstructor.com/blog/2023/11/05/chain-of-density

Install the required packages for the Instructor project.

```bash
pip install instructor aiohttp rich
```

--------------------------------

### Instructor Error Message Example

Source: https://python.useinstructor.com/learning/validation/retry_mechanisms

Example of detailed error feedback provided to the LLM during retries to guide correction.

```text
The following errors occurred during validation:
- price: ensure this value is greater than 0
- name: Product name must be at least 3 characters

Please fix these errors and ensure the response is valid.

```

--------------------------------

### Install Instructor and Anthropic

Source: https://python.useinstructor.com/blog/2025/05/07/using-anthropics-web-search-with-instructor-for-real-time-data

Install the necessary libraries for using Instructor with Anthropic's models. This is a prerequisite for the following code examples.

```bash
uv add instructor anthropic

```

--------------------------------

### Run Instructor Tutorials Locally

Source: https://python.useinstructor.com/tutorials?q=

Commands to clone the repository, install dependencies in editable mode, and launch the tutorial notebooks.

```bash
git clone https://github.com/jxnl/instructor.git
cd instructor
pip install -e ".[all]"
jupyter notebook docs/tutorials/
```

--------------------------------

### OpenAI Provider Example

Source: https://python.useinstructor.com/

Example of using Instructor with OpenAI's GPT models. Ensure you have the instructor library installed and configured for OpenAI.

```python
import instructor
from pydantic import BaseModel


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


client = instructor.from_provider("openai/gpt-5-nano")
res = client.create(
    response_model=ExtractUser,
    messages=[{"role": "user", "content": "John Doe is 30 years old."}]
)

```

--------------------------------

### Install Instructor Dependencies

Source: https://python.useinstructor.com/blog/archive/2024/page/3

Run this command to install the necessary dependencies before proceeding with the tutorial on writing emails with URLs from Instructor docs.

```bash
pip install instructor
```

--------------------------------

### Implement Complete Instructor Example

Source: https://python.useinstructor.com/contributing

A standard example showing imports, model definition, client patching, and usage.

```python
# Complete example with imports
import instructor
from pydantic import BaseModel
# Define your model
class Person(BaseModel):
    name: str
    age: int

# Create the patched client
client = instructor.from_provider("openai/gpt-5-nano")

# Use the model
person = client.create(
    model="gpt-3.5-turbo",
    response_model=Person,
    messages=[
        {"role": "user", "content": "Extract: John Doe is 25 years old"}
    ]
)

print(person.name)  # "John Doe"
print(person.age)   # 25

```

--------------------------------

### Generate Users with Pydantic Field Examples

Source: https://python.useinstructor.com/blog/page/5?q=

Leverage Pydantic's `Field` with `examples` to guide synthetic data generation. This helps in producing more specific and varied outputs.

```python
from typing import Iterable
from pydantic import BaseModel, Field
import instructor


# Define the UserDetail model
class UserDetail(BaseModel):
    name: str = Field(examples=["Timothee Chalamet", "Zendaya"])
    age: int


# Patch the OpenAI client to enable the response_model functionality
client = instructor.from_provider("openai/gpt-5-nano")


def generate_fake_users(count: int) -> Iterable[UserDetail]:
    return client.create(
        model="gpt-3.5-turbo",
        response_model=Iterable[UserDetail],
        messages=[
            {"role": "user", "content": f"Generate a {count} synthetic users"},
        ],
    )


for user in generate_fake_users(5):
    print(user)
    #\n    #> name='John Doe' age=25
    #> name='Alice Smith' age=30
    #> name='Bob Johnson' age=28
    #> name='Emily Brown' age=35
    #> name='Michael Williams' age=27
```

--------------------------------

### Basic Instructor Client Setup

Source: https://python.useinstructor.com/blog/2024/09/07/pydantic-is-still-all-you-need?q=

Initialize an Instructor client with OpenAI. This is the standard setup for using structured outputs with OpenAI models.

```python
from instructor import from_openai

client = from_openai(OpenAI())

response = client.create(model="gpt-3.5-turbo", response_model=User, messages=[...])

```

--------------------------------

### Install Project with UV

Source: https://python.useinstructor.com/contributing

Clones the Instructor repository and installs it in development mode with development and documentation dependencies using UV.

```bash
# Clone the repository
git clone https://github.com/YOUR-USERNAME/instructor.git
cd instructor

# Install with development dependencies
uv pip install -e ".[dev,docs]"
```

--------------------------------

### Basic Instructor Client Setup

Source: https://python.useinstructor.com/examples/self_critique

Initializes the instructor client with a specified model. This setup enables the use of the `response_model` keyword for structured output.

```python
from pydantic import BaseModel
import instructor

# Apply the patch to the OpenAI client
# enables response_model keyword
client = instructor.from_provider("openai/gpt-4.1-mini")


class QuestionAnswer(BaseModel):
    question: str
    answer: str


question = "What is the meaning of life?"
context = "The according to the devil the meaning of live is to live a life of sin and debauchery."

qa: QuestionAnswer = client.create(
    response_model=QuestionAnswer,
    messages=[
        {
            "role": "system",
            "content": "You are a system that answers questions based on the context. answer exactly what the question asks using the context.",
        },
        {
            "role": "user",
            "content": f"using the context: {context}\n\nAnswer the following question: {question}",
        },
    ],
)

```

--------------------------------

### Quick start with auto client

Source: https://python.useinstructor.com/integrations/ollama?q=

Initializes an Instructor client for Ollama with default settings.

```python
import instructor
from pydantic import BaseModel

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

# Simple setup - automatically configured for Ollama
client = instructor.from_provider("ollama/llama2")

resp = client.create(
    messages=[{"role": "user", "content": "Tell me about Harry Potter"}],
    response_model=Character,
)
```

--------------------------------

### Generate Synthetic Users with Field Examples

Source: https://python.useinstructor.com/blog/2024/03/08/simple-synthetic-data-generation

Leverage Pydantic's Field `examples` to guide synthetic data generation with specific, well-known names. This provides more control over the style of generated data.

```python
from typing import Iterable
from pydantic import BaseModel, Field
import instructor


# Define the UserDetail model
class UserDetail(BaseModel):
    name: str = Field(examples=["Timothee Chalamet", "Zendaya"])
    age: int


# Patch the OpenAI client to enable the response_model functionality
client = instructor.from_provider("openai/gpt-5-nano")


def generate_fake_users(count: int) -> Iterable[UserDetail]:
    return client.create(
        model="gpt-3.5-turbo",
        response_model=Iterable[UserDetail],
        messages=[
            {"role": "user", "content": f"Generate a {count} synthetic users"},
        ],
    )


for user in generate_fake_users(5):
    print(user)
    #> name='John Doe' age=25
    #> name='Alice Smith' age=30
    #> name='Bob Johnson' age=28
    #> name='Emily Brown' age=35
    #> name='Michael Williams' age=27

```

--------------------------------

### Groq Structured Output Example

Source: https://python.useinstructor.com/examples/groq

Use Groq for inference with structured outputs by defining a Pydantic model and using instructor's `from_provider` for simplified setup. This example demonstrates generating facts about Tesla.

```python
from pydantic import BaseModel, Field
from typing import List
import instructor


class Character(BaseModel):
    name: str
    fact: List[str] = Field(..., description="A list of facts about the subject")


# Use from_provider for simplified setup
client = instructor.from_provider("groq/mixtral-8x7b-32768", mode=instructor.Mode.TOOLS)

resp = client.create(
    model="mixtral-8x7b-32768",
    messages=[
        {
            "role": "user",
            "content": "Tell me about the company Tesla",
        }
    ],
    response_model=Character,
)
print(resp.model_dump_json(indent=2))
```

--------------------------------

### Client Setup for LLM Providers

Source: https://python.useinstructor.com/start-here

Illustrates how to initialize the Instructor client for different LLM providers using the `from_provider` function. This function abstracts away provider-specific configurations.

```python
# For OpenAI
client = instructor.from_provider("openai/gpt-4o-mini")

```

```python
# For Anthropic
client = instructor.from_provider("anthropic/claude-3-5-haiku-latest")

```

```python
# For Google Gemini
client = instructor.from_provider("google/gemini-3-flash")

```

--------------------------------

### List Type Response

Source: https://python.useinstructor.com/concepts/types?q=

Obtain a list of items as a response. This example shows how to get a list of integers, such as prime numbers.

```python
import instructor
from typing import List

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

resp = client.create(
    response_model=List[int],
    messages=[
        {
            "role": "user",
            "content": "Give me the first 5 prime numbers",
        },
    ],
)

assert resp == [2, 3, 5, 7, 11]
print(resp)
```

--------------------------------

### Install Instructor Locally

Source: https://python.useinstructor.com/tutorials

Clone the Instructor repository and install the package with all dependencies to run tutorials locally.

```bash
git clone https://github.com/jxnl/instructor.git
cd instructor
pip install -e "[all]"
jupyter notebook docs/tutorials/
```

--------------------------------

### Full FastAPI Application with Asyncio

Source: https://python.useinstructor.com/blog/2024/05/03/fastapi-open-telemetry-and-instructor

A complete example including FastAPI setup, Pydantic models, and instrumentation with logfire and instructor.

```python
from pydantic import BaseModel
from fastapi import FastAPI
import instructor
import logfire
import asyncio


class UserData(BaseModel):
    query: str


class MultipleUserData(BaseModel):
    queries: list[str]


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


app = FastAPI()
openai_client = AsyncOpenAI()
logfire.configure(pydantic_plugin=logfire.PydanticPlugin(record="all"))
logfire.instrument_openai(openai_client)
logfire.instrument_fastapi(app)
client = instructor.from_provider("openai/gpt-4o")


@app.post("/user", response_model=UserDetail)
async def endpoint_function(data: UserData) -> UserDetail:
    user_detail = await client.create(
        model="gpt-3.5-turbo",
        response_model=UserDetail,
        messages=[
            {"role": "user", "content": f"Extract: `{data.query}`"},
        ],
    )
    logfire.info("/User returning", value=user_detail)
    return user_detail


@app.post("/many-users", response_model=list[UserDetail])
async def extract_many_users(data: MultipleUserData):
    async def extract_user(query: str):
        user_detail = await client.create(
            model="gpt-3.5-turbo",
            response_model=UserDetail,
            messages=[
                {"role": "user", "content": f"Extract: `{query}`"},
            ],
        )
        logfire.info("/User returning", value=user_detail)
        return user_detail

    coros = [extract_user(query) for query in data.queries]
    return await asyncio.gather(*coros)
```

--------------------------------

### Example Chapter JSON Output

Source: https://python.useinstructor.com/blog/2024/07/11/youtube-transcripts

Illustrative JSON output for an extracted chapter, showing the structure with start timestamp, end timestamp, title, and summary.

```json
{
  "start_ts": 0.0,
  "end_ts": 30.0,
  "title": "Introduction and Topic Overview",
  "summary": "Introduction to the video, outlining the main topic of discussion."
}
```

```json
{
  "start_ts": 31.0,
  "end_ts": 60.0,
  "title": "Background Information",
  "summary": "Background information relevant to the topic."
}
```

```json
{
  "start_ts": 61.0,
  "end_ts": 120.0,
  "title": "Key Concept Explanation",
  "summary": "Detailed explanation of the key concepts."
}
```

```json
{
  "start_ts": 121.0,
  "end_ts": 165.0,
  "title": "Critical Analysis",
  "summary": "Analysis and discussion of the critical aspects of the topic."
}
```

```json
{
  "start_ts": 166.0,
  "end_ts": 210.0,
  "title": "Examples and Case Studies",
  "summary": "Presentation of examples and case studies related to the topic."
}
```

```json
{
  "start_ts": 211.0,
  "end_ts": 240.0,
  "title": "Conclusion and Final Thoughts",
  "summary": "Conclusion of the video with final thoughts on the topic."
}
```

```json
{
  "start_ts": 9.72,
  "end_ts": 65.6,
  "title": "Understanding Language Models",
  "summary": "Explains the code-first approach to using language models, suggesting prerequisites such as prior deep learning knowledge and recommends the course.fast.ai for in-depth learning."
}
```

```json
{
  "start_ts": 65.6,
  "end_ts": 250.68,
  "title": "Basics of Language Models",
  "summary": "Covers the concept of language models, demonstrating how they predict the next word in a sentence, and showcases OpenAI's text DaVinci for creative brainstorming with examples."
}
```

```json
{
  "start_ts": 250.68,
  "end_ts": 459.199,
  "title": "How Language Models Work",
  "summary": "Dives deeper into how language models like ULMfit and others were developed, their training on datasets like Wikipedia, and the importance of learning various aspects of the world to predict the next word effectively."
}
```

--------------------------------

### Structured Outputs with Cerebras Inference

Source: https://python.useinstructor.com/blog/archive/2024/page/2

Example demonstrating how to get guaranteed structured outputs with Cerebras Inference. Sign up for a Cerebras Inference API key at cloud.cerebras.ai.

```python
import instructor
from cerebras.sdk.inference import InferenceClient
from pydantic import BaseModel

class StructuredOutput(BaseModel):
    field1: str
    field2: int

client = instructor.from_cerebras(InferenceClient())

response = client.chat.completions.create(
    model="your-cerebras-model",
    response_model=StructuredOutput,
    messages=[
        {
            "role": "user",
            "content": "Generate structured output.",
        }
    ],
)

print(response.field1)
```

--------------------------------

### Migrate to Google GenAI SDK (Recommended)

Source: https://python.useinstructor.com/integrations/vertex

Shows the recommended way to initialize the Instructor client using the Google GenAI SDK, replacing the deprecated `from_vertexai` method. Option 1 uses `from_provider` for simplicity, while Option 2 uses `from_genai` with an explicit `genai.Client`.

```python
import instructor

# Option 1: Using from_provider (simplest)
client = instructor.from_provider(
    "vertexai/gemini-3-flash",
    project="your-project",  # Optional if set in environment
    location="us-central1"   # Optional, defaults to us-central1
)

# Option 2: Using from_genai with Google GenAI SDK
from google import genai
from instructor import from_genai

client = from_genai(
    genai.Client(
        vertexai=True,
        project="your-project",
        location="us-central1",
        model="gemini-3-flash"
    )
)

```

--------------------------------

### Configure Core Modes

Source: https://python.useinstructor.com/modes-comparison?q=

Examples of initializing the Instructor client with different core modes for structured output.

```python
import instructor
from instructor import Mode

client = instructor.from_provider(
    "openai/gpt-4o-mini",
    mode=Mode.TOOLS,
)
```

```python
import instructor
from instructor import Mode

client = instructor.from_provider(
    "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0",
    mode=Mode.MD_JSON,
)
```

```python
import instructor
from instructor import Mode

client = instructor.from_provider(
    "openai/gpt-4o-mini",
    mode=Mode.JSON_SCHEMA,
)
```

--------------------------------

### Basic Instructor Usage

Source: https://python.useinstructor.com/tutorials/6-chain-of-density.ipynb

Demonstrates the fundamental way to use the instructor library to get a response from an LLM. Ensure you have the 'openai' library installed and an API key configured.

```python
from openai import OpenAI
import instructor

# Initialize the OpenAI client
client = OpenAI()

# Wrap the client with instructor
instructor_client = instructor.patch(client)

# Define a Pydantic model for the response
class User(instructor.BaseModel):
    name: str
    age: int

# Make a call to the LLM to get a structured response
user = instructor_client.chat.completions.create(
    model="gpt-4o",
    response_model=User,
    messages=[
        {"role": "user", "content": "Extract the name and age from the user: John Doe is 30 years old."}
    ],
)

print(user.name, user.age)
```

--------------------------------

### Initialize Clients for Different Providers

Source: https://python.useinstructor.com/blog/2024/04/01/announce-instructor-v1

Demonstrates initializing clients for various providers including OpenAI, Anthropic, and using `litellm`. These clients can all be used with the `create` method.

```python
import openai
import anthropic
import litellm
import instructor
from typing import TypeVar

T = TypeVar("T")

# These are all ways to create a client
client = instructor.from_provider("openai/gpt-5-nano")
client = instructor.from_provider("anthropic/claude-3-5-haiku-latest")
client = instructor.from_litellm(litellm.completion)

# all of these will route to the same underlying create function
# allow you to add instructor to try it out, while easily removing it
client.create(model="gpt-4", response_model=type[T]) -> T
client.create(model="gpt-4", response_model=type[T]) -> T
client.messages.create(model="gpt-4", response_model=type[T]) -> T

```

--------------------------------

### Initialize Instructor Clients with Various Cache Adapters

Source: https://python.useinstructor.com/blog/page/2

Demonstrates initializing Instructor clients with AutoCache and DiskCache for different providers like OpenAI, Anthropic, and Google. No provider-specific configuration is needed.

```python
from instructor.cache import AutoCache, DiskCache

# Works with OpenAI
openai_client = from_provider("openai/gpt-5-nano", cache=AutoCache())

# Works with Anthropic
anthropic_client = from_provider("anthropic/claude-3-haiku", cache=AutoCache())

# Works with Google
google_client = from_provider("google/gemini-pro", cache=DiskCache())

# Works with any provider in the ecosystem
groq_client = from_provider("groq/llama-3.1-8b", cache=AutoCache())
```

--------------------------------

### Install Instructor with Groq Support

Source: https://python.useinstructor.com/integrations/groq

Install the Instructor library with Groq support using pip. Ensure you have your Groq API key set as an environment variable.

```bash
export GROQ_API_KEY=<your-api-key-here>
pip install "instructor[groq]"
```

--------------------------------

### Custom Redis Cache Implementation

Source: https://python.useinstructor.com/blog/category/cost-reduction?q=

Provides a custom `RedisCache` implementation by inheriting from `BaseCache`. This example shows how to integrate with Redis for caching, including `get` and `set` methods with optional TTL.

```python
from instructor.cache import BaseCache
import redis


class RedisCache(BaseCache):
    def __init__(self, host="localhost", port=6379, **kwargs):
        self.redis = redis.Redis(host=host, port=port, **kwargs)

    def get(self, key: str):
        value = self.redis.get(key)
        return value.decode() if value else None

    def set(self, key: str, value, ttl: int | None = None):
        if ttl:
            self.redis.setex(key, ttl, value)
        else:
            self.redis.set(key, value)

```

--------------------------------

### Initialize Instructor Async Client

Source: https://python.useinstructor.com/examples/bulk_classification

Sets up the instructor client with OpenAI provider and async support enabled.

```python
import instructor

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

--------------------------------

### System Messages with GenAI and Instructor

Source: https://python.useinstructor.com/integrations/genai?q=

Illustrates how to provide system messages to set context and instructions for Gemini models when using Instructor. This example shows the basic setup for client initialization.

```python
from google import genai
import instructor
from pydantic import BaseModel


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


client = instructor.from_provider("google/gemini-2.5-flash")


```

--------------------------------

### Generate Intermediate Reasoning

Source: https://python.useinstructor.com/prompting/decomposition/program_of_thought

Function to generate intermediate reasoning by calling the instructor client. It uses a system prompt to guide the AI in generating a valid Python program that starts with a specific prefix and a user query.

```python
def generate_intermediate_reasoning(query: str):
    return client.create(
        model="gpt-4o",
        messages=[
            {
                "role": "system",
                "content": dedent(
                    f"""
                You are a world class AI system that excels
                at answering user queries in a systematic
                and detailed manner. You are about to be
                passed a user query to respond to. Make sure
                to generate a valid program that can be
                executed to answer the user query.

                Make sure to begin your generated program
                with the following prefix

                {prefix}
                """
                ),
            },
            {
                "role": "user",
                "content": query,
            },
        ],
        response_model=ProgramExecution,
    )
```

--------------------------------

### Demonstrate Instructor with OpenAI and Anthropic Clients

Source: https://python.useinstructor.com/blog/page/5?q=

This example shows how to use the `instructor.from_provider` method to initialize clients for both OpenAI and Anthropic. It includes setting up a Pydantic model for structured output and demonstrates asynchronous calls for the Anthropic client. Ensure the ANTHROPIC_API_KEY environment variable is set for the Anthropic part to work.

```python
import os
import asyncio
import instructor
from pydantic import BaseModel, Field


class UserInfo(BaseModel):
    """User information extraction model."""

    name: str = Field(description="The user's full name")
    age: int = Field(description="The user's age in years")
    occupation: str = Field(description="The user's job or profession")


async def main():
    # Test OpenAI
    openai_client = instructor.from_provider("openai/gpt-5-nano")
    openai_result = openai_client.create(
        response_model=UserInfo,
        messages=[{"role": "user", "content": "Jane Doe is a 28-year-old data scientist."}]
    )
    print(f"OpenAI result: {openai_result.model_dump()}")

    # Test Anthropic with async client
    if os.environ.get("ANTHROPIC_API_KEY"):
        anthropic_client = instructor.from_provider(
            model="anthropic/claude-3-5-haiku-latest",
            async_client=True,
            max_tokens=400,  # Required for Anthropic
        )
        anthropic_result = await anthropic_client.create(
            response_model=UserInfo,
            messages=[
                {
                    "role": "user",
                    "content": "John Smith is a 35-year-old software engineer.",
                }
            ],
        )
        print(f"Anthropic result: {anthropic_result.model_dump()}")


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Parallel LLM Response Generation with Instructor

Source: https://python.useinstructor.com/prompting/decomposition/skeleton_of_thought

Implement Skeleton-of-Thought for parallel LLM response generation. This involves getting a skeleton outline and then expanding each point in parallel using `asyncio`. Ensure the instructor library is installed and configured.

```python
import instructor
from pydantic import BaseModel
import asyncio
client = instructor.from_provider("openai/gpt-5-nano", async_client=True)


class Point(BaseModel):
    index: int
    description: str


class Skeleton(BaseModel):
    points: list[Point]


class Response(BaseModel):
    response: str


async def get_skeleton(question):
    return await client.create(
        model="gpt-4o",
        response_model=Skeleton,
        messages=[
            {
                "role": "user",
                "content": f"""
You’re an organizer responsible for only giving the skeleton (not the full content) for answering the question.
Provide the skeleton in a list of points (numbered 1., 2., 3., etc.) to answer the question.
Instead of writing a full sentence, each skeleton point should be very short with only 3∼5 words.
Generally, the skeleton should have 3∼10 points.

Now, please provide the skeleton for the following question.

<question>
{question}
</question>

Skeleton:
""",
            }
        ],
    )


async def expand_point(question, skeleton, point_index):
    return await client.create(
        model="gpt-4o",
        response_model=Response,
        messages=[
            {
                "role": "user",
                "content": f"""
You’re responsible for continuing the writing of one and only one point in the overall answer to the following question.

<question>
{question}
</question>

The skeleton of the answer is:

<skeleton>
{skeleton}
</skeleton>

Continue and only continue the writing of point {point_index}.
Write it **very shortly** in 1∼2 sentence and do not continue with other points!
""",
            }
        ],
    )


async def main():
    query = "Compose an engaging travel blog post about a recent trip to Hawaii, highlighting cultural experiences and must-see attractions."

    # Step 1: Get the skeleton
    skeleton = await get_skeleton(query)

    for point in skeleton.points:
        print(point)
        #> index=1 description='Introduction to Hawaii trip'
        #> index=2 description='Arrival and first impressions'
        #> index=3 description='Traditional Hawaiian cuisine'
        #> index=4 description='Exploring local markets'
        #> index=5 description='Visit to historic sites'
        #> index=6 description='Experience a Hawaiian luau'
        #> index=7 description='Day at the beach'
        #> index=8 description='Hiking adventures'
        #> index=9 description='Scenic viewpoints'
        #> index=10 description='Closing remarks and tips'

    # Step 2: Expand on each point in parallel
    tasks = [expand_point(query, skeleton, point.index) for point in skeleton.points]
    responses = await asyncio.gather(*tasks)

    for response in responses:
        print(response.response)
        """
        Hawaii-a paradise of golden beaches, lush landscapes, and vibrant culture-beckoned us with the promise of adventure and unforgettable experiences. Our journey began the moment we landed on this magical archipelago, ready to explore its unique blend of natural beauty and rich traditions.
        """
        """
        The moment we landed in Hawaii, we were greeted with warm aloha spirit, lush tropical landscapes, and the gentle aroma of hibiscus flowers in the air.
        """
        """
        The traditional Hawaiian cuisine was an exotic delight; from savoring the rich flavors of poke bowls to indulging in the sweet taste of haupia, every bite was a unique cultural experience.
        """
        """
        Exploring local markets was a vibrant and delightful experience, where the air was filled with the scent of exotic fruits, freshly-made poke, and sounds of local musicians. We discovered unique handicrafts and interacted with friendly vendors eager to share their stories and traditions.
        """
        """
        A visit to Pearl Harbor is a poignant reminder of the past, offering a chance to pay respects and learn about the events that shaped history. Walking through the USS Arizona Memorial and exploring the interactive exhibits was both humbling and enlightening.
        """
        
```

--------------------------------

### Using TOOLS Mode with AWS Bedrock Client

Source: https://python.useinstructor.com/integrations/bedrock

Configure the Instructor client to use the `TOOLS` mode for AWS Bedrock, which leverages function calling for models that support it. This example shows simplified setup using `from_provider`.

```python
import boto3
import instructor
from instructor import Mode
from pydantic import BaseModel

# Use from_provider for simplified setup
client = instructor.from_provider("bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0", mode=Mode.TOOLS)

# Or if you need to use a custom boto3 client:
# bedrock_client = boto3.client('bedrock-runtime')
# client = instructor.from_provider("bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0", client=bedrock_client, mode=Mode.TOOLS)

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


```

--------------------------------

### Install Instructor with uv

Source: https://python.useinstructor.com/?q=

Use uv to add the Instructor library to your project dependencies.

```bash
uv add instructor

```

--------------------------------

### Initialize Instructor Client and Create Response

Source: https://python.useinstructor.com/concepts/unions

Demonstrates initializing the Instructor client with a provider and executing a request with a response model.

```python
client = instructor.from_provider("openai/gpt-4o")
response = client.create(
    response_model=Response,
    messages=[{"role": "user", "content": "Tell me a joke about programming."}],
)
```

--------------------------------

### Example Usage of Redis Caching Decorator

Source: https://python.useinstructor.com/concepts/caching?q=

Demonstrates how to apply the `instructor_cache` decorator to a function that extracts user details using an AI client and returns a Pydantic model. This setup is beneficial for distributed systems requiring fast data access.

```python
import redis
import functools
import inspect
import instructor

from pydantic import BaseModel

client = instructor.from_provider("openai/gpt-4.1-mini")
cache = redis.Redis("localhost")


def instructor_cache(func):
    """Cache a function that returns a Pydantic model"""
    return_type = inspect.signature(func).return_annotation
    if not issubclass(return_type, BaseModel):  # 
        raise ValueError("The return type must be a Pydantic model")

    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        key = f"{func.__name__}-{functools._make_key(args, kwargs, typed=False)}"  # 
        # Check if the result is already cached
        if (cached := cache.get(key)) is not None:
            # Deserialize from JSON based on the return type
            return return_type.model_validate_json(cached)

        # Call the function and cache its result
        result = func(*args, **kwargs)
        serialized_result = result.model_dump_json()
        cache.set(key, serialized_result)

        return result

    return wrapper


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


@instructor_cache
def extract(data) -> UserDetail:
    # Assuming client.chat.completions.create returns a UserDetail instance
    return client.create(
        response_model=UserDetail,
        messages=[
            {"role": "user", "content": data},
        ],
    )


```

--------------------------------

### Configure LLM providers

Source: https://python.useinstructor.com/start-here?q=

Examples of initializing the Instructor client for different LLM providers using the from_provider method.

```python
# For OpenAI
client = instructor.from_provider("openai/gpt-4o-mini")

# For Anthropic
client = instructor.from_provider("anthropic/claude-3-5-haiku-latest")

# For Google Gemini
client = instructor.from_provider("google/gemini-3-flash")
```

--------------------------------

### OpenAI API Model Distillation with Instructor

Source: https://python.useinstructor.com/blog/archive/2024/page/2

Explores leveraging OpenAI's API Model Distillation feature with Instructor's structured output capabilities to create more efficient and specialized models. This example is conceptual and requires specific setup for distillation.

```python
import instructor
from openai import OpenAI
from pydantic import BaseModel

class DistilledTaskOutput(BaseModel):
    summary: str
    keywords: list[str]

# Assume 'client' is configured for API Model Distillation
# This is a conceptual example, actual distillation setup is more involved.
client = instructor.from_openai(OpenAI())

# In a real scenario, you would use a distilled model endpoint
# response = client.chat.completions.create(
#     model="your-distilled-model-name",
#     response_model=DistilledTaskOutput,
#     messages=[
#         {
#             "role": "user",
#             "content": "Process the following document for summary and keywords.",
#         }
#     ],
# )

# print(response.summary)

```

--------------------------------

### Quick Start: Distilling Python Functions with Instructor

Source: https://python.useinstructor.com/blog/2023/10/17/enhancing-python-functions-with-instructor-a-guide-to-fine-tuning-and-distillation?q=

Use the `@instructions.distil` decorator to automatically generate a dataset for fine-tuning. The decorated function must return a Pydantic model to leverage function calling. This example sets up logging to save the data to a file.

```python
import logging
import random
from pydantic import BaseModel
from instructor import Instructions  # pip install instructor

# Logging setup
logging.basicConfig(level=logging.INFO)

instructions = Instructions(
    name="three_digit_multiply",
    finetune_format="messages",
    # log handler is used to save the data to a file
    # you can imagine saving it to a database or other storage
    # based on your needs!
    log_handlers=[logging.FileHandler("math_finetunes.jsonl")],
)


class Multiply(BaseModel):
    a: int
    b: int
    result: int


# Define a function with distillation
# The decorator will automatically generate a dataset for fine-tuning
# They must return a pydantic model to leverage function calling
@instructions.distil
def fn(a: int, b: int) -> Multiply:
    resp = a * b
    return Multiply(a=a, b=b, result=resp)


# Generate some data
for _ in range(10):
    a = random.randint(100, 999)
    b = random.randint(100, 999)
    print(fn(a, b))
    #> a=268 b=548 result=146864
    #> a=774 b=447 result=345978
    #> a=154 b=902 result=138908
    #> a=304 b=808 result=245632
    #> a=980 b=104 result=101920
    #> a=725 b=455 result=329875
    #> a=206 b=386 result=79516
    #> a=488 b=920 result=448960
    #> a=989 b=889 result=879221
    #> a=815 b=343 result=279545

```

--------------------------------

### Basic Migration: After

Source: https://python.useinstructor.com/concepts/migration

Shows the new `from_provider` pattern for creating an Instructor client for OpenAI and making a request.

```python
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"}],
)

```

--------------------------------

### Quick Start: Distilling a Python Function for Fine-Tuning

Source: https://python.useinstructor.com/concepts/distillation

This example demonstrates how to set up Instructor to distill a Python function into a fine-tuning dataset. It configures logging to save the data in JSONL format and defines a Pydantic model for the function's output. The `@instructions.distil` decorator automatically handles dataset generation.

```python
import logging
import random
from pydantic import BaseModel

# Logging setup
logging.basicConfig(level=logging.INFO)

from instructor import Instructions, FinetuneFormat  # pip install instructor

instructions = Instructions(
    name="three_digit_multiply",
    finetune_format=FinetuneFormat.MESSAGES,  # or FinetuneFormat.RAW
    # log handler is used to save the data to a file
    # you can imagine saving it to a database or other storage
    # based on your needs!
    log_handlers=[logging.FileHandler("math_finetunes.jsonl")],
)


class Multiply(BaseModel):
    a: int
    b: int
    result: int


# Define a function with distillation
# The decorator will automatically generate a dataset for fine-tuning
# They must return a pydantic model to leverage function calling
@instructions.distil
def fn(a: int, b: int) -> Multiply:
    resp = a * b
    return Multiply(a=a, b=b, result=resp)


# Generate some data
for _ in range(10):
    random.seed(42)
    a = random.randint(100, 999)
    b = random.randint(100, 999)
    print(fn(a, b))
```