feat(v2/anthropic): implement provider with mode registry integration

docs/integrations/anthropic.md

@@ -1,11 +1,11 @@
 ---
 title: "Anthropic Claude Tutorial: Structured Outputs with Instructor"
-description: "Complete guide to using Anthropic's Claude models with Instructor for structured data extraction. Learn how to use Claude 3 Opus, Sonnet, and Haiku for type-safe outputs in Python."
+description: "Complete guide to using Anthropic's Claude models with Instructor for structured data extraction. Learn how to use Claude Haiku for type-safe outputs in Python."
 ---
 
 # Anthropic Claude Tutorial: Structured Outputs with Instructor
 
-Learn how to use Anthropic's Claude models (Claude 3 Opus, Sonnet, and Haiku) with Instructor to extract structured, validated data. This tutorial covers everything from basic setup to advanced patterns for production use.
+Learn how to use Anthropic's Claude Haiku models with Instructor to extract structured, validated data. This tutorial covers everything from basic setup to advanced patterns for production use.
 
 ## Quick Start: Install Instructor for Claude
 
@@ -46,8 +46,8 @@ class User(BaseModel):
     properties: List[Properties] = Field(description="List of user properties")
 
 client = instructor.from_provider(
-    "anthropic/claude-3-5-haiku-latest",
-    mode=instructor.Mode.ANTHROPIC_TOOLS
+    "anthropic/claude-4-5-haiku-latest",
+    mode=instructor.Mode.TOOLS
 )
 
 try:
@@ -97,9 +97,9 @@ except Exception as e:
 import asyncio
 
 async_client = instructor.from_provider(
-    "anthropic/claude-3-5-haiku-latest",
+    "anthropic/claude-4-5-haiku-latest",
     async_client=True,
-    mode=instructor.Mode.ANTHROPIC_TOOLS,
+    mode=instructor.Mode.TOOLS,
 )
 
 async def extract_user():
@@ -114,6 +114,11 @@ print(user)
 
 ### Parallel Tool Calling
 
+Parallel tool mode is automatically detected when your response model is `Iterable[Union[Model1, Model2, ...]]`. Just use `Mode.TOOLS` (or let it default) and the handler will automatically:
+- Set tool_choice to "auto" (required for parallel)
+- Generate schemas for all union members
+- Return a generator yielding each tool result
+
 ```python
 from typing import Iterable, Literal
 from pydantic import BaseModel
@@ -129,9 +134,10 @@ class GoogleSearch(BaseModel):
     query: str
 
 
+# No need to specify Mode.PARALLEL_TOOLS - it's auto-detected!
 client = instructor.from_provider(
     "anthropic/claude-3-5-haiku-latest",
-    mode=instructor.Mode.ANTHROPIC_PARALLEL_TOOLS,
+    mode=instructor.Mode.TOOLS,  # or just omit and use default
 )
 
 results = client.chat.completions.create(
@@ -142,13 +148,19 @@ results = client.chat.completions.create(
             "content": "What is the weather in toronto and dallas and who won the super bowl?",
         },
     ],
-    response_model=Iterable[Weather | GoogleSearch],
+    response_model=Iterable[Weather | GoogleSearch],  # Auto-detects parallel mode
 )
 
 for item in results:
     print(item)
 ```
 
+**How it works**: When Instructor detects `Iterable[Union[...]]`, it automatically:
+1. Sets `tool_choice` to `"auto"` (allows model to call any tool)
+2. Generates tool schemas from all union members
+3. Returns a generator that yields each extracted tool call
+4. Each yielded item is validated against its corresponding Pydantic model
+
 ## Multimodal
 
 > We've provided a few different sample files for you to use to test out these new features. All examples below use these files.
@@ -185,7 +197,7 @@ class ImageDescription(BaseModel):
     colors: list[str] = Field(..., description="The colors in the image")
 
 
-client = instructor.from_provider("anthropic/claude-3-5-haiku-latest")
+client = instructor.from_provider("anthropic/claude-4-5-haiku-latest")
 url = "https://raw.githubusercontent.com/instructor-ai/instructor/main/tests/assets/image.jpg"
 # Multiple ways to load an image:
 response = client.chat.completions.create(
@@ -239,7 +251,7 @@ class Receipt(BaseModel):
     items: list[str]
 
 
-client = instructor.from_provider("anthropic/claude-3-5-haiku-latest")
+client = instructor.from_provider("anthropic/claude-4-5-haiku-latest")
 url = "https://raw.githubusercontent.com/instructor-ai/instructor/main/tests/assets/invoice.pdf"
 # Multiple ways to load an PDF:
 response = client.chat.completions.create(
@@ -281,7 +293,7 @@ class Receipt(BaseModel):
     items: list[str]
 
 
-client = instructor.from_provider("anthropic/claude-3-5-haiku-latest")
+client = instructor.from_provider("anthropic/claude-4-5-haiku-latest")
 url = "https://raw.githubusercontent.com/instructor-ai/instructor/main/tests/assets/invoice.pdf"
 # Multiple ways to load an PDF:
 response, completion = client.chat.completions.create_with_completion(
@@ -338,8 +350,8 @@ from pydantic import BaseModel, Field
 
 # Initialize client with explicit mode
 client = instructor.from_provider(
-    "anthropic/claude-3-5-haiku-latest",
-    mode=instructor.Mode.ANTHROPIC_TOOLS,
+    "anthropic/claude-4-5-haiku-latest",
+    mode=instructor.Mode.TOOLS,
 )
 
 # Define your model with proper annotations
@@ -387,7 +399,7 @@ from pydantic import BaseModel, Field
 
 # Initialize client with explicit mode
 client = from_provider(
-    mode=instructor.Mode.ANTHROPIC_TOOLS
+    mode=instructor.Mode.TOOLS
 )
 
 # Define your model with proper annotations
@@ -434,11 +446,22 @@ except Exception as e:
 
 We provide several modes to make it easy to work with the different response models that Anthropic supports
 
-1. `instructor.Mode.ANTHROPIC_JSON` : This uses the text completion API from the Anthropic API and then extracts out the desired response model from the text completion model
-2. `instructor.Mode.ANTHROPIC_TOOLS` : This uses Anthropic's [tools calling API](https://docs.anthropic.com/en/docs/build-with-claude/tool-use) to return structured outputs to the client
-3. `instructor.Mode.ANTHROPIC_PARALLEL_TOOLS` : Runs multiple tools in parallel and returns a list of tool calls
+1. `instructor.Mode.JSON` : This uses the text completion API from the Anthropic API and then extracts out the desired response model from the text completion model
+2. `instructor.Mode.TOOLS` : This uses Anthropic's [tools calling API](https://docs.anthropic.com/en/docs/build-with-claude/tool-use) to return structured outputs. Automatically detects parallel tools from `Iterable[Union[...]]` response models.
+3. `instructor.Mode.PARALLEL_TOOLS` : **Deprecated** - Use `Mode.TOOLS` with `Iterable[Union[Model1, Model2, ...]]` instead. Auto-detected automatically.
 
-In general, we recommend using `Mode.ANTHROPIC_TOOLS` because it's the best way to ensure you have the desired response schema that you want.
+### Mode Auto-Detection
+
+`Mode.TOOLS` now intelligently adapts based on your response model and parameters:
+
+| Response Model | Parameters | Behavior |
+|---|---|---|
+| `Model` | Regular | Single tool (forced) |
+| `Model` | `thinking={...}` | Single tool with extended thinking (auto) |
+| `Iterable[Union[Model1, Model2]]` | Regular | Parallel tools (auto) |
+| `Iterable[Union[Model1, Model2]]` | `thinking={...}` | Parallel with thinking |
+
+In general, we recommend using `Mode.TOOLS` because it automatically handles all these cases and is the best way to ensure you have the desired response schema.
 
 ## Caching
 
@@ -469,8 +492,9 @@ class Character(BaseModel):
     description: str = Field(description="A description of the character")
 
 # Initialize client with explicit mode and prompt caching
-client = instructor.from_provider("anthropic/claude-3-5-haiku-latest")
-    mode=instructor.Mode.ANTHROPIC_TOOLS,
+client = instructor.from_provider(
+    "anthropic/claude-4-5-haiku-latest",
+    mode=instructor.Mode.TOOLS,
 )
 
 try:
@@ -543,8 +567,9 @@ class ImageAnalyzer(BaseModel):
     scene_type: str = Field(description="Type of scene shown in the images (indoor, outdoor, etc.)")
 
 # Initialize client with explicit mode and image caching enabled
-client = instructor.from_provider("anthropic/claude-3-5-haiku-latest")
-    mode=instructor.Mode.ANTHROPIC_TOOLS,
+client = instructor.from_provider(
+    "anthropic/claude-4-5-haiku-latest",
+    mode=instructor.Mode.TOOLS,
 )
 
 try:
@@ -592,9 +617,11 @@ except Exception as e:
     print(f"Error during image analysis: {e}")
 ```
 
-## Thinking
+## Thinking (Extended Thinking)
 
-Anthropic recently released support for extended thinking with their `sonnet-3.7` model series. In instructor, we support getting a validated tool call with the `instructor.Mode.ANTHROPIC_REASONING_TOOLS` Mode as seen below.
+Anthropic supports extended thinking with their Claude models, enabling the model to think through complex problems before providing structured outputs. In Instructor, use `Mode.TOOLS` with the `thinking` parameter to enable this feature.
+
+### Using Extended Thinking with TOOLS
 
 ```python
 from anthropic import Anthropic
@@ -607,24 +634,38 @@ class Answer(BaseModel):
 
 
 client = Anthropic()
-client = instructor.from_provider("anthropic/claude-3-5-haiku-latest")
+client = instructor.from_provider(
+    "anthropic/claude-4-5-haiku-latest",
+    mode=instructor.Mode.TOOLS
+)
+
 response = client.chat.completions.create(
     response_model=Answer,
     messages=[
         {
             "role": "user",
-            "content": "Which is larger, 9.11 or 9.8",
+            "content": "Which is larger, 9.11 or 9.8?",
         },
     ],
     temperature=1,
     max_tokens=2000,
     thinking={"type": "enabled", "budget_tokens": 1024},
 )
 
-
-# Assertions to validate the response
+# Response is a validated Answer object
 assert isinstance(response, Answer)
 assert response.answer == 9.8
 ```
 
-This then returns the response as a validated `Answer` object.
+### How It Works
+
+When you provide the `thinking` parameter with `type: "enabled"`:
+
+1. **Automatic Mode Detection**: `Mode.TOOLS` automatically detects the thinking parameter and adjusts the tool choice strategy to `auto` (required by Anthropic's API when thinking is enabled)
+2. **Model Reasoning**: Claude uses the allocated `budget_tokens` to reason about the problem
+3. **Structured Output**: After reasoning, the model returns a valid tool call with your response model
+4. **Validation**: The response is automatically validated against your Pydantic model
+
+### Deprecation Notice
+
+`Mode.ANTHROPIC_REASONING_TOOLS` is deprecated. Use `Mode.TOOLS` with the `thinking` parameter instead. Both modes now support thinking, but using the standard `TOOLS` mode is preferred and more flexible.

docs/integrations/genai.md

@@ -20,15 +20,19 @@ This guide demonstrates how to use Instructor with Google's `genai` SDK to extra
 
 We currently have two modes for Gemini
 
-- `Mode.GENAI_TOOLS` : This leverages function calling under the hood and returns a structured response
-- `Mode.GENAI_STRUCTURED_OUTPUTS` : This provides Gemini with a JSON Schema that it will use to respond in a structured format with
+- `Mode.TOOLS` : This leverages function calling under the hood and returns a structured response
+- `Mode.JSON` : This provides Gemini with a JSON Schema that it will use to respond in a structured format with
 
 !!! info "Gemini Thought Parts Filtering"
 
-    When using `Mode.GENAI_TOOLS`, Instructor automatically filters out thought parts from Gemini responses. Gemini 2.5 models include internal reasoning parts with `thought: true` by default, which cannot be disabled. Instructor removes these thought parts before processing the structured output to prevent runtime errors.
+    When using `Mode.TOOLS`, Instructor automatically filters out thought parts from Gemini responses. Gemini 2.5 models include internal reasoning parts with `thought: true` by default, which cannot be disabled. Instructor removes these thought parts before processing the structured output to prevent runtime errors.
 
     This filtering happens automatically and requires no additional configuration. For more information about Gemini's thinking feature, see the [official documentation](https://ai.google.dev/gemini-api/docs/thinking).
 
+!!! note "Backwards Compatibility"
+
+    The provider-specific modes (`Mode.GENAI_TOOLS`, `Mode.GENAI_JSON`, `Mode.GENAI_STRUCTURED_OUTPUTS`) are still supported for backwards compatibility and automatically map to the generic modes (`Mode.TOOLS`, `Mode.JSON`).
+
 ## Installation
 
 ```bash
@@ -65,6 +69,35 @@ response = client.chat.completions.create(
 print(response)  # User(name='Jason', age=25)
 ```
 
+## Using the v2 GenAI client
+
+If you prefer to work directly with the native `google.genai.Client`, the v2 helper keeps the Google request format intact while still giving you Instructor's structured outputs.
+
+```python
+from google.genai import Client
+from instructor import Mode
+from instructor.v2 import from_genai
+from pydantic import BaseModel
+
+
+class User(BaseModel):
+    name: str
+    age: int
+
+
+raw_client = Client(api_key="YOUR_KEY")
+client = from_genai(raw_client, mode=Mode.TOOLS)
+
+result = client.chat.completions.create(
+    messages=[{"role": "user", "content": "Extract: Jason is 25 years old"}],
+    response_model=User,
+)
+
+print(result)
+```
+
+Behind the scenes the v2 client registers the correct mode handler, converts OpenAI-style messages to the GenAI `contents` format, and parses the response while filtering Gemini thought parts.
+
 ## Message Formatting
 
 Genai supports multiple message formats, and Instructor seamlessly works with all of them. This flexibility allows you to use whichever format is most convenient for your application:
@@ -514,7 +547,7 @@ print(response)
 
     **As of July 11, 2025, Google GenAI does not support streaming with tool/function calling or structured outputs for regular models.** 
 
-    - `Mode.GENAI_TOOLS` and `Mode.GENAI_STRUCTURED_OUTPUTS` do not support streaming with regular models
+    - `Mode.TOOLS` and `Mode.JSON` do not support streaming with regular models
     - To use streaming, you must use `Partial[YourModel]` explicitly or switch to other modes like `Mode.JSON`
     - Alternatively, set `stream=False` to disable streaming
 
@@ -531,7 +564,7 @@ import instructor
 
 client = instructor.from_provider(
     "google/gemini-2.5-flash",
-    mode=instructor.Mode.GENAI_STRUCTURED_OUTPUTS,
+    mode=instructor.Mode.JSON,
 )
 
 

docs/integrations/google.md

@@ -289,8 +289,12 @@ These limitations are specific to Google Gemini and do not affect other provider
 
 We provide several modes to make it easy to work with the different response models that Gemini supports:
 
-1. `instructor.Mode.GENAI_TOOLS` : This uses Gemini's tool calling API to return structured outputs (default)
-2. `instructor.Mode.GENAI_STRUCTURED_OUTPUTS` : This uses Gemini's JSON schema mode for structured outputs
+1. `instructor.Mode.TOOLS` : This uses Gemini's tool calling API to return structured outputs (default)
+2. `instructor.Mode.JSON` : This uses Gemini's JSON schema mode for structured outputs
+
+!!! note "Backwards Compatibility"
+
+    The provider-specific modes (`Mode.GENAI_TOOLS`, `Mode.GENAI_JSON`, `Mode.GENAI_STRUCTURED_OUTPUTS`) are still supported and automatically map to the generic modes.
 
 !!! info "Mode Selection"
     When using `from_provider`, the appropriate mode is automatically selected based on the provider and model capabilities.