# Instructor — Structured LLM Outputs with Pydantic

> Extract structured data from LLMs using Pydantic models. Works with OpenAI, Anthropic, Gemini, and local models. The simplest way to get reliable JSON from any LLM.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
pip install instructor
```

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

client = instructor.from_openai(OpenAI())

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

user = client.chat.completions.create(
    model="gpt-4o",
    response_model=User,
    messages=[{"role": "user", "content": "John is 30 years old"}],
)
print(user)  # User(name='John', age=30)
```

## What is Instructor?

Instructor patches LLM client libraries to return validated Pydantic objects instead of raw text. It handles retries, streaming, and partial responses — making structured extraction reliable across any provider.

**Answer-Ready**: Instructor is a Python library that extracts structured, validated data from LLMs using Pydantic models, supporting OpenAI, Anthropic, Gemini, and local models with automatic retry logic.

## Key Patterns

### 1. Multi-Provider Support

```python
# Anthropic
import instructor
from anthropic import Anthropic
client = instructor.from_anthropic(Anthropic())

# Gemini
import instructor
import google.generativeai as genai
client = instructor.from_gemini(genai.GenerativeModel("gemini-1.5-pro"))

# Ollama (local)
from openai import OpenAI
client = instructor.from_openai(
    OpenAI(base_url="http://localhost:11434/v1"),
    mode=instructor.Mode.JSON,
)
```

### 2. Nested & Complex Types

```python
from typing import List
from pydantic import BaseModel

class Address(BaseModel):
    street: str
    city: str
    country: str

class Company(BaseModel):
    name: str
    industry: str
    addresses: List[Address]
    employee_count: int

company = client.chat.completions.create(
    model="gpt-4o",
    response_model=Company,
    messages=[{"role": "user", "content": "..."}],
)
```

### 3. Streaming Partial Results

```python
for partial in client.chat.completions.create_partial(
    model="gpt-4o",
    response_model=User,
    messages=[{"role": "user", "content": "John is 30"}],
):
    print(partial)  # Progressively filled fields
```

### 4. Automatic Retries

```python
user = client.chat.completions.create(
    model="gpt-4o",
    response_model=User,
    messages=[...],
    max_retries=3,  # Retries with validation errors fed back
)
```

## FAQ

**Q: How does it differ from function calling?**
A: Instructor builds on function calling but adds Pydantic validation, automatic retries with error feedback, streaming, and multi-provider support.

**Q: Does it work with Claude?**
A: Yes, via `instructor.from_anthropic()` with full tool-use support.

**Q: Performance overhead?**
A: Minimal — it is a thin wrapper. Retries add latency only when validation fails.

## Source & Thanks

- GitHub: [jxnl/instructor](https://github.com/jxnl/instructor) (8k+ stars)
- Docs: [python.useinstructor.com](https://python.useinstructor.com)
- Author: Jason Liu

<!-- ZH -->


## Quick Start

```bash
pip install instructor
```

Define output structure with Pydantic models, and Instructor automatically extracts validated structured data from LLMs.

## What is Instructor?

Instructor patches LLM client libraries so they return validated Pydantic objects instead of raw text. Supports retries, streaming output, and partial responses.

**In one sentence**: Instructor extracts structured data from LLMs using Pydantic models, supporting OpenAI, Anthropic, Gemini, and local models.

## Core Patterns

### 1. Multi-Provider Support
Works with OpenAI, Anthropic, Gemini, Ollama, and more — switch with a single line.

### 2. Nested Complex Types
Supports nested models, lists, optional fields, and the full power of Pydantic.

### 3. Streaming Partial Results
Fields fill in progressively — great for real-time display of large structured outputs.

### 4. Auto-Retry
On validation failure, automatically feeds the error back to the LLM for regeneration.

## FAQ

**Q: Does it support Claude?**
A: Yes, via `instructor.from_anthropic()` using tool-use mode.

**Q: Performance overhead?**
A: Minimal — it's a thin wrapper. Retries add latency only on validation failure.

## Source & Thanks

- GitHub: [jxnl/instructor](https://github.com/jxnl/instructor) (8k+ stars)
- Author: Jason Liu

---
Source: https://tokrepo.com/en/workflows/instructor-structured-llm-outputs-pydantic-9301dfb7
Author: Pydantic