Repository: 567-labs/instructor

Stars: 12784

CLAUDE.md Copy Chapter

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Instructor Development Guide

Commands Copy Chapter

Installation & Setup Copy Chapter

Code Style Guidelines Copy Chapter

Conventional Commits Copy Chapter

Core Architecture Copy Chapter

Provider Architecture Copy Chapter

Key Components Copy Chapter

Testing Guidelines Copy Chapter

Documentation Guidelines Copy Chapter

Branch and Development Workflow Copy Chapter

Adding New Providers Copy Chapter

Step-by-Step Guide Copy Section

class Provider(Enum):
       YOUR_PROVIDER = "your_provider"

2. Add Provider Modes in instructor/mode.py:

class Mode(enum.Enum):
       YOUR_PROVIDER_TOOLS = "your_provider_tools"
       YOUR_PROVIDER_JSON = "your_provider_json"

3. Create Client Implementation instructor/client_your_provider.py:
- Use overloads for sync/async variants
- Validate mode compatibility
- Return appropriate Instructor/AsyncInstructor instance
- Handle provider-specific edge cases

4. Add Conditional Import in instructor/__init__.py:

if importlib.util.find_spec("your_provider_sdk") is not None:
       from .client_your_provider import from_your_provider
       __all__ += ["from_your_provider"]

5. Update Auto Client in instructor/auto_client.py:
- Add to supported_providers list
- Implement provider handling in from_provider()
- Update get_provider() function if URL-detectable

6. Create Tests in tests/llm/test_your_provider/:
- conftest.py with client fixtures
- Basic extraction tests
- Streaming tests
- Validation/retry tests
- No mocking - use real API calls

7. Add Documentation in docs/integrations/your_provider.md:
- Installation instructions
- Basic usage examples
- Supported modes
- Provider-specific features

8. Update Navigation in mkdocs.yml:
- Add to integrations section
- Include redirects if needed

Contributing to Evals Copy Chapter

Pull Request Guidelines Copy Chapter

Type System and Best Practices Copy Chapter

Type Checking with ty Copy Section

Code Quality Checks Before Committing Copy Section

Type Patterns Copy Section

Pydantic Integration Copy Section

Building Documentation Copy Chapter

Setup Copy Section

Install documentation dependencies

pip install -r requirements-doc.txt

Local Development Copy Section

Serve documentation locally with hot reload

uv run mkdocs serve
Build documentation for production

./build_mkdocs.sh

Documentation Features Copy Section

Writing Documentation Copy Section

Project Structure Copy Chapter

Documentation Structure Copy Chapter

Example Patterns Copy Chapter

Dependency Management Copy Chapter

Core Dependencies Copy Section

Optional Dependencies Copy Section

Install with specific provider

pip install "instructor[anthropic]"
pip install "instructor[google-generativeai]"
pip install "instructor[groq]"

Development Dependencies Copy Section

Install all development dependencies

uv pip install -e ".[dev]"

Version Constraints Copy Section

Managing Dependencies Copy Section

The library enables structured LLM outputs using Pydantic models across multiple providers with type safety.

README.md Copy Chapter

Instructor: Structured Outputs for LLMs

Get reliable JSON from any LLM. Built on Pydantic for validation, type safety, and IDE support.

import instructor
from pydantic import BaseModel

Define what you want

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

Extract it from natural language

client = instructor.from_provider("openai/gpt-4o-mini")
user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "John is 25 years old"}],
)
print(user)  # User(name='John', age=25)

That's it. No JSON parsing, no error handling, no retries. Just define a model and get structured data.


Use Instructor for fast extraction, reach for PydanticAI when you need agents. Instructor keeps schema-first flows simple and cheap. If your app needs richer agent runs, built-in observability, or shareable traces, try PydanticAI. PydanticAI is the official agent runtime from the Pydantic team, adding typed tools, replayable datasets, evals, and production dashboards while using the same Pydantic models. Dive into the PydanticAI docs to see how it extends Instructor-style workflows.

Why Instructor? Copy Chapter

Getting structured data from LLMs is hard. You need to:

1. Write complex JSON schemas
2. Handle validation errors
3. Retry failed extractions
4. Parse unstructured responses
5. Deal with different provider APIs

Instructor handles all of this with one simple interface:

<table>
<tr>
<td><b>Without Instructor</b></td>
<td><b>With Instructor</b></td>
</tr>
<tr>
<td>

response = openai.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "..."}],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "extract_user",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "name": {"type": "string"},
                        "age": {"type": "integer"},
                    },
                },
            },
        }
    ],
)
Parse response

tool_call = response.choices[0].message.tool_calls[0]
user_data = json.loads(tool_call.function.arguments)
Validate manually

if "name" not in user_data:
    # Handle error...
    pass

</td>
<td>

client = instructor.from_provider("openai/gpt-4")
user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "..."}],
)
That's it! user is validated and typed

</td>
</tr>
</table>

Install in seconds Copy Chapter

pip install instructor

Or with your package manager:

uv add instructor
poetry add instructor

Works with every major provider Copy Chapter

Use the same code with any LLM provider:

OpenAI

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

client = instructor.from_provider("anthropic/claude-3-5-sonnet")
Google

client = instructor.from_provider("google/gemini-pro")
Ollama (local)

client = instructor.from_provider("ollama/llama3.2")
With API keys directly (no environment variables needed)

client = instructor.from_provider("openai/gpt-4o", api_key="sk-...")
client = instructor.from_provider("anthropic/claude-3-5-sonnet", api_key="sk-ant-...")
client = instructor.from_provider("groq/llama-3.1-8b-instant", api_key="gsk_...")
All use the same API!

user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "..."}],
)

Production-ready features Copy Chapter

Automatic retries Copy Section

Failed validations are automatically retried with the error message:

from pydantic import BaseModel, field_validator

class User(BaseModel):
    name: str
    age: int
    @field_validator('age')
    def validate_age(cls, v):
        if v < 0:
            raise ValueError('Age must be positive')
        return v

Instructor automatically retries when validation fails

user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "..."}],
    max_retries=3,
)

Streaming support Copy Section

Stream partial objects as they're generated:

from instructor import Partial
for partial_user in client.chat.completions.create(
    response_model=Partial[User],
    messages=[{"role": "user", "content": "..."}],
    stream=True,
):
    print(partial_user)
    # User(name=None, age=None)
    # User(name="John", age=None)
    # User(name="John", age=25)

Nested objects Copy Section

Extract complex, nested data structures:

from typing import List

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

class User(BaseModel):
    name: str
    age: int
    addresses: List[Address]

Instructor handles nested objects automatically

user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "..."}],
)

Used in production by Copy Chapter

Trusted by over 100,000 developers and companies building AI applications:

- 3M+ monthly downloads
- 10K+ GitHub stars
- 1000+ community contributors

Companies using Instructor include teams at OpenAI, Google, Microsoft, AWS, and many YC startups.

Get started Copy Chapter

Basic extraction Copy Section

Extract structured data from any text:

from pydantic import BaseModel
import instructor
client = instructor.from_provider("openai/gpt-4o-mini")

class Product(BaseModel):
    name: str
    price: float
    in_stock: bool

product = client.chat.completions.create(
    response_model=Product,
    messages=[{"role": "user", "content": "iPhone 15 Pro, $999, available now"}],
)
print(product)
Product(name='iPhone 15 Pro', price=999.0, in_stock=True)

Multiple languages Copy Section

Instructor's simple API is available in many languages:

- Python - The original
- TypeScript - Full TypeScript support
- Ruby - Ruby implementation
- Go - Go implementation
- Elixir - Elixir implementation
- Rust - Rust implementation

Learn more Copy Section

- Documentation - Comprehensive guides
- Examples - Copy-paste recipes
- Blog - Tutorials and best practices
- Discord - Get help from the community

Why use Instructor over alternatives? Copy Chapter

vs Raw JSON mode: Instructor provides automatic validation, retries, streaming, and nested object support. No manual schema writing.

vs LangChain/LlamaIndex: Instructor is focused on one thing - structured extraction. It's lighter, faster, and easier to debug.

vs Custom solutions: Battle-tested by thousands of developers. Handles edge cases you haven't thought of yet.

Contributing Copy Chapter

We welcome contributions! Check out our good first issues to get started.

License Copy Chapter

MIT License - see LICENSE for details.

---

<p align="center">
Built by the Instructor community. Special thanks to <a href="https://twitter.com/jxnlco">Jason Liu</a> and all <a href="https://github.com/567-labs/instructor/graphs/contributors">contributors</a>.
</p>