# Instructor: Structured Outputs for LLMs with Pydantic and Python

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/instructor-ai-instructor
Generated for open source discovery and AI-assisted research.

Instructor is a powerful Python library designed to simplify obtaining structured outputs from Large Language Models (LLMs). By leveraging Pydantic, it provides robust validation, type safety, and IDE support, eliminating the need for manual JSON parsing, error handling, or retries. This tool streamlines the process of extracting reliable, structured data from any LLM provider.

GitHub: https://github.com/instructor-ai/instructor
OSRepos URL: https://osrepos.com/repo/instructor-ai-instructor

## Summary

Instructor is a powerful Python library designed to simplify obtaining structured outputs from Large Language Models (LLMs). By leveraging Pydantic, it provides robust validation, type safety, and IDE support, eliminating the need for manual JSON parsing, error handling, or retries. This tool streamlines the process of extracting reliable, structured data from any LLM provider.

## Topics

- Python
- LLM Tools
- AI
- OpenAI
- Pydantic
- Structured Data
- Validation
- Function Calling

## Repository Information

Last analyzed by OSRepos: Sat Nov 08 2025 20:00:44 GMT+0000 (Western European Standard Time)
Detail views: 8
GitHub clicks: 6

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

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

bash
pip install instructor


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

bash
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:

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

python
# 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](https://python.useinstructor.com){:target="_blank"}
*   [Examples](https://python.useinstructor.com/examples/){:target="_blank"}
*   [Blog](https://python.useinstructor.com/blog/){:target="_blank"}
*   [Discord Community](https://discord.gg/bD9YE9JArw){:target="_blank"}
*   [GitHub Repository](https://github.com/567-labs/instructor){:target="_blank"}