docs(modes): add migration guide

Author: jxnl

docs/api.md

@@ -5,6 +5,10 @@ description: Explore the comprehensive API reference with details on instructors
 
 # API Reference
 
+Core modes are the recommended default. Legacy provider-specific modes still
+work but are deprecated and will show warnings. See the
+[Mode Migration Guide](concepts/mode-migration.md) for details.
+
 ::: instructor.from_provider
 
 ::: instructor.dsl.validators

docs/concepts/from_provider.md

@@ -189,13 +189,16 @@ client = instructor.from_provider(
 
 ## Default Modes
 
-Each provider uses a recommended default mode:
+Each provider uses a recommended default **core** mode:
 
-- **OpenAI**: `Mode.TOOLS` (function calling)
-- **Anthropic**: `Mode.ANTHROPIC_TOOLS` (tool use)
-- **Google**: `Mode.GENAI_TOOLS` (function calling)
-- **Ollama**: `Mode.TOOLS` (if model supports it) or `Mode.JSON`
-- **Others**: Provider-specific defaults
+- **OpenAI**: `Mode.TOOLS`
+- **Anthropic**: `Mode.TOOLS`
+- **Google**: `Mode.TOOLS` or `Mode.JSON` based on the model
+- **Ollama**: `Mode.TOOLS` (if supported) or `Mode.JSON`
+- **Others**: `Mode.TOOLS` or `Mode.MD_JSON` depending on capability
+
+Legacy provider-specific modes still work, but they are deprecated.
+See the [Mode Migration Guide](./mode-migration.md) for details.
 
 You can override these defaults with the `mode` parameter.
 

docs/concepts/mode-migration.md

@@ -0,0 +1,96 @@
+---
+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.
+
+## 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` |
+| `BEDROCK_TOOLS` | `TOOLS` |
+| `BEDROCK_JSON` | `MD_JSON` |
+
+## 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.TOOLS,
+)
+```
+
+## Notes
+
+- Legacy modes still work but show a deprecation warning.
+- Use core modes for new code and docs.
+- See [Mode Comparison](../modes-comparison.md) for details.

docs/integrations/bedrock.md

@@ -19,6 +19,7 @@ pip install "instructor[bedrock]"
 
 - [Getting Started](../getting-started.md) - Quick start guide
 - [from_provider Guide](../concepts/from_provider.md) - Detailed client configuration
+- [Mode Migration Guide](../concepts/mode-migration.md) - Move to core modes
 - [Provider Examples](../index.md#provider-examples) - Quick examples for all providers
 - [AWS Integration Guide](../examples/index.md#aws-integration) - More AWS examples
 
@@ -39,7 +40,7 @@ client = instructor.from_provider("bedrock/anthropic.claude-3-5-sonnet-20241022-
 # The auto client automatically handles:
 # - AWS credential detection from environment
 # - Region configuration (defaults to us-east-1)
-# - Mode selection based on model (Claude models use BEDROCK_TOOLS)
+# - Mode selection based on model (Claude models use TOOLS)
 ```
 
 ## Deprecation Notice
@@ -122,10 +123,13 @@ print(user)
 
 ## Supported Modes
 
-AWS Bedrock supports the following modes with Instructor:
+AWS Bedrock supports the following **core** modes:
 
-- `BEDROCK_TOOLS`: Uses function calling for models that support it (like Claude models)
-- `BEDROCK_JSON`: Direct JSON response generation
+- `TOOLS`: Uses function calling for models that support it (like Claude models)
+- `MD_JSON`: Direct JSON response generation (text extraction fallback)
+
+> Legacy modes (`BEDROCK_TOOLS`, `BEDROCK_JSON`) are deprecated and map to the core
+> modes above. Use `TOOLS` or `MD_JSON` in new code.
 
 ```python
 import boto3
@@ -134,11 +138,11 @@ from instructor import Mode
 from pydantic import BaseModel
 
 # Use from_provider for simplified setup
-client = instructor.from_provider("bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0", mode=Mode.BEDROCK_TOOLS)
+client = instructor.from_provider("bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0", mode=Mode.TOOLS)
 
 # Or if you need to use a custom boto3 client:
 # bedrock_client = boto3.client('bedrock-runtime')
-# client = instructor.from_provider("bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0", client=bedrock_client, mode=Mode.BEDROCK_TOOLS)
+# client = instructor.from_provider("bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0", client=bedrock_client, mode=Mode.TOOLS)
 
 class User(BaseModel):
     name: str
@@ -314,7 +318,7 @@ bedrock_client = boto3.client(
 client = instructor.from_provider(
     "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0",
     client=bedrock_client,
-    mode=instructor.Mode.BEDROCK_TOOLS
+    mode=instructor.Mode.TOOLS
 )
 
 # Advanced inference configuration