Instructor

https://python.useinstructor.com
Admin
Instructor is a multi-language library for extracting structured data from Large Language Models...
Tokens:328,460
Snippets:2,913
Trust Score:6.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### 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]"
```

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

### Install and initialize native caching

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

Quick start guide for upgrading, selecting a backend, and initializing the client.

```bash
pip install "instructor>=1.9.1"
```

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

# For development/single-process
cache = AutoCache(maxsize=1000)

# For persistence
cache = DiskCache(directory=".cache")
```

```python
from instructor import from_provider

client = from_provider("your/favorite/model", cache=cache)
```

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

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

### Manual Client Setup

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

Steps for manually installing dependencies, patching a provider client, and executing a request.

```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]"

```

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

### 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
```

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

### 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 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/
```

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

### Install Dependencies

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

Install the necessary SDKs for LangSmith and Instructor.

```bash
pip install -U langsmith
pip install -U instructor
```

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

### Installing Instructor

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

Command to install the necessary dependencies for structured output extraction.

```bash
pip install instructor pydantic
```

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

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

```

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

### 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]
```

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

### Verify Instructor Installation

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

A basic example demonstrating structured data extraction using a Pydantic 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-5.4-mini",
    response_model=Person,
    messages=[
        {"role": "user", "content": "John Doe is 30 years old"}
    ]
)

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

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

### Install Project with UV

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

Clone the repository and install development 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]"
```

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

### 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]"
```

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

### Install Instructor with VertexAI Support

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

Installs the Instructor library with dependencies for the VertexAI SDK. Requires a credentials.json file or OAuth integration for authentication.

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

```

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

### Install Instructor with Provider Support

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

Installation commands for specific LLM providers.

```bash
pip install "instructor[anthropic]"  # For Anthropic
pip install "instructor[google-generativeai]"  # For Google/Gemini
```

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

### Install Instructor with LiteLLM

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

Install the necessary package to enable LiteLLM support in Instructor.

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

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

### Install Instructor

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

Install the instructor library using pip. This is the only dependency required for basic usage.

```bash
pip install "instructor"
```

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

### Install Instructor for Cohere

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

Install the necessary dependencies to use Cohere with Instructor.

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

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

### Quick Start with Ollama Auto Client

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

Sets up a basic Instructor client for Ollama, automatically configuring it for the specified model. This is a simple way to start generating structured outputs.

```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,
)

```

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

### Install Instructor and Pydantic

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

Standard installation commands for the core library and its required dependency.

```bash
pip install instructor
```

```bash
pip install pydantic
```

```bash
uv pip install instructor
```

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

### Install Dependencies

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

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

```bash
pip install instructor openai pydantic

```

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

### Install Instructor with Bedrock Support

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

Install the Instructor library with the necessary dependencies for AWS Bedrock integration.

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

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

### Install and Configure Perplexity API

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

Set the API key environment variable and install the necessary instructor package with perplexity support.

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

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

### Install Required Packages

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

Install the necessary Python packages for using Groq with instructor. This includes instructor, groq, pydantic, openai, and anthropic.

```bash
pip install instructor groq pydantic openai anthropic

```

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

### Generate In-Context Examples with Instructor

Source: https://python.useinstructor.com/prompting/few_shot/example_generation/sg_icl

Implement SG-ICL by generating examples for prompts using the Instructor library. This involves defining Pydantic models for responses and using a client to create structured outputs.

```python
import instructor
from pydantic import BaseModel
from typing import Literal
n = 4  # num examples to generate per class


class GeneratedReview(BaseModel):
    review: str
    sentiment: Literal["positive", "negative"]


class SentimentPrediction(BaseModel):
    sentiment: Literal["positive", "negative"]


client = instructor.from_provider("openai/gpt-5-nano")


def generate_sample(input_review, sentiment):
    return client.create(
        model="gpt-4o",
        response_model=GeneratedReview,
        messages=[
            {
                "role": "user",
                "content": f"""
                           Generate a '{sentiment}' review similar to: {input_review}
                           Generated review:
                           """,
            }
        ],
    )

def predict_sentiment(input_review, in_context_samples):
    return client.create(
        model="gpt-4o",
        response_model=SentimentPrediction,
        messages=[
            {
                "role": "user",
                "content": "".join(
                    [
                        f"Review: {sample.review}\nSentiment: {sample.sentiment}\n\n"
                        for sample in in_context_samples
                    ]
                )
                + f"Review: {input_review}\nSentiment:",
            }
        ],
    ).sentiment


if __name__ == "__main__":
    input_review = (
        "This movie was a rollercoaster of emotions, keeping me engaged throughout."
    )

    # Generate in-context samples
    samples = [
        generate_sample(input_review, sentiment)
        for sentiment in ('positive', 'negative')
        for _ in range(n)
    ]
    for sample in samples:
        print(sample)
        
```

```python
review='This film was an enthralling experience from start to finish, leaving me captivated every moment.' sentiment='positive'
```

```python
review='This film was an emotional journey that captivated me from start to finish.' sentiment='positive'
```

```python
review='The film took me on an unforgettable journey, capturing my attention at every moment.' sentiment='positive'
```

```python
review='This book was a riveting journey, capturing my attention from start to finish.' sentiment='positive'
```

```python
review='The movie was a total letdown, failing to hold my interest from start to finish.' sentiment='negative'
```

```python
review='This movie was a disjointed mess of emotions, leaving me confused throughout.' sentiment='negative'
```

```python
review='The movie was an emotional rollercoaster, but it left me feeling more confused than engaged.' sentiment='negative'
```

```python
review='This movie was a monotonous ride, failing to engage me at any point.' sentiment='negative'
```

```python
review='This film was an emotional journey, captivating me from start to finish.' sentiment='positive'
```

```python
review='This film captivated me from start to finish with its thrilling plot and emotional depth.' sentiment='positive'
```

```python
review='This movie was a breathtaking journey, capturing my attention from start to finish.' sentiment='positive'
```

```python
review='This movie was a chaotic mess of emotions, losing me at every turn.' sentiment='negative'
```

```python
review='This movie was a confusing mess, leaving me disengaged throughout.' sentiment='negative'
```

```python
review='This movie was a chore to sit through, leaving me bored most of the time.' sentiment='negative'
```

```python
review='This movie was a mishmash of confusing scenes, leaving me frustrated throughout.' sentiment='negative'
```

```python
# Predict sentiment
    print(predict_sentiment(input_review, samples))
    #> positive
```

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

### Leverage field-level examples for synthetic data

Source: https://python.useinstructor.com/blog/category/pydantic

Use Pydantic Field examples to guide the generation of specific data patterns.

```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-5.4-mini",
        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
```

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

### Configure Cohere Provider

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

Installation and environment variable setup for Cohere models.

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

```bash
export COHERE_API_KEY=your_cohere_key
```

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

### Create Instructor Client via from_provider

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

Demonstrates basic client initialization, enabling caching, and creating asynchronous clients.

```python
>>> import instructor
>>> from instructor.cache import AutoCache
>>>
>>> # Basic usage
>>> client = instructor.from_provider("openai/gpt-4")
>>> client = instructor.from_provider("anthropic/claude-3-sonnet")
>>>
>>> # With caching
>>> cache = AutoCache(maxsize=1000)
>>> client = instructor.from_provider("openai/gpt-4", cache=cache)
>>>
>>> # Async clients
>>> async_client = instructor.from_provider("openai/gpt-4", async_client=True)
```

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

### Configure OpenAI Provider

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

Installation and environment variable setup for OpenAI models.

```bash
pip install instructor
```

```bash
export OPENAI_API_KEY=your_openai_key
```

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

### Provider Initialization Examples

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

Quick reference strings for initializing various supported LLM providers.

```python
instructor.from_provider("openai/gpt-5-nano")
instructor.from_provider("anthropic/claude-3-sonnet")
instructor.from_provider("google/gemini-2.5-flash")
instructor.from_provider("mistral/mistral-large-latest")
instructor.from_provider("cohere/command-r")
instructor.from_provider("perplexity/sonar-small")
instructor.from_provider("groq/llama3-8b-8192")
instructor.from_provider("writer/palmyra-x-004")
instructor.from_provider("bedrock/anthropic.claude-3-sonnet-20240229-v1:0")
instructor.from_provider("cerebras/llama3.1-70b")
instructor.from_provider("fireworks/llama-v3-70b-instruct")
instructor.from_provider("vertexai/gemini-3-flash")
instructor.from_provider("genai/gemini-3-flash")
instructor.from_provider("ollama/llama3.2")
```

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

### Configure Mistral Provider

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

Installation and environment variable setup for Mistral AI models.

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

```bash
export MISTRAL_API_KEY=your_mistral_key
```

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

### 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")

```

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

### Configure Anthropic Claude Provider

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

Installation and environment variable setup for Anthropic models.

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

```bash
export ANTHROPIC_API_KEY=your_anthropic_key
```

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

### 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 Google Gemini Provider

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

Installation and environment variable setup for Google Gemini models.

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

```bash
export GOOGLE_API_KEY=your_google_key
```

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

### Initialize Instructor Client

Source: https://python.useinstructor.com/tutorials/3-0-applications-rag.ipynb

Sets up the instructor client using the OpenAI provider for structured output generation.

```python
import instructor

from openai import OpenAI
from pydantic import BaseModel, Field

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

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

### 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))
```

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

### Initialize Instructor with OpenAI Client

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

Demonstrates creating a synchronous Instructor client using the from_openai factory with different modes.

```python
>>> import openai
>>> from instructor import Mode
>>> from instructor.v2.providers.openai import from_openai
>>>
>>> client = openai.OpenAI()
>>> instructor_client = from_openai(client, mode=Mode.TOOLS)
>>>
>>> # Or use JSON_SCHEMA mode for structured outputs
>>> instructor_client = from_openai(client, mode=Mode.JSON_SCHEMA)
```

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

### 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)
```

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

### 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,
    )
```

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

### 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


```

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

### Initialize Instructor clients with from_provider

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

Compares the legacy manual patching method with the recommended from_provider approach.

```python
# Old way (still works, but more verbose)
import openai
import instructor

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

# New way (recommended)
client = instructor.from_provider("openai/gpt-4o-mini")
```

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

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

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

### 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.
        """
        
```

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

### 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))
```

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

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

```

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

### Initialize and use a client with from_provider

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

Demonstrates creating an Instructor client for a specific provider and model, then using it to extract structured data into a Pydantic model.

```python
import instructor
from pydantic import BaseModel


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


# Create a client for any provider
client = instructor.from_provider("openai/gpt-4o-mini")
# Or: instructor.from_provider("anthropic/claude-3-5-sonnet")
# Or: instructor.from_provider("google/gemini-2.5-flash")

# Use the client as usual
user = client.create(
    response_model=User,
    messages=[{"role": "user", "content": "Extract: John is 30 years old"}],
)
```

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

### Example Usage: KNN for Effective Example Selection

Source: https://python.useinstructor.com/prompting/few_shot/exemplar_selection/knn

Demonstrates the complete workflow of selecting effective in-context examples using KNN. It embeds examples and a query, finds the closest examples, formats them, and generates a final response.

```python
if __name__ == "__main__":
    examples = [
        {"question": "What is the capital of France?", "answer": "Paris"},
        {"question": "Who wrote Romeo and Juliet", "answer": "Shakespeare"},
        {"question": "What is the capital of Germany?", "answer": "Berlin"},
    ]

    query = "What is the capital of Italy?"

    # Step 1 : Embed the Examples
    embeddings = embed_queries([example["question"] for example in examples] + [query])

    embedded_examples = embeddings[:-1]
    embedded_query = embeddings[-1]

    # # Step 3: Find the k closest examples to the query
    k_closest_examples = knn(embedded_examples, embedded_query[0], 2)

    for example in k_closest_examples:
        print(example)
        #> (0.4013468481736857, 'What is the capital of France?')
        #> (0.4471368596136872, 'What is the capital of Germany?')

    # Step 4: Use these examples as in-context examples
    formatted_examples = generate_question_and_answer_pair(
        [example[1] for example in k_closest_examples], examples
    )
    response = generate_response(formatted_examples, query)
    print(response.answer)
    #> Rome
```

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

### Quick Start: Initialize Client and Create Structured Output

Source: https://python.useinstructor.com/integrations/openai-responses

Initializes the Instructor client with a specific model and mode, defines a Pydantic model for the response, and creates a structured output from a text input.

```python
import instructor
from pydantic import BaseModel

# Initialize the client
client = instructor.from_provider(
    "openai/gpt-4.1-mini", mode=instructor.Mode.RESPONSES_TOOLS
)


# Define your response model
class User(BaseModel):
    name: str
    age: int


# Create structured output
profile = client.responses.create(
    input="Extract out Ivan is 28 years old",
    response_model=User,
)

print(profile)
#> name='Ivan' age=28

```

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

### Conventional Commit Examples

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

Common examples of conventional commit messages.

```text
feat(openai): add streaming response support

fix(anthropic): resolve tool calling response format

docs: update installation instructions

test(evals): add new recursive schema test cases

```

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

### Multiple Providers: After

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

Demonstrates the unified `from_provider` method for initializing clients for different services like OpenAI and Anthropic.

```python
import instructor

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

```

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

### Install Project with Poetry

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

Clone the repository and install dependencies using Poetry.

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

# Install with development dependencies
poetry install --with dev,docs
```

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

### Setting Up Environment for Multimodal Gemini with Instructor

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

This snippet shows the necessary imports for setting up an environment to use Google's Gemini model with Instructor for analyzing travel videos and extracting structured recommendations. Ensure these libraries are installed before proceeding.

```python
from instructor import OpenAISchema
from pydantic import BaseModel, Field
from typing import List
import google.generativeai as genai

# Configure the generative AI client with your API key
genai.configure(api_key="YOUR_API_KEY")

# Define a Pydantic model for structured output
class Recommendation(BaseModel):
    name: str = Field(description="The name of the place or activity")
    description: str = Field(description="A brief description of the recommendation")
    tags: List[str] = Field(description="Keywords associated with the recommendation")

# Define a Pydantic model for the overall response
class Recommendations(BaseModel):
    recommendations: List[Recommendation]

# Load the multimodal model
model = genai.GenerativeModel('gemini-pro-vision')

# Create an Instructor client for the Gemini model
client = instructor.from_gemini(model, mode=instructor.Mode.TOOLS)

# Example usage (replace with actual video analysis logic)
# response = client.chat.completions.create(
#     model="gemini-pro-vision",
#     response_model=Recommendations,
#     messages=[
#         {
#             "role": "user",
#             "content": [
#                 {
#                     "type": "text",
#                     "text": "Analyze this video and provide travel recommendations."
#                 },
#                 {
#                     "type": "image_url",
#                     "image_url": {
#                         "url": "URL_TO_YOUR_VIDEO_FRAME_OR_THUMBNAIL"
#                     }
#                 }
#             ]
#         }
#     ]
# )

# print(response.json())

```

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

### Install Poetry

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

Install the Poetry dependency manager via the official script.

```bash
curl -sSL https://install.python-poetry.org | python3 -
```

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

### Install required packages

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

Install the necessary dependencies to use Instructor with Databricks.

```bash
uv pip install instructor openai
```

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

### Conventional Comment Examples

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

Examples of using conventional comment labels for code reviews.

```text
suggestion: use a validator for this field
This would ensure the value is always properly formatted.

question: why not use async processing here?
I'm curious if this would improve performance.

fix: correct the parameter type
It should be an OpenAI client instance, not a string.

```

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

### Install Instructor CLI

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

The CLI tools are bundled with the main Instructor package.

```bash
pip install instructor
```

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

### Install Instructor for Anthropic

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

Install the necessary package to enable Anthropic support in Instructor.

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

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

### Implement Demonstration Ensembling with Instructor

Source: https://python.useinstructor.com/prompting/ensembling/dense

Uses the instructor library to partition examples into batches, generate self-consistent responses, and aggregate the results using a Counter.

```python
import instructor
from pydantic import BaseModel
import asyncio
from collections import Counter
from typing import Literal
from textwrap import dedent

class DemonstrationResponse(BaseModel):
    correct_answer: Literal["Positive", "Negative", "Neutral"]


client = instructor.from_provider("openai/gpt-5-nano", async_client=True)


async def generate_self_consistent_response(prompt: str, examples: list[str]):
    concetenated_examples = "\n".join(examples)
    return await client.create(
        model="gpt-4o",
        messages=[
            {
                "role": "system",
                "content": dedent(
                    f"""
                You are an intelligent AI System that excels
                at classifying user queries into three
                possible labels:
                - Positive
                - Negative
                - Neutral

                You are about to be given a user query and
                asked to classify it into one of the three
                categories. Make sure to refer closely to
                the examples provided to you, examining each
                individual example before coming up with the
                final answer.

                Here are the examples:
                {concetenated_examples}
                """
                ),
            },
            {"role": "user", "content": prompt},
        ],
        response_model=DemonstrationResponse,
        temperature=0,
    )


async def generate_self_consistent_responses(
    prompt: str, num_responses: int, examples: list[str]
):
    assert (
        len(examples) % num_responses == 0
    ), "The number of examples must be evenly divisible by num_responses"

    # Batch the examples into num_responses batches
    batch_size = len(examples) // num_responses

    coros = [
        generate_self_consistent_response(prompt, examples[i : i + batch_size])
        for i in range(0, len(examples), batch_size)
    ]

    responses = await asyncio.gather(*coros)
    return responses


if __name__ == "__main__":
    user_query = "What is the weather like today?"
    examples = [
        "I love this product! [Positive]",
        "This is the worst service ever. [Negative]",
        "The movie was okay, not great but not terrible. [Neutral]",
        "I'm so happy with my new phone! [Positive]",
        "The food was terrible and the service was slow. [Negative]",
        "It's an average day, nothing special. [Neutral]",
        "Fantastic experience, will come again! [Positive]",
        "I wouldn't recommend this to anyone. [Negative]",
        "The book was neither good nor bad. [Neutral]",
        "Absolutely thrilled with the results! [Positive]",
    ]
    responses = asyncio.run(generate_self_consistent_responses(user_query, 5, examples))
    answer_counts = Counter([response.correct_answer for response in responses])
    most_common_answer, _ = answer_counts.most_common(1)[0]
    print(most_common_answer)
    #> Neutral
```

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

### Install Instructor Mistral package

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

Install the necessary dependencies to use Instructor with Mistral.

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

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

### Initializing Bedrock Clients with Latest Models

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

Provides examples of initializing Instructor clients for various modern foundation models available on AWS Bedrock, including Claude 3.5, Amazon Nova, Meta Llama 3, and Mistral.

```python
import instructor

# Claude 3.5 models (latest)
client = instructor.from_provider("bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0")
# or
client = instructor.from_provider("bedrock/anthropic.claude-3-5-haiku-20241022-v1:0")

# Amazon Nova models (multimodal)
client = instructor.from_provider("bedrock/amazon.nova-micro-v1:0")

# Meta Llama 3 models
client = instructor.from_provider("bedrock/meta.llama3-70b-instruct-v1:0")

# Mistral models
client = instructor.from_provider("bedrock/mistral.mistral-large-2402-v1:0")

```

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

### View CLI Help for Batch Creation

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

Displays the available options and usage for the create-from-file command.

```bash
$ instructor batch create-from-file --help

 Usage: instructor batch create-from-file [OPTIONS]

 Create a batch job from a file

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --file-path                                  TEXT  File containing the    │
│                                                       batch job requests     │
│                                                       [default: None]        │
│                                                       [required]             │
│    --model                                      TEXT  Model in format        │
│                                                       'provider/model-name'  │
│                                                       (e.g., 'openai/gpt-5.4-mini', │
│                                                       'anthropic/claude-3-s… │
│                                                       [default:              │
│                                                       openai/gpt-4o-mini]    │
│    --description                                TEXT  Description/metadata   │
│                                                       for the batch job      │
│                                                       [default: Instructor   │
│                                                       batch job]             │
│    --completion-window                          TEXT  Completion window for  │
│                                                       the batch job (OpenAI  │
│                                                       only)                  │
│                                                       [default: 24h]         │
│    --use-anthropic        --no-use-anthropic          [DEPRECATED] Use       │
│                                                       --model instead. Use   │
│                                                       Anthropic API instead  │
│                                                       of OpenAI              │
│                                                       [default:              │
│                                                       no-use-anthropic]      │
│    --help                                             Show this message and  │
│                                                       exit.                  │
╰──────────────────────────────────────────────────────────────────────────────╯
```
Tokens:
Raw