0
# Provider Support
1

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

4
## Provider Factory Functions
5

6
### OpenAI
7

8
Create Instructor clients from OpenAI clients with full feature support.
9

10
```python { .api }
11
def from_openai(
12
    client: openai.OpenAI | openai.AsyncOpenAI,
13
    mode: instructor.Mode = instructor.Mode.TOOLS,
14
    **kwargs: Any
15
) -> Instructor | AsyncInstructor:
16
    """
17
    Create Instructor from OpenAI client.
18
    
19
    Args:
20
        client: OpenAI synchronous or asynchronous client
21
        mode: Extraction mode (TOOLS, JSON, TOOLS_STRICT, etc.)
22
        **kwargs: Additional configuration options
23
        
24
    Returns:
25
        Configured Instructor or AsyncInstructor instance
26
    """
27
```
28

29
#### Usage Examples
30

31
```python { .api }
32
import instructor
33
from openai import OpenAI, AsyncOpenAI
34

35
# Synchronous client
36
openai_client = OpenAI(api_key="your-key")
37
client = instructor.from_openai(
38
    openai_client, 
39
    mode=instructor.Mode.TOOLS
40
)
41

42
# Asynchronous client
43
async_openai_client = AsyncOpenAI(api_key="your-key") 
44
async_client = instructor.from_openai(
45
    async_openai_client,
46
    mode=instructor.Mode.TOOLS_STRICT
47
)
48

49
# Different modes
50
json_client = instructor.from_openai(
51
    openai_client,
52
    mode=instructor.Mode.JSON
53
)
54

55
parallel_client = instructor.from_openai(
56
    openai_client, 
57
    mode=instructor.Mode.PARALLEL_TOOLS
58
)
59
```
60

61
### Anthropic
62

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

65
```python { .api }
66
def from_anthropic(
67
    client: anthropic.Anthropic | anthropic.AsyncAnthropic | ...,
68
    mode: instructor.Mode = instructor.Mode.ANTHROPIC_TOOLS,
69
    beta: bool = False,
70
    **kwargs: Any
71
) -> instructor.Instructor | instructor.AsyncInstructor:
72
    """
73
    Create Instructor from Anthropic client.
74
    
75
    Args:
76
        client: Anthropic synchronous or asynchronous client
77
        mode: Extraction mode (ANTHROPIC_TOOLS, ANTHROPIC_JSON, etc.)
78
        beta: Enable beta features
79
        **kwargs: Additional configuration options
80
        
81
    Returns:
82
        Configured Instructor or AsyncInstructor instance
83
    """
84
```
85

86
#### Usage Examples
87

88
```python { .api }
89
import instructor
90
from anthropic import Anthropic, AsyncAnthropic
91

92
# Synchronous client
93
anthropic_client = Anthropic(api_key="your-key")
94
client = instructor.from_anthropic(
95
    anthropic_client,
96
    mode=instructor.Mode.ANTHROPIC_TOOLS
97
)
98

99
# Asynchronous client
100
async_anthropic_client = AsyncAnthropic(api_key="your-key")
101
async_client = instructor.from_anthropic(
102
    async_anthropic_client,
103
    mode=instructor.Mode.ANTHROPIC_TOOLS
104
)
105

106
# JSON mode
107
json_client = instructor.from_anthropic(
108
    anthropic_client,
109
    mode=instructor.Mode.ANTHROPIC_JSON
110
)
111

112
# Reasoning tools (beta)
113
reasoning_client = instructor.from_anthropic(
114
    anthropic_client,
115
    mode=instructor.Mode.ANTHROPIC_REASONING_TOOLS,
116
    beta=True
117
)
118

119
# Parallel tools
120
parallel_client = instructor.from_anthropic(
121
    anthropic_client,
122
    mode=instructor.Mode.ANTHROPIC_PARALLEL_TOOLS
123
)
124
```
125

126
### Google Providers
127

128
#### Gemini (Deprecated)
129

130
```python { .api }
131
def from_gemini(
132
    client: Any,
133
    mode: instructor.Mode = instructor.Mode.GEMINI_TOOLS,
134
    **kwargs: Any
135
) -> instructor.Instructor:
136
    """
137
    Create Instructor from Gemini client (deprecated).
138
    
139
    Args:
140
        client: Gemini client instance
141
        mode: Extraction mode
142
        **kwargs: Additional configuration options
143
        
144
    Returns:
145
        Configured Instructor instance
146
    """
147
```
148

149
#### Google GenAI
150

151
```python { .api }
152
def from_genai(
153
    client: Any,
154
    mode: instructor.Mode = instructor.Mode.GEMINI_TOOLS, 
155
    **kwargs: Any
156
) -> instructor.Instructor:
157
    """
158
    Create Instructor from Google GenAI client.
159
    
160
    Args:
161
        client: Google GenAI client instance
162
        mode: Extraction mode
163
        **kwargs: Additional configuration options
164
        
165
    Returns:
166
        Configured Instructor instance
167
    """
168
```
169

170
#### Vertex AI
171

172
```python { .api }
173
def from_vertexai(
174
    client: Any,
175
    mode: instructor.Mode = instructor.Mode.VERTEXAI_TOOLS,
176
    **kwargs: Any
177
) -> instructor.Instructor:
178
    """
179
    Create Instructor from Vertex AI client.
180
    
181
    Args:
182
        client: Vertex AI client instance  
183
        mode: Extraction mode
184
        **kwargs: Additional configuration options
185
        
186
    Returns:
187
        Configured Instructor instance
188
    """
189
```
190

191
#### Google Usage Examples
192

193
```python { .api }
194
import instructor
195
import google.generativeai as genai
196
from vertexai.preview.generative_models import GenerativeModel
197

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

203
# Vertex AI client  
204
vertexai_model = GenerativeModel("gemini-pro")
205
client = instructor.from_vertexai(vertexai_model)
206
```
207

208
### Other Provider Functions
209

210
#### LiteLLM
211

212
```python { .api }
213
def from_litellm(
214
    client: Any,
215
    mode: instructor.Mode = instructor.Mode.TOOLS,
216
    **kwargs: Any
217
) -> instructor.Instructor:
218
    """
219
    Create Instructor from LiteLLM client.
220
    
221
    Args:
222
        client: LiteLLM client instance
223
        mode: Extraction mode
224
        **kwargs: Additional configuration options
225
        
226
    Returns:
227
        Configured Instructor instance
228
    """
229
```
230

231
#### Fireworks AI
232

233
```python { .api }
234
def from_fireworks(
235
    client: Any,
236
    mode: instructor.Mode = instructor.Mode.TOOLS,
237
    **kwargs: Any
238
) -> instructor.Instructor:
239
    """
240
    Create Instructor from Fireworks client.
241
    
242
    Args:
243
        client: Fireworks AI client instance
244
        mode: Extraction mode
245
        **kwargs: Additional configuration options
246
        
247
    Returns:
248
        Configured Instructor instance
249
    """
250
```
251

252
#### Cerebras
253

254
```python { .api }
255
def from_cerebras(
256
    client: Any,
257
    mode: instructor.Mode = instructor.Mode.TOOLS,
258
    **kwargs: Any
259
) -> instructor.Instructor:
260
    """
261
    Create Instructor from Cerebras client.
262
    
263
    Args:
264
        client: Cerebras client instance
265
        mode: Extraction mode
266
        **kwargs: Additional configuration options
267
        
268
    Returns:
269
        Configured Instructor instance
270
    """
271
```
272

273
#### Groq
274

275
```python { .api }
276
def from_groq(
277
    client: Any,
278
    mode: instructor.Mode = instructor.Mode.TOOLS,
279
    **kwargs: Any
280
) -> instructor.Instructor:
281
    """
282
    Create Instructor from Groq client.
283
    
284
    Args:
285
        client: Groq client instance
286
        mode: Extraction mode
287
        **kwargs: Additional configuration options
288
        
289
    Returns:
290
        Configured Instructor instance
291
    """
292
```
293

294
#### Mistral AI
295

296
```python { .api }
297
def from_mistral(
298
    client: Any,
299
    mode: instructor.Mode = instructor.Mode.MISTRAL_TOOLS,
300
    **kwargs: Any
301
) -> instructor.Instructor:
302
    """
303
    Create Instructor from Mistral client.
304
    
305
    Args:
306
        client: Mistral AI client instance
307
        mode: Extraction mode (typically MISTRAL_TOOLS)
308
        **kwargs: Additional configuration options
309
        
310
    Returns:
311
        Configured Instructor instance
312
    """
313
```
314

315
#### Cohere
316

317
```python { .api }
318
def from_cohere(
319
    client: Any,
320
    mode: instructor.Mode = instructor.Mode.TOOLS,
321
    **kwargs: Any
322
) -> instructor.Instructor:
323
    """
324
    Create Instructor from Cohere client.
325
    
326
    Args:
327
        client: Cohere client instance
328
        mode: Extraction mode
329
        **kwargs: Additional configuration options
330
        
331
    Returns:
332
        Configured Instructor instance
333
    """
334
```
335

336
#### AWS Bedrock
337

338
```python { .api }
339
def from_bedrock(
340
    client: Any,
341
    mode: instructor.Mode = instructor.Mode.ANTHROPIC_TOOLS,
342
    **kwargs: Any
343
) -> instructor.Instructor:
344
    """
345
    Create Instructor from AWS Bedrock client.
346
    
347
    Args:
348
        client: AWS Bedrock client instance
349
        mode: Extraction mode
350
        **kwargs: Additional configuration options
351
        
352
    Returns:
353
        Configured Instructor instance
354
    """
355
```
356

357
#### Writer
358

359
```python { .api }
360
def from_writer(
361
    client: Any,
362
    mode: instructor.Mode = instructor.Mode.TOOLS,
363
    **kwargs: Any
364
) -> instructor.Instructor:
365
    """
366
    Create Instructor from Writer client.
367
    
368
    Args:
369
        client: Writer client instance
370
        mode: Extraction mode
371
        **kwargs: Additional configuration options
372
        
373
    Returns:
374
        Configured Instructor instance
375
    """
376
```
377

378
#### xAI
379

380
```python { .api }
381
def from_xai(
382
    client: Any,
383
    mode: instructor.Mode = instructor.Mode.TOOLS,
384
    **kwargs: Any
385
) -> instructor.Instructor:
386
    """
387
    Create Instructor from xAI client.
388
    
389
    Args:
390
        client: xAI client instance
391
        mode: Extraction mode
392
        **kwargs: Additional configuration options
393
        
394
    Returns:
395
        Configured Instructor instance
396
    """
397
```
398

399
#### Perplexity
400

401
```python { .api }
402
def from_perplexity(
403
    client: Any,
404
    mode: instructor.Mode = instructor.Mode.TOOLS,
405
    **kwargs: Any
406
) -> instructor.Instructor:
407
    """
408
    Create Instructor from Perplexity client.
409
    
410
    Args:
411
        client: Perplexity client instance
412
        mode: Extraction mode
413
        **kwargs: Additional configuration options
414
        
415
    Returns:
416
        Configured Instructor instance
417
    """
418
```
419

420
## Auto-Detection
421

422
### from_provider()
423

424
Automatically detect the provider type and create appropriate client.
425

426
```python { .api }
427
def from_provider(
428
    client: Any,
429
    **kwargs: Any
430
) -> instructor.Instructor:
431
    """
432
    Auto-detect provider and create Instructor client.
433
    
434
    Args:
435
        client: Any supported LLM client
436
        **kwargs: Additional configuration options
437
        
438
    Returns:
439
        Configured Instructor instance with detected provider
440
        
441
    Raises:
442
        ValueError: If provider cannot be detected
443
    """
444
```
445

446
#### Usage Examples
447

448
```python { .api }
449
import instructor
450
from openai import OpenAI
451
from anthropic import Anthropic
452

453
# Auto-detect OpenAI
454
openai_client = OpenAI()
455
client = instructor.from_provider(openai_client)
456

457
# Auto-detect Anthropic  
458
anthropic_client = Anthropic()
459
client = instructor.from_provider(anthropic_client)
460

461
# Works with any supported provider
462
various_clients = [openai_client, anthropic_client, gemini_client, groq_client]
463
for llm_client in various_clients:
464
    instructor_client = instructor.from_provider(llm_client)
465
    # Use instructor_client normally
466
```
467

468
## Provider Support Matrix
469

470
| Provider | Sync | Async | Tools | JSON | Streaming | Batch | Multimodal |
471
|----------|------|-------|-------|------|-----------|-------|------------|
472
| OpenAI | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
473
| Anthropic | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
474
| Google GenAI | ✓ | ✗ | ✓ | ✓ | ✓ | ✗ | ✓ |
475
| Vertex AI | ✓ | ✗ | ✓ | ✓ | ✓ | ✗ | ✓ |
476
| Mistral | ✓ | ✗ | ✓ | ✗ | ✓ | ✗ | ✗ |
477
| Groq | ✓ | ✗ | ✓ | ✗ | ✓ | ✗ | ✗ |
478
| Cohere | ✓ | ✗ | ✓ | ✗ | ✓ | ✗ | ✗ |
479
| Fireworks | ✓ | ✗ | ✓ | ✗ | ✓ | ✗ | ✗ |
480
| LiteLLM | ✓ | ✓ | ✓ | ✓ | ✓ | Varies | Varies |
481
482
## Provider Enum
483

484
```python { .api }
485
from instructor import Provider
486

487
class Provider(Enum):
488
    """LLM provider enumeration."""
489
    OPENAI = "openai"
490
    ANTHROPIC = "anthropic"
491
    GEMINI = "gemini"
492
    VERTEXAI = "vertexai"
493
    MISTRAL = "mistral"
494
    COHERE = "cohere"
495
    GROQ = "groq"
496
    FIREWORKS = "fireworks"
497
    CEREBRAS = "cerebras"
498
    WRITER = "writer"
499
    XAI = "xai"
500
    PERPLEXITY = "perplexity"
501
    BEDROCK = "bedrock"
502
    LITELLM = "litellm"
503
```
504

505
## Configuration Examples
506

507
### Provider-Specific Settings
508

509
```python { .api }
510
# OpenAI with custom settings
511
client = instructor.from_openai(
512
    OpenAI(
513
        api_key="your-key",
514
        base_url="https://custom.openai.endpoint",
515
        timeout=30.0
516
    ),
517
    mode=instructor.Mode.TOOLS_STRICT
518
)
519

520
# Anthropic with custom settings
521
client = instructor.from_anthropic(
522
    Anthropic(
523
        api_key="your-key", 
524
        base_url="https://custom.anthropic.endpoint",
525
        timeout=60.0
526
    ),
527
    mode=instructor.Mode.ANTHROPIC_REASONING_TOOLS,
528
    beta=True
529
)
530

531
# LiteLLM with custom model routing
532
import litellm
533
client = instructor.from_litellm(
534
    litellm,
535
    mode=instructor.Mode.TOOLS
536
)
537

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

546
### Error Handling by Provider
547

548
```python { .api }
549
try:
550
    client = instructor.from_provider(unknown_client)
551
except ValueError as e:
552
    print(f"Unsupported provider: {e}")
553
    # Fall back to manual provider selection
554
    if hasattr(unknown_client, 'chat'):
555
        # Looks like OpenAI-compatible
556
        client = instructor.from_openai(unknown_client)
557
    else:
558
        raise ValueError("Cannot determine provider type")
559
```