> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Instructor structured output integration

> Combine the AI Gateway with Instructor for type-safe LLM responses. Generate Pydantic models and structured JSON outputs with validation and retries.

## AI Gateway

### Overview

Instructor is a library for extracting structured outputs from LLMs using Pydantic models. Connecting Instructor to Orq.ai's AI Gateway provides type-safe structured extraction with access to 300+ models through a single configuration change.

### Key Benefits

Orq.ai's AI Gateway enhances Instructor applications with:

<CardGroup cols={2}>
  <Card title="Complete Observability" icon="chart-line">
    Track every extraction, validation, and retry with detailed traces
  </Card>

  <Card title="Built-in Reliability" icon="shield-check">
    Automatic fallbacks, retries, and load balancing for production resilience
  </Card>

  <Card title="Cost Optimization" icon="chart-pie">
    Real-time cost tracking and spend management across all AI operations
  </Card>

  <Card title="Multi-Provider Access" icon="cubes">
    Access 300+ LLMs and 20+ providers through a single, unified integration
  </Card>
</CardGroup>

### Prerequisites

Before integrating Instructor with Orq.ai, ensure the following are in place:

* An Orq.ai account and [API Key](/docs/ai-gateway/configuration/api-keys)
* Python 3.8 or higher

<Info>
  To set up an API key, see [API keys & Endpoints](/docs/ai-gateway/configuration/api-keys).
</Info>

### Installation

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install instructor openai
```

### Configuration

Configure Instructor to use Orq.ai's AI Gateway by patching an OpenAI client with a custom `base_url`:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import instructor
from openai import OpenAI
import os

client = instructor.from_openai(OpenAI(
    base_url="https://api.orq.ai/v3/router",
    api_key=os.getenv("ORQ_API_KEY"),
))
```

> **base\_url**: `https://api.orq.ai/v3/router`

### Basic Extraction

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import instructor
from pydantic import BaseModel
from openai import OpenAI
import os

client = instructor.from_openai(OpenAI(
    base_url="https://api.orq.ai/v3/router",
    api_key=os.getenv("ORQ_API_KEY"),
))

class UserInfo(BaseModel):
    name: str
    age: int

user_info = client.chat.completions.create(
    model="openai/gpt-4o",
    response_model=UserInfo,
    messages=[{"role": "user", "content": "John Doe is 30 years old."}],
)

print(user_info.name)   # John Doe
print(user_info.age)    # 30
```

### Classification

Use Instructor with `Literal` types for classification:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import instructor
from pydantic import BaseModel, Field
from openai import OpenAI
from typing import Literal
import os

client = instructor.from_openai(OpenAI(
    base_url="https://api.orq.ai/v3/router",
    api_key=os.getenv("ORQ_API_KEY"),
))

class Sentiment(BaseModel):
    label: Literal["positive", "negative", "neutral"]
    confidence: float = Field(ge=0.0, le=1.0)

result = client.chat.completions.create(
    model="openai/gpt-4o",
    response_model=Sentiment,
    messages=[{"role": "user", "content": "Classify: 'This product is absolutely amazing!'"}],
)
print(f"Sentiment: {result.label}, Confidence: {result.confidence:.2f}")
```

### Model Selection

With Orq.ai, any supported model from 20+ providers can be used:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import instructor
from pydantic import BaseModel
from openai import OpenAI
import os

class UserInfo(BaseModel):
    name: str
    age: int

# Use Claude
claude_client = instructor.from_openai(OpenAI(
    base_url="https://api.orq.ai/v3/router",
    api_key=os.getenv("ORQ_API_KEY"),
))

result = claude_client.chat.completions.create(
    model="anthropic/claude-sonnet-4-6",
    response_model=UserInfo,
    messages=[{"role": "user", "content": "Jane Smith is 25 years old."}],
)
print(f"{result.name}, {result.age}")

# Use Gemini
gemini_client = instructor.from_openai(OpenAI(
    base_url="https://api.orq.ai/v3/router",
    api_key=os.getenv("ORQ_API_KEY"),
))

result = gemini_client.chat.completions.create(
    model="google-ai/gemini-2.5-flash",
    response_model=UserInfo,
    messages=[{"role": "user", "content": "Bob Johnson is 40 years old."}],
)
print(f"{result.name}, {result.age}")
```