Overview ↗

Original Documentation

This section explains the core concepts and features of the Instructor library, organized by category to help you find what you need.

Core Concepts#

These are the fundamental concepts you need to understand to use Instructor effectively:

Models - Using Pydantic models to define output structures
Patching - How Instructor patches LLM clients
from_provider - Unified interface for creating clients across all providers
Migration Guide - Migrating from older patterns to from_provider
Types - Working with different data types in your models
Validation - Validating LLM outputs against your models
Prompting - Creating effective prompts for structured output extraction
Multimodal - Working with Audio Files, Images and PDFs

Data Handling and Structures#

These concepts relate to defining and working with different data structures:

Fields - Working with Pydantic fields and attributes
Lists and Arrays - Handling lists and arrays in your models
TypedDicts - Using TypedDict for flexible typing
Union Types - Working with union types
Enums - Using enumerated types in your models
Missing - Handling missing or optional values
Alias - Create field aliases
Citation - Extract and validate citations from source text

Streaming Features#

These features help you work with streaming responses:

Stream Partial - Stream partially completed responses
Stream Iterable - Stream collections of completed objects
Raw Response - Access the raw LLM response

Error Handling and Validation#

These features help you ensure data quality:

Retrying - Configure automatic retry behavior
Validators - Define custom validation logic
Hooks - Add callbacks for monitoring and debugging

Performance Optimization#

These features help you optimize performance:

Caching - Cache responses to improve performance
Prompt Caching - Cache prompts to reduce token usage
Usage Tokens - Track token usage
Parallel Tools - Run multiple tools in parallel
Dictionary Operations - Performance optimizations for dictionary operations

Integration Features#

These features help you integrate with other technologies:

FastAPI - Integrate with FastAPI
Type Adapter - Use TypeAdapter with Instructor
Templating - Use templates for dynamic prompts
Distillation - Optimize models for production

Philosophy#

Philosophy - The guiding principles behind Instructor

How These Concepts Work Together#

Instructor is built around a few key ideas that work together:

Define Structure with Pydantic: Use Pydantic models to define exactly what data you want.
Create Clients with from_provider: Use the unified interface to create clients for any provider.
Validate and Retry: Automatically validate responses and retry if necessary.
Process Streams: Handle streaming responses for real-time updates.

Typical Workflow#

sequenceDiagram
    participant User as Your Code
    participant Instructor
    participant LLM as LLM Provider

    User->>Instructor: Define Pydantic model
    User->>Instructor: Create client with from_provider
    User->>Instructor: Call create() with response_model
    Instructor->>LLM: Send structured request
    LLM->>Instructor: Return LLM response
    Instructor->>Instructor: Validate against model

    alt Validation Success
        Instructor->>User: Return validated Pydantic object
    else Validation Failure
        Instructor->>LLM: Retry with error context
        LLM->>Instructor: Return new response
        Instructor->>Instructor: Validate again
        Instructor->>User: Return validated object or error
    end