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.

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:

import instructor
from instructor import Mode

client = instructor.from_provider(
    "anthropic/claude-3-5-haiku-latest",
    mode=Mode.ANTHROPIC_TOOLS,
)

After:

import instructor
from instructor import Mode

client = instructor.from_provider(
    "anthropic/claude-3-5-haiku-latest",
    mode=Mode.TOOLS,
)

Example: Bedrock¶

Before:

import instructor
from instructor import Mode

client = instructor.from_provider(
    "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0",
    mode=Mode.BEDROCK_TOOLS,
)

After:

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 for details.