chore: import upstream snapshot with attribution

2026-07-13 13:36:38 +08:00
commit 97e91a83f3
978 changed files with 159975 additions and 0 deletions
@@ -0,0 +1,135 @@
+---
+title: Your First LLM Extraction with Instructor
+description: Step-by-step tutorial for your first structured data extraction from language models using Instructor and Pydantic.
+---
+
+# Your First LLM Extraction: Structured Outputs Tutorial
+
+Learn how to extract structured data from LLMs using Instructor in this hands-on tutorial. We'll build a simple yet powerful example that demonstrates how to transform unstructured text into validated Python objects using GPT-4, Claude, or any supported LLM.
+
+## Quick Start: Extract Structured Data from LLMs
+
+This LLM tutorial shows you how to extract structured information from natural language. We'll parse a person's name and age - a perfect starting point for understanding Instructor's power:
+
+```python
+from pydantic import BaseModel
+import instructor
+# 1. Define your data model for LLM extraction
+class Person(BaseModel):
+    name: str
+    age: int
+
+# 2. Initialize Instructor with your LLM provider
+client = instructor.from_provider("openai/gpt-5-nano")
+
+# 3. Extract structured data from LLM
+person = client.create(
+    response_model=Person,   # Type-safe extraction
+    messages=[
+        {"role": "user", "content": "John Doe is 30 years old"}
+    ]
+)
+
+# 4. Use validated, structured data from LLM
+print(f"Name: {person.name}, Age: {person.age}")
+# Output: Name: John Doe, Age: 30
+```
+
+## How Instructor LLM Extraction Works
+
+```
+┌─────────────┐    ┌──────────────┐    ┌─────────────┐
+│ Define      │ -> │ Instruct LLM │ -> │ Get Typed   │
+│ Structure   │    │ to Extract   │    │ Response    │
+└─────────────┘    └──────────────┘    └─────────────┘
+```
+
+Understanding the LLM structured output pipeline:
+
+### Step 1: Define Your LLM Output Schema
+
+```python
+class Person(BaseModel):
+    name: str
+    age: int
+```
+
+Pydantic models define the structure for LLM outputs:
+- `name`: String field for extracting names from LLM
+- `age`: Integer field with automatic type validation
+
+### Step 2: Configure Your LLM Client
+
+```python
+client = instructor.from_provider("openai/gpt-5-nano")
+```
+
+Instructor enhances your LLM client with structured output capabilities. Works with OpenAI, Anthropic, Google, and 15+ providers.
+
+### Step 3: Execute LLM Extraction
+
+```python
+person = client.create(
+    response_model=Person,
+    messages=[
+        {"role": "user", "content": "John Doe is 30 years old"}
+    ]
+)
+```
+
+Key parameters for structured LLM outputs:
+- `response_model`: Pydantic model for type-safe extraction
+- `messages`: Input text for the LLM to process
+
+Note: The model is already specified when creating the client with `from_provider()`, so you don't need to pass it again.
+
+### Step 4: Work with Validated LLM Data
+
+```python
+print(f"Name: {person.name}, Age: {person.age}")
+```
+
+Get back a fully validated Python object from your LLM - no JSON parsing, no validation errors, just clean data ready to use.
+
+## Enhance LLM Extraction with Field Descriptions
+
+Improve LLM accuracy by providing clear field descriptions:
+
+```python
+from pydantic import BaseModel, Field
+
+class Person(BaseModel):
+    name: str = Field(description="Person's full name")
+    age: int = Field(description="Person's age in years")
+```
+
+Field descriptions act as prompts, guiding the LLM to extract exactly what you need.
+
+## Handle Optional Data in LLM Responses
+
+Real-world LLM extractions often have missing data. Handle it gracefully:
+
+```python
+from typing import Optional
+
+class Person(BaseModel):
+    name: str
+    age: Optional[int] = None  # Now age is optional
+```
+
+## Continue Your LLM Tutorial Journey
+
+You've successfully extracted structured data from an LLM! Next steps:
+
+1. **[Advanced Response Models](response_models.md)** - Complex schemas for LLM outputs
+2. **[Multi-Provider Setup](../../concepts/from_provider.md)** - Use GPT-4, Claude, Gemini interchangeably
+3. **[Production Patterns](../patterns/simple_object.md)** - Real-world LLM extraction examples
+
+## Common LLM Extraction Patterns
+
+- **Entity Extraction**: Names, dates, locations from unstructured text
+- **Sentiment Analysis**: Structured sentiment scores with reasoning
+- **Data Classification**: Categorize text into predefined schemas
+- **Information Parsing**: Convert documents into structured databases
+
+Ready to build more complex LLM extractions? Continue to [Response Models](response_models.md) →
@@ -0,0 +1,147 @@
+---
+title: Installing Instructor for LLM Structured Outputs
+description: Complete installation guide for Instructor with support for OpenAI, Anthropic, Google, and 15+ LLM providers. Get started in minutes.
+---
+
+# Instructor Installation Guide: Setup for LLM Structured Outputs
+
+Learn how to install Instructor, the leading Python library for extracting structured data from LLMs like GPT-4, Claude, and Gemini. This comprehensive installation tutorial covers all major LLM providers and gets you ready for production use.
+
+## Quick Start: Install Instructor for LLM Development
+
+Get started with structured LLM outputs in seconds. Install Instructor using pip:
+
+```shell
+pip install instructor
+```
+
+Instructor leverages Pydantic for type-safe LLM data extraction:
+
+```shell
+pip install pydantic
+```
+
+> **Pro Tip**: Use `uv` for faster installation: `uv pip install instructor`
+
+## LLM Provider Installation Guide
+
+Instructor supports 15+ LLM providers. Here's how to install and configure each:
+
+### OpenAI (GPT-4, GPT-3.5)
+
+OpenAI is the default LLM provider for Instructor. Perfect for GPT-4 and GPT-3.5-turbo structured outputs:
+
+```shell
+pip install instructor
+```
+
+Configure your OpenAI API key for LLM access:
+
+```shell
+export OPENAI_API_KEY=your_openai_key
+```
+
+### Anthropic Claude LLM Setup
+
+Extract structured data from Claude 3 models (Opus, Sonnet, Haiku) with native tool support:
+
+```shell
+pip install "instructor[anthropic]"
+```
+
+Configure Claude API access:
+
+```shell
+export ANTHROPIC_API_KEY=your_anthropic_key
+```
+
+### Google Gemini LLM Integration
+
+Use Gemini Pro and Flash models for structured outputs with function calling:
+
+```shell
+pip install "instructor[google-genai]"
+```
+
+Set up Gemini API access:
+
+```shell
+export GOOGLE_API_KEY=your_google_key
+```
+
+### Cohere
+
+To use with Cohere's models:
+
+```shell
+pip install "instructor[cohere]"
+```
+
+Set up your Cohere API key:
+
+```shell
+export COHERE_API_KEY=your_cohere_key
+```
+
+### Mistral
+
+To use with Mistral AI's models:
+
+```shell
+pip install "instructor[mistralai]"
+```
+
+Set up your Mistral API key:
+
+```shell
+export MISTRAL_API_KEY=your_mistral_key
+```
+
+### LiteLLM (Multiple Providers)
+
+To use LiteLLM for accessing multiple providers:
+
+```shell
+pip install "instructor[litellm]"
+```
+
+Set up API keys for the providers you want to use.
+
+## Verify Your Instructor LLM Setup
+
+Test your Instructor installation with this simple LLM structured output example:
+
+```python
+import instructor
+from pydantic import BaseModel
+class Person(BaseModel):
+    name: str
+    age: int
+
+client = instructor.from_provider("openai/gpt-5-nano")
+person = client.create(
+    model="gpt-5.4-mini",
+    response_model=Person,
+    messages=[
+        {"role": "user", "content": "John Doe is 30 years old"}
+    ]
+)
+
+print(f"Name: {person.name}, Age: {person.age}")
+```
+
+## Next Steps in Your LLM Tutorial Journey
+
+With Instructor installed, you're ready to build powerful LLM applications:
+
+1. **[Create Your First LLM Extraction](first_extraction.md)** - Build structured outputs with any LLM
+2. **[Master Response Models](response_models.md)** - Learn Pydantic models for LLM data validation
+3. **[Configure LLM Clients](../../concepts/from_provider.md)** - Set up OpenAI, Anthropic, Google, and more
+
+## Common Installation Issues
+
+- **Import Errors**: Ensure you've installed the provider-specific extras (e.g., `instructor[anthropic]`)
+- **API Key Issues**: Verify your environment variables are set correctly
+- **Version Conflicts**: Use `pip install --upgrade instructor` to get the latest version
+
+Ready to extract structured data from LLMs? Continue to [Your First Extraction](first_extraction.md) →
@@ -0,0 +1,202 @@
+---
+title: Understanding Response Models in Instructor
+description: Learn how to create response models with Pydantic to define structure, validation rules, and extract complex data from LLMs.
+---
+
+# Understanding Response Models
+
+Response models are at the core of Instructor's functionality. They define the structure of the data you want to extract and provide validation rules. This guide explains how to create different types of response models for various use cases.
+
+## Basic Models
+
+Let's start with a simple model similar to what we've seen before:
+
+```python
+from pydantic import BaseModel
+
+class User(BaseModel):
+    name: str
+    age: int
+```
+
+This defines a model with two required fields: `name` (a string) and `age` (an integer).
+
+## Adding Field Metadata
+
+You can add metadata to fields using the `Field` class:
+
+```python
+from pydantic import BaseModel, Field
+
+class WeatherForecast(BaseModel):
+    """Weather forecast for a specific location"""
+
+    temperature: float = Field(
+        description="Current temperature in Celsius"
+    )
+    condition: str = Field(
+        description="Weather condition (sunny, cloudy, rainy, etc.)"
+    )
+    humidity: int = Field(
+        description="Humidity percentage from 0-100"
+    )
+```
+
+Field descriptions help the LLM understand what information to extract for each field.
+
+## Field Validation
+
+You can add validation rules to ensure the extracted data meets your requirements:
+
+```python
+from pydantic import BaseModel, Field
+
+class Product(BaseModel):
+    name: str = Field(min_length=3)
+    price: float = Field(gt=0)  # greater than 0
+    quantity: int = Field(ge=0)  # greater than or equal to 0
+    description: str = Field(max_length=500)
+```
+
+Common validation parameters include:
+- `min_length`/`max_length`: For strings
+- `ge`/`gt`/`le`/`lt`: For numbers (greater/less than or equal/than)
+- `pattern`: For regex pattern matching
+
+For more on validation, see the [Field Validation](../patterns/field_validation.md) and [Validation Basics](../validation/basics.md) guides.
+
+## Nested Models
+
+You can create complex data structures with nested models:
+
+```python
+from pydantic import BaseModel, Field
+from typing import List, Optional
+
+class Address(BaseModel):
+    street: str
+    city: str
+    state: Optional[str] = None
+    country: str
+
+class User(BaseModel):
+    name: str
+    age: int
+    addresses: List[Address]
+```
+
+This allows you to extract hierarchical data structures. For more examples, check out the [Simple Nested Structure](../patterns/nested_structure.md) guide.
+
+## Using Enums
+
+Enums help when you want to restrict a field to a set of specific values:
+
+```python
+from enum import Enum
+from pydantic import BaseModel
+
+class UserType(str, Enum):
+    ADMIN = "admin"
+    REGULAR = "regular"
+    GUEST = "guest"
+
+class User(BaseModel):
+    name: str
+    user_type: UserType
+```
+
+## Optional Fields
+
+For fields that might not be present in the source text:
+
+```python
+from typing import Optional
+from pydantic import BaseModel
+
+class Contact(BaseModel):
+    name: str
+    email: str
+    phone: Optional[str] = None
+    address: Optional[str] = None
+```
+
+For more about working with optional fields, see the [Optional Fields](../patterns/optional_fields.md) guide.
+
+## Lists and Arrays
+
+To extract multiple items of the same type:
+
+```python
+from typing import List
+from pydantic import BaseModel
+
+class BlogPost(BaseModel):
+    title: str
+    content: str
+    tags: List[str]
+```
+
+For more about working with lists, see the [List Extraction](../patterns/list_extraction.md) guide.
+
+## Using Your Models with Instructor
+
+Once you've defined your model, you can use it for extraction:
+
+```python
+import instructor
+client = instructor.from_provider("openai/gpt-5-nano")
+
+forecast = client.create(
+    model="gpt-5.4-mini",
+    response_model=WeatherForecast,
+    messages=[
+        {"role": "user", "content": "What's the weather in New York today?"}
+    ]
+)
+
+print(forecast.model_dump_json(indent=2))
+```
+
+## Model Documentation
+
+You can add documentation to your models using docstrings and field descriptions:
+
+```python
+from pydantic import BaseModel, Field
+
+class Investment(BaseModel):
+    """Represents an investment opportunity with risk and return details."""
+
+    name: str = Field(description="Name of the investment")
+    amount: float = Field(description="Investment amount in USD")
+    expected_return: float = Field(description="Expected annual return percentage")
+    risk_level: str = Field(description="Risk level (low, medium, high)")
+```
+
+This documentation helps both the LLM understand what to extract and makes your code more maintainable.
+
+## Advanced Validation with Validators
+
+For more complex validation rules, you can use validator methods:
+
+```python
+from pydantic import BaseModel, Field, field_validator
+from datetime import date
+
+class Reservation(BaseModel):
+    check_in: date
+    check_out: date
+    guests: int = Field(ge=1)
+
+    @field_validator("check_out")
+    def check_dates(cls, v, values):
+        if "check_in" in values.data and v <= values.data["check_in"]:
+            raise ValueError("check_out must be after check_in")
+        return v
+```
+
+For more advanced validation techniques, check out the [Custom Validators](../validation/custom_validators.md) guide.
+
+## Next Steps
+
+In the next section, learn about [from_provider](../../concepts/from_provider.md) to configure different LLM providers and understand the various modes of operation.
@@ -0,0 +1,148 @@
+---
+title: Getting Started with Structured LLM Outputs
+description: Learn the basics of extracting structured data from language models using Instructor. Understand the difference between unstructured and structured outputs.
+---
+
+# Getting Started with Structured Outputs
+
+Large language models (LLMs) are powerful tools for generating text, but extracting structured data from their outputs can be challenging. Structured outputs solve this problem by having LLMs return data in consistent, machine-readable formats.
+
+## The Problem with Unstructured Outputs
+
+Let's look at what happens when we ask an LLM to extract information without any structure:
+
+```python
+from openai import OpenAI
+
+client = OpenAI()
+response = client.create(
+    model="gpt-5.4-mini",
+    messages=[
+        {
+            "role": "user",
+            "content": "Extract customer: John Doe, age 35, email: john@example.com",
+        }
+    ],
+)
+
+print(response.choices[0].message.content)
+```
+
+The output might look like:
+```
+Customer Name: John Doe
+Age: 35
+Email: john@example.com
+```
+
+Or it could be:
+```
+I found the following customer information:
+- Name: John Doe
+- Age: 35
+- Email address: john@example.com
+```
+
+This inconsistency makes it difficult to reliably parse the information in downstream applications.
+
+## The Solution: Structured Outputs with Instructor
+
+Instructor solves this problem by using Pydantic models to define the expected structure of the output:
+
+```python
+import instructor
+from pydantic import BaseModel, Field, EmailStr
+class Customer(BaseModel):
+    name: str = Field(description="Customer's full name")
+    age: int = Field(description="Customer's age in years", ge=0, le=120)
+    email: EmailStr = Field(description="Customer's email address")
+
+client = instructor.from_provider("openai/gpt-5-nano")
+customer = client.create(
+    model="gpt-5.4-mini",
+    messages=[
+        {
+            "role": "user",
+            "content": "Extract customer: John Doe, age 35, email: john@example.com",
+        }
+    ],
+    response_model=Customer,  # This is the key part
+)
+
+print(customer)  # Customer(name='John Doe', age=35, email='john@example.com')
+print(f"Name: {customer.name}, Age: {customer.age}, Email: {customer.email}")
+```
+
+The benefits of this approach include:
+
+1. **Consistency**: Always get data in the same format
+2. **Validation**: Age must be between 0 and 120, email must be valid
+3. **Type Safety**: `age` is always an integer, not a string
+4. **Documentation**: Model fields are self-documenting with descriptions
+
+## Complex Example: Nested Structures
+
+Instructor shines with complex data structures:
+
+```python
+from typing import List, Optional
+from pydantic import BaseModel, Field
+import instructor
+client = instructor.from_provider("openai/gpt-5-nano")
+
+class Address(BaseModel):
+    street: str
+    city: str
+    state: str
+    zip_code: str
+
+class Contact(BaseModel):
+    email: Optional[str] = None
+    phone: Optional[str] = None
+
+class Person(BaseModel):
+    name: str
+    age: int
+    occupation: str
+    address: Address
+    contact: Contact
+    skills: List[str] = Field(description="List of professional skills")
+
+person = client.create(
+    model="gpt-5.4-mini",
+    messages=[
+        {
+            "role": "user",
+            "content": """
+        Extract detailed information for this person:
+        John Smith is a 42-year-old software engineer living at 123 Main St, San Francisco, CA 94105.
+        His email is john.smith@example.com and phone is 555-123-4567.
+        John is skilled in Python, JavaScript, and cloud architecture.
+        """,
+        }
+    ],
+    response_model=Person,
+)
+
+print(f"Name: {person.name}")
+print(f"Location: {person.address.city}, {person.address.state}")
+print(f"Skills: {', '.join(person.skills)}")
+```
+
+## Installation
+
+To get started with Instructor, install it via pip:
+
+```shell
+pip install instructor pydantic
+```
+
+You'll also need to set up your API keys for the LLM provider you're using.
+
+## Next Steps
+
+In the next sections, you'll learn how to:
+
+1. Create your [first extraction](first_extraction.md)
+2. Understand the different [response models](response_models.md) you can create
+3. Set up [clients for various LLM providers](../../concepts/from_provider.md)