### Installation and Setup Commands

Source: https://github.com/567-labs/instructor/blob/main/CLAUDE.md

Initial environment setup commands for local development.

```bash
pip install uv
```

```bash
uv venv
```

```bash
uv pip install -e ".[dev]"
```

```bash
uv run pre-commit install
```

```bash
uv run pytest tests/ -k "not openai"
```

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

### Instructor Responses API - Quick Start

Source: https://github.com/567-labs/instructor/blob/main/docs/integrations/openai-responses.md

A quick start example demonstrating how to initialize the Instructor client and use the `create` method to get a structured output from an OpenAI model.

```APIDOC
## POST /responses/create

### Description
This endpoint creates a structured output from an OpenAI model based on the provided input and response model.

### Method
POST

### Endpoint
/responses/create

### Parameters
#### Query Parameters
- **response_model** (BaseModel) - Required - The Pydantic model to use for structuring the output.
- **input** (str) - Required - The input prompt for the OpenAI model.

### Request Body
This endpoint does not use a request body. All parameters are passed as query parameters or within the client initialization.

### Request Example
```python
import instructor
from pydantic import BaseModel

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

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

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

print(profile)
```

### Response
#### Success Response (200)
- **response** (BaseModel) - The structured output conforming to the `response_model`.

#### Response Example
```json
{
  "name": "Ivan",
  "age": 28
}
```
```

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

### Basic Instructor Client Setup

Source: https://github.com/567-labs/instructor/blob/main/docs/blog/posts/pydantic-is-still-all-you-need.md

Instantiate an Instructor client with an OpenAI client to enable structured outputs. Ensure you have the OpenAI library installed.

```python
from instructor import from_openai

client = from_openai(OpenAI())
```

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

### Manual Client Setup

Source: https://github.com/567-labs/instructor/blob/main/docs/integrations/index.md

Shows how to manually set up an Instructor client by patching an existing provider client. This requires installing provider-specific dependencies.

```python
import instructor
from provider_package import Client

client = instructor.from_provider(Client())

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

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

### Setup and Installation for Writer Instructor

Source: https://github.com/567-labs/instructor/blob/main/docs/integrations/writer.md

Instructions for configuring the environment variables and installing the necessary Python dependencies to use Instructor with Writer.

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

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

### Install Instructor and Provider Extras

Source: https://github.com/567-labs/instructor/blob/main/docs/getting-started.md

Installs the Instructor library and optional dependencies for specific LLM providers. Core Instructor has minimal dependencies; provider SDKs must be added explicitly.

```bash
pip install instructor

# For Anthropic
pip install "instructor[anthropic]"

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

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

# For Cohere
pip install "instructor[cohere]"

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

# For Mistral
pip install "instructor[mistralai]"

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

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

### Setup Repository and Environment

Source: https://github.com/567-labs/instructor/blob/main/CONTRIBUTING.md

Commands to fork, clone, and configure the local development environment, including setting up remotes and installing pre-commit hooks.

```bash
git clone https://github.com/YOUR-USERNAME/instructor.git
cd instructor
git remote add upstream https://github.com/instructor-ai/instructor.git
pip install pre-commit
pre-commit install
```

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

### Initialize Provider Client

Source: https://github.com/567-labs/instructor/blob/main/docs/integrations/index.md

Demonstrates initializing an Instructor client using a provider string for both synchronous and asynchronous operations. This is the recommended way to get started.

```python
import instructor
from pydantic import BaseModel

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

# Initialize any provider with a simple string
client = instructor.from_provider("openai/gpt-5.4-mini")
# Or use async client
async_client = instructor.from_provider("anthropic/claude-3-sonnet", async_client=True)

# Use the same interface for all providers
response = client.create(
    response_model=UserInfo,
    messages=[{"role": "user", "content": "Your prompt"}]
)
```

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

### Async Client Initialization with Instructor

Source: https://github.com/567-labs/instructor/blob/main/docs/getting-started.md

Demonstrates how to initialize an Instructor client for asynchronous operations. This is useful when integrating Instructor with async frameworks or performing I/O bound tasks.

```python
import instructor

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

# Later, use await client.create(...) for async calls
```

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

### Setup and Installation for Groq AI

Source: https://github.com/567-labs/instructor/blob/main/docs/examples/groq.md

Commands to install the necessary Python packages and configure the environment variable required for Groq API authentication.

```bash
pip install instructor groq pydantic openai anthropic
export GROQ_API_KEY=<your-api-key>
```

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

### Verify Instructor Installation with OpenAI

Source: https://github.com/567-labs/instructor/blob/main/docs/learning/getting_started/installation.md

A Python example demonstrating how to verify your Instructor installation by creating a structured output using the OpenAI provider. It defines a Pydantic model and uses the Instructor client to parse LLM output.

```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 Instructor with {Provider} Support

Source: https://github.com/567-labs/instructor/blob/main/NEW_PROVIDER_AGENT_INSTRUCTIONS.md

Installs the Instructor library with specific support for the {Provider} SDK. This is the first step to using Instructor with {Provider} models.

```bash
pip install "instructor[{provider}]"
```

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

### Migrate Bedrock client initialization to core modes

Source: https://github.com/567-labs/instructor/blob/main/docs/concepts/mode-migration.md

Demonstrates updating the Instructor client initialization for Bedrock. Note that while some legacy modes are deprecated, this example highlights the transition to the recommended core mode structure.

```python
# Before
import instructor
from instructor import Mode

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

# After
import instructor
from instructor import Mode

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

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

### Asynchronous Instructor Client Initialization and Usage

Source: https://github.com/567-labs/instructor/blob/main/docs/architecture.md

Illustrates the asynchronous setup for the Instructor library. It shows how to create an asynchronous client using `instructor.from_provider` with `async_client=True` and how to make an asynchronous call to the `create` method using `await`. The example includes Pydantic model definition and basic asynchronous execution with `asyncio.run`.

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

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

async def main():
    aclient = instructor.from_provider("openai/gpt-5-nano", async_client=True)
    model = await aclient.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "{\"name\": \"Ada\", \"age\": 37}"}],
        response_model=User,
        max_retries=3,
        strict=True,
    )
    print(model)

asyncio.run(main())

```

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

### Install Instructor and OpenAI

Source: https://github.com/567-labs/instructor/blob/main/docs/integrations/databricks.md

Installs the necessary Python packages for using instructor with OpenAI and Databricks models. This is a prerequisite for the examples in this guide.

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

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

### Setting up Instructor Clients for Different Providers (Python)

Source: https://github.com/567-labs/instructor/blob/main/docs/start-here.md

Shows how to initialize the Instructor client for various LLM providers using the `from_provider` function. This abstracts away provider-specific configurations, allowing for easy switching between services like OpenAI, Anthropic, and Google Gemini.

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

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

### Extract Basic Structured Data with Anthropic

Source: https://github.com/567-labs/instructor/blob/main/docs/getting-started.md

Shows how to use Instructor with the Anthropic provider to extract structured data. It follows the same pattern as the OpenAI example, but uses an Anthropic model identifier.

```python
import instructor
from pydantic import BaseModel

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

# Create an instructor client with from_provider for Anthropic
client = instructor.from_provider("anthropic/claude-3-opus-20240229")

user_info = client.create(
    response_model=UserInfo,
    messages=[
        {"role": "user", "content": "John Doe is 30 years old."}
    ],
)

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

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

### Defining Response Models with Pydantic (Python)

Source: https://github.com/567-labs/instructor/blob/main/docs/start-here.md

Illustrates how to define a Pydantic model for Instructor's response models. This example shows a `User` model with `name` and `age` fields, including descriptions for each field. These descriptions are crucial for guiding the LLM to extract the correct information.

```python
from pydantic import BaseModel, Field

class User(BaseModel):
    name: str = Field(description="The user's full name")
    age: int = Field(description="The user's age in years")
    # The descriptions help the LLM understand what to extract
```

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

### Install Project with UV

Source: https://github.com/567-labs/instructor/blob/main/docs/contributing.md

Clone the Instructor repository and install it in development mode with UV, including development and documentation dependencies.

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

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

### Scrape and Extract Web Page Content

Source: https://github.com/567-labs/instructor/blob/main/docs/examples/document_segmentation.md

Fetches the content of a given URL and extracts the main text using the `trafilatura` library. This function is part of the example usage for demonstrating document structuring on real-world web content. It requires the `trafilatura` package to be installed.

```python
from trafilatura import fetch_url, extract

# <%hide%>
import instructor
from pydantic import BaseModel, Field
from typing import List


def doc_with_lines(document):
    document_lines = document.split("\n")
    document_with_line_numbers = ""
    line2text = {}
    for i, line in enumerate(document_lines):
        document_with_line_numbers += f"[{i}] {line}\n"
        line2text[i] = line
    return document_with_line_numbers, line2text


client = instructor.from_provider("cohere/command-r-plus")


system_prompt = f"""
You are a world class educator working on organizing your lecture notes.
Read the document below and extract a StructuredDocument object from it where each section of the document is centered around a single concept/topic that can be taught in one lesson.
Each line of the document is marked with its line number in square brackets (e.g. [1], [2], [3], etc). Use the line numbers to indicate section start and end.
"""


class Section(BaseModel):
    title: str = Field(description="main topic of this section of the document")
    start_index: int = Field(description="line number where the section begins")
    end_index: int = Field(description="line number where the section ends")


class StructuredDocument(BaseModel):
    """obtains meaningful sections, each centered around a single concept/topic"""

    sections: List[Section] = Field(description="a list of sections of the document")


def get_structured_document(document_with_line_numbers) -> StructuredDocument:
    return client.create(
        model="command-a-03-2025",
        response_model=StructuredDocument,
        messages=[
            {
                "role": "system",
                "content": system_prompt,
            },
            {
                "role": "user",
                "content": document_with_line_numbers,
            },
        ],
    )  # type: ignore


def get_sections_text(structured_doc, line2text):
    segments = []
    for s in structured_doc.sections:
        contents = []
        for line_id in range(s.start_index, s.end_index):
            contents.append(line2text.get(line_id, ''))
        segments.append(
            {
                "title": s.title,
                "content": "\n".join(contents),
                "start": s.start_index,
                "end": s.end_index,
            }
        )
    return segments

```

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

### Build Documentation

Source: https://github.com/567-labs/instructor/blob/main/AGENT.md

Serve documentation locally using 'mkdocs serve' or build for production with a script.

```bash
uv run mkdocs serve
```

```bash
./build_mkdocs.sh
```

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

### Start Fine-Tuning Interface

Source: https://github.com/567-labs/instructor/blob/main/docs/cli/index.md

Launch the interactive fine-tuning interface by running the `instructor finetune` command.

```bash
instructor finetune
```

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

### Generate Synthetic User Data with Examples

Source: https://github.com/567-labs/instructor/blob/main/docs/blog/posts/fake-data.md

Generates synthetic user data, influencing the output by providing examples directly in the Pydantic model's field definitions. This helps guide the model towards generating data that matches the style of the examples.

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

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

### Initialize Instructor Clients with `from_provider`

Source: https://github.com/567-labs/instructor/blob/main/docs/concepts/from_provider.md

Demonstrates how to use `from_provider` to initialize clients for different AI providers 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")
```

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

### Generate Response with Examples

Source: https://github.com/567-labs/instructor/blob/main/docs/prompting/ensembling/usp.md

Generates a final classification response using a specified model ('gpt-4o'). It includes a system prompt that provides formatted examples to guide the model's classification.

```python
async def generate_response_with_examples(query: str, examples: list[str]):
    formatted_examples = "\n".join(examples)
    return await client.create(
        model="gpt-4o",
        response_model=Classification,
        messages=[
            {
                "role": "system",
                "content": f"""
                You are a helpful assistant that classifies queries into one of the following categories: Happy, Angry, Sadness.

                Here are some samples of queries and their categories:

                <examples>
                {formatted_examples}
                </examples>

                Here is a user query to classify

                <query>
                {query}
                </query>
                """,
            }
        ],
    )
```

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

### Example Usage of diskcache Decorator

Source: https://github.com/567-labs/instructor/blob/main/docs/blog/posts/caching.md

Demonstrates how to apply the `instructor_cache` decorator to a function that extracts user details using an AI client. This example shows the basic setup with diskcache and Pydantic models.

```python
import functools
import inspect
import instructor
import diskcache

from pydantic import BaseModel

client = instructor.from_provider("openai/gpt-5-nano")
cache = diskcache.Cache('./my_cache_directory')


def instructor_cache(func):
    """Cache a function that returns a Pydantic model"""
    return_type = inspect.signature(func).return_annotation  # (4)
    if not issubclass(return_type, BaseModel):  # (1)
        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)}"  #  (2)
        )
        # Check if the result is already cached
        if (cached := cache.get(key)) is not None:
            # Deserialize from JSON based on the return type (3)
            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:
    return client.create(
        model="gpt-5.4-mini",
        response_model=UserDetail,
        messages=[
            {"role": "user", "content": data},
        ],
    )

```

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

### Install Provider with uv or Poetry

Source: https://github.com/567-labs/instructor/blob/main/docs/contributing.md

Demonstrates how to install the Instructor library with the newly added provider using `uv` or `poetry`. This command installs the provider-specific dependencies.

```bash
# Installation command for your provider
uv pip install "instructor[my-provider]"
# or with poetry
poetry install --with my-provider
```

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

### Run Instructor Hooks Example

Source: https://github.com/567-labs/instructor/blob/main/examples/hooks/README.md

Navigate to the example directory and run the Python script to execute the Instructor hooks example.

```bash
cd examples/hooks

python run.py
```

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

### Install Instructor with Mistral Support

Source: https://github.com/567-labs/instructor/blob/main/docs/integrations/mistral.md

Installs the Instructor library with the necessary dependencies for Mistral integration. This is the first step to using Instructor with Mistral models.

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

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

### Creating Instructor Clients

Source: https://github.com/567-labs/instructor/blob/main/docs/blog/posts/version-1.md

Demonstrates multiple ways to initialize an Instructor client, including from providers like OpenAI and Anthropic, and from LiteLLM. These clients can proxy existing model creation methods.

```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-5.4-mini", response_model=type[T]) -> T
client.create(model="gpt-5.4-mini", response_model=type[T]) -> T
client.messages.create(model="gpt-5.4-mini", response_model=type[T]) -> T
```

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

### Instructor CLI Fine-tuning Workflow Example

Source: https://github.com/567-labs/instructor/blob/main/docs/cli/finetune.md

Demonstrates the typical workflow for fine-tuning a model using the Instructor CLI, including uploading data, listing files, and creating a job with specified parameters.

```sh
$ instructor files upload transformed_data.jsonl
$ instructor files upload validation_data.jsonl
$ instructor files list
...
$ instructor jobs create_from_id <file_id> --validation_file <validation_file_id> --n_epochs 3 --batch_size 16 --learning_rate_multiplier 0.5
```

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

### Install and Configure mkdocs-llmstxt Plugin

Source: https://github.com/567-labs/instructor/blob/main/docs/blog/posts/mkdocs-llmstxt-plugin-integration.md

Provides instructions for installing the mkdocs-llmstxt plugin using pip and a basic configuration example for mkdocs.yml, highlighting the required `site_url` and section mapping.

```bash
pip install mkdocs-llmstxt
```

```yaml
site_url: https://your-site.com/  # Required for the plugin

plugins:
  - llmstxt:
      markdown_description: Description of your project
      sections:
        Documentation:
          - docs/*.md
```

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

### OpenAI Provider Example

Source: https://github.com/567-labs/instructor/blob/main/docs/index.md

Demonstrates data extraction using the OpenAI provider. Ensure you have the necessary API keys and library installed.

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

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

### Configure Groq Client for Instructor

Source: https://github.com/567-labs/instructor/blob/main/docs/blog/posts/open_source.md

Provides the setup steps for using the Groq API with Instructor, including environment variable configuration and client initialization.

```bash
export GROQ_API_KEY="your-api-key"
```

```python
import os
from pydantic import BaseModel
import groq
import instructor

client = groq.Groq(
    api_key=os.environ.get("GROQ_API_KEY"),
)
```

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

### Initialize LLM Providers with Strings

Source: https://github.com/567-labs/instructor/blob/main/docs/blog/posts/string-based-init.md

Use the `instructor.from_provider` function with a "provider/model-name" string to initialize any supported LLM client. This simplifies setup and allows for easy switching between providers.

```python
import instructor
from pydantic import BaseModel


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


# Initialize any provider with a single consistent interface
client = instructor.from_provider("openai/gpt-5.4-mini")
client = instructor.from_provider("anthropic/claude-3-sonnet")
client = instructor.from_provider("google/gemini-pro")
client = instructor.from_provider("mistral/mistral-large")
```

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

### Migrate Gemini Client Initialization

Source: https://github.com/567-labs/instructor/blob/main/docs/integrations/google.md

Demonstrates the transition from deprecated provider-specific modes to the recommended from_provider initialization pattern for standard Gemini models.

```python
# Old Way (Deprecated)
import instructor
import google.generativeai as genai

client = instructor.from_provider(
    "google/gemini-2.5-flash",
    mode=instructor.Mode.JSON,
)

# New Way (Recommended)
import instructor

# Option 1: Using from_provider (recommended)
client = instructor.from_provider("google/gemini-2.5-flash")

# Option 2: Using from_genai directly (legacy/advanced)
from google import genai
from instructor import from_genai

client = from_genai(genai.Client())
```

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

### Setup Async LLM Client and Data Model

Source: https://github.com/567-labs/instructor/blob/main/docs/blog/posts/learn-async.md

Initializes the Instructor async client with OpenAI and defines a Pydantic model for structured data extraction. This setup serves as the foundation for all concurrent processing examples.

```python
import instructor
from pydantic import BaseModel

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:
    return await client.create(
        model="gpt-4o-mini",
        response_model=Person,
        messages=[{"role": "user", "content": f"Extract person info: {text}"}],
    )

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

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

### Installation and Configuration for Anyscale

Source: https://github.com/567-labs/instructor/blob/main/docs/integrations/anyscale.md

Commands to install the necessary instructor package and configure the required Anyscale API key environment variable.

```bash
pip install instructor
export ANYSCALE_API_KEY=your_api_key_here
```

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

### Ollama (Local) Provider Example

Source: https://github.com/567-labs/instructor/blob/main/docs/index.md

Demonstrates data extraction using a local Ollama model. This requires Ollama to be installed and running with the specified model.

```python
import instructor
from pydantic import BaseModel


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


client = instructor.from_provider("ollama/llama3.2")
resp = client.create(
    response_model=ExtractUser,
    messages=[{"role": "user", "content": "Extract Jason is 25 years old."}]
)
```

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

### Serve Documentation Locally

Source: https://github.com/567-labs/instructor/blob/main/CLAUDE.md

Start a local development server for the documentation with hot reloading. Changes made to the documentation files will be reflected automatically.

```bash
# Serve documentation locally with hot reload
uv run mkdocs serve
```

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

### Asynchronous Structured Output Generation

Source: https://github.com/567-labs/instructor/blob/main/docs/integrations/ollama.md

Example of using an asynchronous client with Instructor to generate structured outputs from Ollama models.

```python
import instructor
from pydantic import BaseModel
import asyncio

async_client = instructor.from_provider(
    "ollama/llama2",
    async_client=True,
)

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

async def get_character():
    return await async_client.create(
        messages=[{"role": "user", "content": "Tell me about Harry Potter"}],
        response_model=Character,
    )

print(asyncio.run(get_character()))
```

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

### Set API Keys as Environment Variables

Source: https://github.com/567-labs/instructor/blob/main/docs/getting-started.md

Configures API keys for LLM providers by setting them as environment variables. This is a common practice for securely managing credentials.

```bash
# For OpenAI
export OPENAI_API_KEY=your_openai_api_key

# For Anthropic
export ANTHROPIC_API_KEY=your_anthropic_api_key

# For other providers, set relevant API keys
```

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

### Install Instructor for Google GenAI

Source: https://github.com/567-labs/instructor/blob/main/docs/integrations/google.md

Install the necessary Python package to enable Instructor support for Google's GenAI SDK.

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

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

### Run Instructor Tutorials Locally

Source: https://github.com/567-labs/instructor/blob/main/docs/tutorials/index.md

This bash script clones the Instructor repository, installs the necessary dependencies, and launches Jupyter notebooks for the tutorials. Ensure you have Git and pip installed, and Python 3.8+.

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

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

### Instructor Retry Error Feedback Example

Source: https://github.com/567-labs/instructor/blob/main/docs/learning/validation/retry_mechanisms.md

Illustrates the detailed error messages Instructor provides to the LLM to guide corrections during retries. This feedback helps the LLM understand specific validation failures.

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

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

### Migrate Vertex AI Client Initialization

Source: https://github.com/567-labs/instructor/blob/main/docs/integrations/google.md

Shows how to update Vertex AI client initialization in Instructor, moving from legacy mode-based configurations to the modern from_provider or from_genai approach.

```python
# Old Way (Deprecated)
import instructor
import vertexai
from vertexai.generative_models import GenerativeModel

vertexai.init(project="your-project", location="us-central1")
client = instructor.from_provider("google/gemini-2.5-flash", vertexai=True),
    mode=instructor.Mode.TOOLS,
)

# New Way (Recommended)
import instructor

# Option 1: Using from_provider (recommended)
client = instructor.from_provider(
    "vertexai/gemini-3-flash",
    project="your-project",
    location="us-central1"
)

# Option 2: Using from_genai with vertexai=True (legacy/advanced)
from google import genai
from instructor import from_genai

client = from_genai(
    genai.Client(
        vertexai=True,
        project="your-project",
        location="us-central1"
    )
)
```

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

### Stream LLM Responses Incrementally

Source: https://github.com/567-labs/instructor/blob/main/docs/getting-started.md

Enables streaming of LLM responses using `create_partial`, allowing for incremental display of generated content. This improves user experience for longer responses.

```python
from instructor import Partial

# Assuming 'client' and 'Person' model are defined
# stream = client.create_partial(
#     response_model=Person,
#     messages=[
#         {"role": "user", "content": "Extract a detailed person profile for John Smith, 35, who lives in Chicago and Springfield."}
#     ],
# )

# for partial in stream:
#     # This will incrementally show the response being built
#     print(partial)
```

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

### Install Parea and Instructor

Source: https://github.com/567-labs/instructor/blob/main/docs/blog/posts/parea.md

Install the necessary libraries for Parea and Instructor integration.

```bash
pip install -U parea-ai instructor
```

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

### Install Instructor with LiteLLM Support

Source: https://github.com/567-labs/instructor/blob/main/docs/integrations/litellm.md

Install the necessary packages for using Instructor with LiteLLM.

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

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

### Perform File Search for RAG Applications

Source: https://github.com/567-labs/instructor/blob/main/docs/integrations/openai-responses.md

Enables semantic and keyword search over documents using vector store IDs. Includes examples for sync and async implementations.

```python
from pydantic import BaseModel
import instructor

class Citation(BaseModel):
    file_id: int
    file_name: str
    excerpt: str

class Response(BaseModel):
    citations: list[Citation]
    response: str

client = instructor.from_provider(
    "openai/gpt-4.1-mini",
    mode=instructor.Mode.RESPONSES_TOOLS_WITH_INBUILT_TOOLS
)

response = client.responses.create(
    input="How much does the Kyoto itinerary cost?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": ["your_vector_store_id"],
        "max_num_results": 2,
    }],
    response_model=Response,
)
```

```python
import asyncio
# ... (imports and models same as sync)

client = instructor.from_provider(
    "openai/gpt-4.1-mini",
    mode=instructor.Mode.RESPONSES_TOOLS_WITH_INBUILT_TOOLS,
    async_client=True
)

async def main():
    response = await client.responses.create(
        input="How much does the Kyoto itinerary cost?",
        tools=[{
            "type": "file_search",
            "vector_store_ids": ["your_vector_store_id"],
            "max_num_results": 2,
        }],
        response_model=Response,
    )

asyncio.run(main())
```

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

### Quick Start with Auto Client

Source: https://github.com/567-labs/instructor/blob/main/docs/integrations/ollama.md

Shows the simplest way to initialize an Instructor client for Ollama and generate a structured response based on a Pydantic model.

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

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

### LangSmith and Instructor Setup

Source: https://github.com/567-labs/instructor/blob/main/docs/blog/posts/langsmith.md

Demonstrates how to wrap an OpenAI client with LangSmith and initialize an Instructor client for structured API calls. This setup is crucial for enabling LangSmith's tracing and observability features.

```python
import instructor
import asyncio

from langsmith import traceable
from langsmith.wrappers import wrap_openai

from openai import AsyncOpenAI
from pydantic import BaseModel, Field, field_validator
from typing import List
from enum import Enum

# Wrap the OpenAI client with LangSmith
wrapped_client = wrap_openai(AsyncOpenAI())

# Create instructor client with LangSmith-wrapped client
# Note: When using LangSmith, you may need to pass the wrapped client
# For most cases, use: client = instructor.from_provider("openai/gpt-4o", mode=instructor.Mode.TOOLS)
client = instructor.from_provider("openai/gpt-4o", mode=instructor.Mode.TOOLS)

# Rate limit the number of requests
sem = asyncio.Semaphore(5)
```

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

### Streaming Partial Responses with Instructor and Mistral

Source: https://github.com/567-labs/instructor/blob/main/docs/integrations/mistral.md

Introduces streaming capabilities for incremental model responses. This example uses `create_partial` to build a response piece by piece, suitable for real-time applications.

```python
from pydantic import BaseModel
import instructor
from mistralai import Mistral
from instructor.dsl.partial import Partial

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

# Initialize with API key
client = Mistral(api_key=os.environ.get("MISTRAL_API_KEY"))

# Enable instructor patches for Mistral client
instructor_client = instructor.from_provider("mistral/mistral-small")


```

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

### Create Async Client with from_provider

Source: https://github.com/567-labs/instructor/blob/main/docs/concepts/from_provider.md

Demonstrates how to create an asynchronous client using `instructor.from_provider` by setting `async_client=True`. The client is then used with `await` for making LLM calls.

```python
import asyncio
import instructor
from pydantic import BaseModel


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


async def main() -> None:
    # Create async client
    async_client = instructor.from_provider("openai/gpt-4o-mini", async_client=True)

    # Use with await
    await async_client.create(
        response_model=User,
        messages=[{"role": "user", "content": "Extract: Alice is 25"}],
    )


asyncio.run(main())
```

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

### Initialize Instructor Client with Cohere Provider

Source: https://github.com/567-labs/instructor/blob/main/docs/examples/document_segmentation.md

Initializes the Instructor client to use the 'cohere/command-r-plus' model. This setup is necessary for leveraging Instructor's features with Cohere's language models.

```python
client = instructor.from_provider("cohere/command-r-plus")
```