Instructor: Structured Outputs for LLMs with Pydantic and Python

Introduction

Instructor is a Python library that revolutionizes how developers interact with Large Language Models (LLMs) to obtain structured data. It addresses the common challenges of getting reliable, validated JSON outputs from LLMs by integrating seamlessly with Pydantic. This integration provides automatic validation, type safety, and excellent IDE support, significantly simplifying the development of AI applications. Instructor handles complex tasks such as writing JSON schemas, managing validation errors, retrying failed extractions, and parsing unstructured responses across various LLM providers, all through a single, intuitive interface.

Installation

Getting started with Instructor is straightforward. You can install it using pip:

pip install instructor

Alternatively, you can use other package managers like uv or poetry:

uv add instructor
poetry add instructor

Examples

Instructor's core strength lies in its simplicity. Define your desired output structure using a Pydantic BaseModel, and Instructor handles the rest. Below is a basic example demonstrating how to extract user information:

import instructor
from pydantic import BaseModel

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

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)

Instructor also supports a wide range of LLM providers, allowing you to use the same API for OpenAI, Anthropic, Google, Ollama, and more.

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

# All use the same API!
# user = client.chat.completions.create(
#     response_model=User,
#     messages=[{"role": "user", "content": "Extract a user from this text..."}],
# )

Why use Instructor

Instructor stands out by offering a comprehensive solution for structured LLM outputs, addressing many pain points developers face:

• Automatic Validation and Retries: It automatically validates outputs against your Pydantic models and retries if validation fails, providing robust error handling.
• Type Safety and IDE Support: Leveraging Pydantic ensures strong typing and excellent IDE integration, making your code more maintainable and less prone to errors.
• Provider Agnostic: Use the same clean API across various LLM providers, including OpenAI, Anthropic, Google, and local models like Ollama.
• Streaming Support: Stream partial objects as they are generated, enabling real-time feedback and more dynamic applications.
• Complex Data Structures: Easily extract nested objects and lists, simplifying the handling of intricate data models.
• Simplified Development: Eliminates the need for manual JSON schema writing, parsing, and error handling, allowing you to focus on application logic.

Links

To learn more and get started with Instructor, explore these official resources:

• Documentation
• Examples
• Blog
• Discord Community
• GitHub Repository