tessl/pypi-instructor

Structured outputs for LLMs with type safety, validation, and automatic retries

—

Pending

Overview

Eval results

Files

Provider Support

Name: tessl/pypi-instructor
Author: tessl

The instructor package supports multiple LLM providers through dedicated factory functions and auto-detection capabilities. Each provider has specific configuration options and supported modes.

Provider Factory Functions

OpenAI

Create Instructor clients from OpenAI clients with full feature support.

def from_openai(
    client: openai.OpenAI | openai.AsyncOpenAI,
    mode: instructor.Mode = instructor.Mode.TOOLS,
    **kwargs: Any
) -> Instructor | AsyncInstructor:
    """
    Create Instructor from OpenAI client.
    
    Args:
        client: OpenAI synchronous or asynchronous client
        mode: Extraction mode (TOOLS, JSON, TOOLS_STRICT, etc.)
        **kwargs: Additional configuration options
        
    Returns:
        Configured Instructor or AsyncInstructor instance
    """

Usage Examples

import instructor
from openai import OpenAI, AsyncOpenAI

# Synchronous client
openai_client = OpenAI(api_key="your-key")
client = instructor.from_openai(
    openai_client, 
    mode=instructor.Mode.TOOLS
)

# Asynchronous client
async_openai_client = AsyncOpenAI(api_key="your-key") 
async_client = instructor.from_openai(
    async_openai_client,
    mode=instructor.Mode.TOOLS_STRICT
)

# Different modes
json_client = instructor.from_openai(
    openai_client,
    mode=instructor.Mode.JSON
)

parallel_client = instructor.from_openai(
    openai_client, 
    mode=instructor.Mode.PARALLEL_TOOLS
)

Anthropic

Create Instructor clients from Anthropic clients with tool and JSON support.

def from_anthropic(
    client: anthropic.Anthropic | anthropic.AsyncAnthropic | ...,
    mode: instructor.Mode = instructor.Mode.ANTHROPIC_TOOLS,
    beta: bool = False,
    **kwargs: Any
) -> instructor.Instructor | instructor.AsyncInstructor:
    """
    Create Instructor from Anthropic client.
    
    Args:
        client: Anthropic synchronous or asynchronous client
        mode: Extraction mode (ANTHROPIC_TOOLS, ANTHROPIC_JSON, etc.)
        beta: Enable beta features
        **kwargs: Additional configuration options
        
    Returns:
        Configured Instructor or AsyncInstructor instance
    """

Usage Examples

import instructor
from anthropic import Anthropic, AsyncAnthropic

# Synchronous client
anthropic_client = Anthropic(api_key="your-key")
client = instructor.from_anthropic(
    anthropic_client,
    mode=instructor.Mode.ANTHROPIC_TOOLS
)

# Asynchronous client
async_anthropic_client = AsyncAnthropic(api_key="your-key")
async_client = instructor.from_anthropic(
    async_anthropic_client,
    mode=instructor.Mode.ANTHROPIC_TOOLS
)

# JSON mode
json_client = instructor.from_anthropic(
    anthropic_client,
    mode=instructor.Mode.ANTHROPIC_JSON
)

# Reasoning tools (beta)
reasoning_client = instructor.from_anthropic(
    anthropic_client,
    mode=instructor.Mode.ANTHROPIC_REASONING_TOOLS,
    beta=True
)

# Parallel tools
parallel_client = instructor.from_anthropic(
    anthropic_client,
    mode=instructor.Mode.ANTHROPIC_PARALLEL_TOOLS
)

Google Providers

Gemini (Deprecated)

def from_gemini(
    client: Any,
    mode: instructor.Mode = instructor.Mode.GEMINI_TOOLS,
    **kwargs: Any
) -> instructor.Instructor:
    """
    Create Instructor from Gemini client (deprecated).
    
    Args:
        client: Gemini client instance
        mode: Extraction mode
        **kwargs: Additional configuration options
        
    Returns:
        Configured Instructor instance
    """

Google GenAI

def from_genai(
    client: Any,
    mode: instructor.Mode = instructor.Mode.GEMINI_TOOLS, 
    **kwargs: Any
) -> instructor.Instructor:
    """
    Create Instructor from Google GenAI client.
    
    Args:
        client: Google GenAI client instance
        mode: Extraction mode
        **kwargs: Additional configuration options
        
    Returns:
        Configured Instructor instance
    """

Vertex AI

def from_vertexai(
    client: Any,
    mode: instructor.Mode = instructor.Mode.VERTEXAI_TOOLS,
    **kwargs: Any
) -> instructor.Instructor:
    """
    Create Instructor from Vertex AI client.
    
    Args:
        client: Vertex AI client instance  
        mode: Extraction mode
        **kwargs: Additional configuration options
        
    Returns:
        Configured Instructor instance
    """

Google Usage Examples

import instructor
import google.generativeai as genai
from vertexai.preview.generative_models import GenerativeModel

# GenAI client
genai.configure(api_key="your-key")
genai_model = genai.GenerativeModel('gemini-pro')
client = instructor.from_genai(genai_model)

# Vertex AI client  
vertexai_model = GenerativeModel("gemini-pro")
client = instructor.from_vertexai(vertexai_model)

Other Provider Functions

LiteLLM

def from_litellm(
    client: Any,
    mode: instructor.Mode = instructor.Mode.TOOLS,
    **kwargs: Any
) -> instructor.Instructor:
    """
    Create Instructor from LiteLLM client.
    
    Args:
        client: LiteLLM client instance
        mode: Extraction mode
        **kwargs: Additional configuration options
        
    Returns:
        Configured Instructor instance
    """

Fireworks AI

def from_fireworks(
    client: Any,
    mode: instructor.Mode = instructor.Mode.TOOLS,
    **kwargs: Any
) -> instructor.Instructor:
    """
    Create Instructor from Fireworks client.
    
    Args:
        client: Fireworks AI client instance
        mode: Extraction mode
        **kwargs: Additional configuration options
        
    Returns:
        Configured Instructor instance
    """

Cerebras

def from_cerebras(
    client: Any,
    mode: instructor.Mode = instructor.Mode.TOOLS,
    **kwargs: Any
) -> instructor.Instructor:
    """
    Create Instructor from Cerebras client.
    
    Args:
        client: Cerebras client instance
        mode: Extraction mode
        **kwargs: Additional configuration options
        
    Returns:
        Configured Instructor instance
    """

Groq

def from_groq(
    client: Any,
    mode: instructor.Mode = instructor.Mode.TOOLS,
    **kwargs: Any
) -> instructor.Instructor:
    """
    Create Instructor from Groq client.
    
    Args:
        client: Groq client instance
        mode: Extraction mode
        **kwargs: Additional configuration options
        
    Returns:
        Configured Instructor instance
    """

Mistral AI

def from_mistral(
    client: Any,
    mode: instructor.Mode = instructor.Mode.MISTRAL_TOOLS,
    **kwargs: Any
) -> instructor.Instructor:
    """
    Create Instructor from Mistral client.
    
    Args:
        client: Mistral AI client instance
        mode: Extraction mode (typically MISTRAL_TOOLS)
        **kwargs: Additional configuration options
        
    Returns:
        Configured Instructor instance
    """

Cohere

def from_cohere(
    client: Any,
    mode: instructor.Mode = instructor.Mode.TOOLS,
    **kwargs: Any
) -> instructor.Instructor:
    """
    Create Instructor from Cohere client.
    
    Args:
        client: Cohere client instance
        mode: Extraction mode
        **kwargs: Additional configuration options
        
    Returns:
        Configured Instructor instance
    """

AWS Bedrock

def from_bedrock(
    client: Any,
    mode: instructor.Mode = instructor.Mode.ANTHROPIC_TOOLS,
    **kwargs: Any
) -> instructor.Instructor:
    """
    Create Instructor from AWS Bedrock client.
    
    Args:
        client: AWS Bedrock client instance
        mode: Extraction mode
        **kwargs: Additional configuration options
        
    Returns:
        Configured Instructor instance
    """

Writer

def from_writer(
    client: Any,
    mode: instructor.Mode = instructor.Mode.TOOLS,
    **kwargs: Any
) -> instructor.Instructor:
    """
    Create Instructor from Writer client.
    
    Args:
        client: Writer client instance
        mode: Extraction mode
        **kwargs: Additional configuration options
        
    Returns:
        Configured Instructor instance
    """

xAI

def from_xai(
    client: Any,
    mode: instructor.Mode = instructor.Mode.TOOLS,
    **kwargs: Any
) -> instructor.Instructor:
    """
    Create Instructor from xAI client.
    
    Args:
        client: xAI client instance
        mode: Extraction mode
        **kwargs: Additional configuration options
        
    Returns:
        Configured Instructor instance
    """

Perplexity

def from_perplexity(
    client: Any,
    mode: instructor.Mode = instructor.Mode.TOOLS,
    **kwargs: Any
) -> instructor.Instructor:
    """
    Create Instructor from Perplexity client.
    
    Args:
        client: Perplexity client instance
        mode: Extraction mode
        **kwargs: Additional configuration options
        
    Returns:
        Configured Instructor instance
    """

Auto-Detection

from_provider()

Automatically detect the provider type and create appropriate client.

def from_provider(
    client: Any,
    **kwargs: Any
) -> instructor.Instructor:
    """
    Auto-detect provider and create Instructor client.
    
    Args:
        client: Any supported LLM client
        **kwargs: Additional configuration options
        
    Returns:
        Configured Instructor instance with detected provider
        
    Raises:
        ValueError: If provider cannot be detected
    """

Usage Examples

import instructor
from openai import OpenAI
from anthropic import Anthropic

# Auto-detect OpenAI
openai_client = OpenAI()
client = instructor.from_provider(openai_client)

# Auto-detect Anthropic  
anthropic_client = Anthropic()
client = instructor.from_provider(anthropic_client)

# Works with any supported provider
various_clients = [openai_client, anthropic_client, gemini_client, groq_client]
for llm_client in various_clients:
    instructor_client = instructor.from_provider(llm_client)
    # Use instructor_client normally

Provider Support Matrix

Provider	Sync	Async	Tools	JSON	Streaming	Batch	Multimodal
OpenAI	✓	✓	✓	✓	✓	✓	✓
Anthropic	✓	✓	✓	✓	✓	✓	✓
Google GenAI	✓	✗	✓	✓	✓	✗	✓
Vertex AI	✓	✗	✓	✓	✓	✗	✓
Mistral	✓	✗	✓	✗	✓	✗	✗
Groq	✓	✗	✓	✗	✓	✗	✗
Cohere	✓	✗	✓	✗	✓	✗	✗
Fireworks	✓	✗	✓	✗	✓	✗	✗
LiteLLM	✓	✓	✓	✓	✓	Varies	Varies

Provider Enum

from instructor import Provider

class Provider(Enum):
    """LLM provider enumeration."""
    OPENAI = "openai"
    ANTHROPIC = "anthropic"
    GEMINI = "gemini"
    VERTEXAI = "vertexai"
    MISTRAL = "mistral"
    COHERE = "cohere"
    GROQ = "groq"
    FIREWORKS = "fireworks"
    CEREBRAS = "cerebras"
    WRITER = "writer"
    XAI = "xai"
    PERPLEXITY = "perplexity"
    BEDROCK = "bedrock"
    LITELLM = "litellm"

Configuration Examples

Provider-Specific Settings

# OpenAI with custom settings
client = instructor.from_openai(
    OpenAI(
        api_key="your-key",
        base_url="https://custom.openai.endpoint",
        timeout=30.0
    ),
    mode=instructor.Mode.TOOLS_STRICT
)

# Anthropic with custom settings
client = instructor.from_anthropic(
    Anthropic(
        api_key="your-key", 
        base_url="https://custom.anthropic.endpoint",
        timeout=60.0
    ),
    mode=instructor.Mode.ANTHROPIC_REASONING_TOOLS,
    beta=True
)

# LiteLLM with custom model routing
import litellm
client = instructor.from_litellm(
    litellm,
    mode=instructor.Mode.TOOLS
)

# Use with custom models via LiteLLM
result = client.create(
    model="claude-3-sonnet-20240229",  # Routed via LiteLLM
    messages=[{"role": "user", "content": "Extract data..."}],
    response_model=MyModel
)

Error Handling by Provider

try:
    client = instructor.from_provider(unknown_client)
except ValueError as e:
    print(f"Unsupported provider: {e}")
    # Fall back to manual provider selection
    if hasattr(unknown_client, 'chat'):
        # Looks like OpenAI-compatible
        client = instructor.from_openai(unknown_client)
    else:
        raise ValueError("Cannot determine provider type")

Install with Tessl CLI