115 lines
2.8 KiB
Markdown
115 lines
2.8 KiB
Markdown
|
---
|
||
|
|
title: Mode Migration Guide
|
||
|
|
description: Migrate from provider-specific modes to the core modes in Instructor.
|
||
|
|
---
|
||
|
|
|
||
|
|
# Mode Migration Guide
|
||
|
|
|
||
|
|
This guide helps you move from provider-specific modes to the core modes.
|
||
|
|
Core modes work across providers and are the recommended choice for new code.
|
||
|
|
|
||
|
|
!!! note "V2 Preview"
|
||
|
|
|
||
|
|
Provider-specific modes are deprecated in v2. They still work, emit warnings, and map to core modes.
|
||
|
|
|
||
|
|
## Core Modes
|
||
|
|
|
||
|
|
These are the core modes you should use:
|
||
|
|
|
||
|
|
- `TOOLS`: Tool or function calling
|
||
|
|
- `JSON_SCHEMA`: Native schema support when a provider has it
|
||
|
|
- `MD_JSON`: JSON extracted from text or code blocks
|
||
|
|
- `PARALLEL_TOOLS`: Multiple tool calls in one response
|
||
|
|
- `RESPONSES_TOOLS`: OpenAI Responses API tools
|
||
|
|
|
||
|
|
## Quick Mapping
|
||
|
|
|
||
|
|
Use this table to replace legacy modes:
|
||
|
|
|
||
|
|
| Legacy Mode | Core Mode |
|
||
|
|
|------------|-----------|
|
||
|
|
| `FUNCTIONS` | `TOOLS` |
|
||
|
|
| `TOOLS_STRICT` | `TOOLS` |
|
||
|
|
| `ANTHROPIC_TOOLS` | `TOOLS` |
|
||
|
|
| `ANTHROPIC_JSON` | `MD_JSON` |
|
||
|
|
| `COHERE_TOOLS` | `TOOLS` |
|
||
|
|
| `COHERE_JSON_SCHEMA` | `JSON_SCHEMA` |
|
||
|
|
| `XAI_TOOLS` | `TOOLS` |
|
||
|
|
| `XAI_JSON` | `MD_JSON` |
|
||
|
|
| `MISTRAL_TOOLS` | `TOOLS` |
|
||
|
|
| `MISTRAL_STRUCTURED_OUTPUTS` | `JSON_SCHEMA` |
|
||
|
|
| `FIREWORKS_TOOLS` | `TOOLS` |
|
||
|
|
| `FIREWORKS_JSON` | `MD_JSON` |
|
||
|
|
| `CEREBRAS_TOOLS` | `TOOLS` |
|
||
|
|
| `CEREBRAS_JSON` | `MD_JSON` |
|
||
|
|
| `WRITER_TOOLS` | `TOOLS` |
|
||
|
|
| `WRITER_JSON` | `MD_JSON` |
|
||
|
|
| `BEDROCK_TOOLS` | `TOOLS` |
|
||
|
|
| `BEDROCK_JSON` | `MD_JSON` |
|
||
|
|
| `PERPLEXITY_JSON` | `MD_JSON` |
|
||
|
|
| `VERTEXAI_TOOLS` | `TOOLS` |
|
||
|
|
| `VERTEXAI_JSON` | `MD_JSON` |
|
||
|
|
| `VERTEXAI_PARALLEL_TOOLS` | `PARALLEL_TOOLS` |
|
||
|
|
|
||
|
|
## Example: Anthropic
|
||
|
|
|
||
|
|
**Before:**
|
||
|
|
|
||
|
|
```python
|
||
|
|
import instructor
|
||
|
|
from instructor import Mode
|
||
|
|
|
||
|
|
client = instructor.from_provider(
|
||
|
|
"anthropic/claude-3-5-haiku-latest",
|
||
|
|
mode=Mode.ANTHROPIC_TOOLS,
|
||
|
|
)
|
||
|
|
```
|
||
|
|
|
||
|
|
**After:**
|
||
|
|
|
||
|
|
```python
|
||
|
|
import instructor
|
||
|
|
from instructor import Mode
|
||
|
|
|
||
|
|
client = instructor.from_provider(
|
||
|
|
"anthropic/claude-3-5-haiku-latest",
|
||
|
|
mode=Mode.TOOLS,
|
||
|
|
)
|
||
|
|
```
|
||
|
|
|
||
|
|
## Example: Bedrock
|
||
|
|
|
||
|
|
**Before:**
|
||
|
|
|
||
|
|
```python
|
||
|
|
import instructor
|
||
|
|
from instructor import Mode
|
||
|
|
|
||
|
|
client = instructor.from_provider(
|
||
|
|
"bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0",
|
||
|
|
mode=Mode.BEDROCK_TOOLS,
|
||
|
|
)
|
||
|
|
```
|
||
|
|
|
||
|
|
**After:**
|
||
|
|
|
||
|
|
```python
|
||
|
|
import instructor
|
||
|
|
from instructor import Mode
|
||
|
|
|
||
|
|
client = instructor.from_provider(
|
||
|
|
"bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0",
|
||
|
|
mode=Mode.BEDROCK_TOOLS,
|
||
|
|
)
|
||
|
|
```
|
||
|
|
|
||
|
|
## Notes
|
||
|
|
|
||
|
|
- Legacy modes still work but show a deprecation warning.
|
||
|
|
- Use core modes for new code and docs.
|
||
|
|
- Core tests are parameterized by provider and mode for consistent coverage.
|
||
|
|
- Streaming extraction is now handled by provider handlers instead of the DSL.
|
||
|
|
- Legacy `ResponseSchema.parse_*` helpers are deprecated. Use `process_response` or
|
||
|
|
`ResponseSchema.from_response` with core modes so the v2 registry handles parsing.
|
||
|
|
- See [Mode Comparison](../modes-comparison.md) for details.
|