Mode Migration ↗

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:

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.