Instructor Concepts¶

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
• Types - Working with different data types in your models
• Validation - Validating LLM outputs against your models
• Prompting - Creating effective prompts for structured output extraction

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

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

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:

1. Define Structure with Pydantic: Use Pydantic models to define exactly what data you want.
2. Enhance LLM Clients: Patch provider clients to add structured output capabilities.
3. Validate and Retry: Automatically validate responses and retry if necessary.
4. 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: Patch LLM client 
    User->>Instructor: Create completion 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

What to Read Next¶

• If you're new to Instructor, start with Models and Patching
• If you're having validation issues, check out Validators and Retrying
• For streaming applications, read Stream Partial and Stream Iterable
• To optimize your application, look at Caching and Usage Tokens

For practical examples of these concepts, visit the Cookbook section.