Refactor output modes: rename *Output to *Mode for consistency AND handle

- Rename ToolOutput → ToolMode, NativeOutput → NativeMode, PromptedOutput → PromptMode

Author: afarntrog

.planning/implementation.md

@@ -59,9 +59,9 @@ The current structured output flow:
    ```
 
 4. **Various Output Modes**:
-   - `ToolOutput`: Function calling for structured output
-   - `NativeOutput`: Native model structured output capabilities
-   - `PromptedOutput`: Prompting-based approach
+   - `ToolMode`: Function calling for structured output
+   - `NativeMode`: Native model structured output capabilities
+   - `PromptMode`: Prompting-based approach
    - `TextOutput`: Post-processing of text output
    - `StructuredDict`: JSON schema validation
 
@@ -114,14 +114,14 @@ class OutputSchema:
         description: Optional[str] = None
     ):
         self.types = types if isinstance(types, list) else [types]
-        self.mode = mode or ToolOutput()  # Default to tool-based approach
+        self.mode = mode or ToolMode()  # Default to tool-based approach
         self.name = name
         self.description = description
 ```
 
 #### Output Mode Implementations (`modes.py`)
 ```python
-class ToolOutput(OutputMode):
+class ToolMode(OutputMode):
     """Use function calling for structured output (DEFAULT)
 
     This is the most reliable approach across all model providers and ensures
@@ -135,11 +135,11 @@ class ToolOutput(OutputMode):
         """Tool-based output is supported by all models that support function calling"""
         return True  # All our models support function calling
 
-class NativeOutput(OutputMode):
+class NativeMode(OutputMode):
     """Use model's native structured output capabilities
 
     Only use when explicitly requested and supported by the model.
-    Falls back to ToolOutput if not supported.
+    Falls back to ToolMode if not supported.
     """
 
     def get_tool_specs(self, output_types: list[Type[BaseModel]]) -> list[ToolSpec]:
@@ -150,7 +150,7 @@ class NativeOutput(OutputMode):
         """Check if model supports native structured output"""
         return model.supports_native_structured_output()
 
-class PromptedOutput(OutputMode):
+class PromptMode(OutputMode):
     """Use prompting to guide output format
 
     Only use when explicitly requested. Less reliable than tool-based approach
@@ -235,19 +235,19 @@ class Agent:
         if not output_type:
             return None
 
-        # Default to ToolOutput if no mode specified
-        resolved_mode = output_mode or ToolOutput()
+        # Default to ToolMode if no mode specified
+        resolved_mode = output_mode or ToolMode()
 
         # Validate mode is supported by current model
         if not resolved_mode.is_supported_by_model(self.model):
-            if isinstance(resolved_mode, NativeOutput):
+            if isinstance(resolved_mode, NativeMode):
                 # Fallback to tool-based approach for native output
                 logger.warning(
                     f"Model {self.model.__class__.__name__} does not support native structured output. "
                     "Falling back to tool-based approach."
                 )
-                resolved_mode = ToolOutput()
-            elif isinstance(resolved_mode, PromptedOutput):
+                resolved_mode = ToolMode()
+            elif isinstance(resolved_mode, PromptMode):
                 # This shouldn't happen as all models support prompting
                 raise ValueError(f"Model {self.model.__class__.__name__} does not support prompting")
 
@@ -326,23 +326,23 @@ class Model(abc.ABC):
 All providers default to tool-based approach unless explicitly overridden:
 
 - **Bedrock**:
-  - Default: ToolOutput (function calling)
-  - Native: Not supported, falls back to ToolOutput
+  - Default: ToolMode (function calling)
+  - Native: Not supported, falls back to ToolMode
   - Prompted: Available when explicitly requested
 
 - **OpenAI**:
-  - Default: ToolOutput (function calling)
+  - Default: ToolMode (function calling)
   - Native: Available when explicitly requested (structured_outputs=True)
   - Prompted: Available when explicitly requested
 
 - **Anthropic**:
-  - Default: ToolOutput (function calling)
-  - Native: Not supported, falls back to ToolOutput
+  - Default: ToolMode (function calling)
+  - Native: Not supported, falls back to ToolMode
   - Prompted: Available when explicitly requested
 
 - **Others (Ollama, LiteLLM, etc.)**:
-  - Default: ToolOutput (function calling)
-  - Native: Model-dependent, falls back to ToolOutput if not supported
+  - Default: ToolMode (function calling)
+  - Native: Model-dependent, falls back to ToolMode if not supported
   - Prompted: Available when explicitly requested
 
 ### 6. Backward Compatibility
@@ -369,23 +369,23 @@ def structured_output(self, output_model: Type[T], prompt: AgentInput = None) ->
 
 #### Type-Safe Patterns
 ```python
-# Agent-level output type (uses ToolOutput by default)
+# Agent-level output type (uses ToolMode by default)
 agent = Agent(model, output_type=UserProfile)  # Uses function calling
 result = agent("Extract user info from: John Doe, age 30")  # Returns AgentResult
 user = result.get_structured_output(UserProfile)  # Extract UserProfile
 
-# Runtime output type specification (uses ToolOutput by default)
+# Runtime output type specification (uses ToolMode by default)
 result = agent("Summarize this text", output_type=Summary)  # Uses function calling
 summary = result.get_structured_output(Summary)  # Extract Summary
 
 # Explicit output mode specification
-precise_agent = Agent(model, output_type=Data, output_mode=NativeOutput())  # Uses native if supported
-fast_agent = Agent(model, output_type=Data, output_mode=PromptedOutput())   # Uses prompting
+precise_agent = Agent(model, output_type=Data, output_mode=NativeMode())  # Uses native if supported
+fast_agent = Agent(model, output_type=Data, output_mode=PromptMode())   # Uses prompting
 
 # Runtime mode override
-result = agent("Extract data", output_type=Data, output_mode=NativeOutput())  # Uses native if supported
+result = agent("Extract data", output_type=Data, output_mode=NativeMode())  # Uses native if supported
 
-# Multiple output types (still uses ToolOutput by default)
+# Multiple output types (still uses ToolMode by default)
 agent = Agent(model, output_type=[Person, Company])  # Creates multiple function tools
 result = agent("What is Apple Inc?")  # Returns AgentResult
 entity = result.structured_output  # Returns Person | Company instance
@@ -397,8 +397,8 @@ text = str(result)  # Get text response
 
 # Fallback behavior for unsupported modes
 try:
-    # If model doesn't support native, automatically falls back to ToolOutput
-    result = agent("Extract", output_type=Data, output_mode=NativeOutput())
+    # If model doesn't support native, automatically falls back to ToolMode
+    result = agent("Extract", output_type=Data, output_mode=NativeMode())
 except ValueError:
     # Only raises if something is fundamentally wrong
     pass
@@ -444,7 +444,7 @@ except ValueError:
    - Update all model providers for structured output support
 
 2. **Provider-Specific Implementation**
-   - All providers: Default to ToolOutput (function calling)
+   - All providers: Default to ToolMode (function calling)
    - OpenAI: Add native structured output support when explicitly requested
    - Bedrock: Enhanced function calling with better schema handling
    - Anthropic: Enhanced function calling support
@@ -507,7 +507,7 @@ except ValueError:
 # Old approach
 user_data = agent.structured_output(UserModel, "Extract user info")
 
-# New approach (uses ToolOutput by default - most reliable)
+# New approach (uses ToolMode by default - most reliable)
 result = agent("Extract user info", output_type=UserModel)
 user_data = result.get_structured_output(UserModel)
 
@@ -521,19 +521,19 @@ user_data = result.structured_output
 text_result = agent("Generate summary")
 structured_result = agent.structured_output(Summary, "Generate summary")
 
-# New: Unified interface (uses ToolOutput by default)
+# New: Unified interface (uses ToolMode by default)
 text_result = agent("Generate summary")
 structured_result = agent("Generate summary", output_type=Summary)
 summary = structured_result.get_structured_output(Summary)
 
-# Or set default output type (uses ToolOutput by default)
+# Or set default output type (uses ToolMode by default)
 summary_agent = Agent(model, output_type=Summary)
 result = summary_agent("Generate summary")
 summary = result.get_structured_output(Summary)
 
 # Explicit mode selection only when needed
-result = agent("Extract", output_type=Data, output_mode=NativeOutput())
-# Falls back to ToolOutput if model doesn't support native
+result = agent("Extract", output_type=Data, output_mode=NativeMode())
+# Falls back to ToolMode if model doesn't support native
 ```
 
 ## Success Metrics

.planning/tasks.md

@@ -7,7 +7,7 @@ This document breaks down the structured output implementation into discrete, ac
 ## Phase 1: Core Infrastructure ✅
 
 ### Task 1.1: Create Output Mode Base Classes ✅
-**Prompt:** Create the base output mode system in `src/strands/output/base.py`. Implement the abstract `OutputMode` class with methods for `get_tool_specs()`, `extract_result()`, and `is_supported_by_model()`. Also implement the `OutputSchema` container class that holds output types (Pydantic models only), mode, name, and description, with a default to `ToolOutput()`.
+**Prompt:** Create the base output mode system in `src/strands/output/base.py`. Implement the abstract `OutputMode` class with methods for `get_tool_specs()`, `extract_result()`, and `is_supported_by_model()`. Also implement the `OutputSchema` container class that holds output types (Pydantic models only), mode, name, and description, with a default to `ToolMode()`.
 
 **Files to create/modify:**
 - `src/strands/output/__init__.py` ✅
@@ -17,18 +17,18 @@ This document breaks down the structured output implementation into discrete, ac
 - Abstract `OutputMode` class with required methods ✅
 - `OutputSchema` class with proper initialization (Pydantic models only) ✅
 - Type hints and docstrings for all public APIs ✅
-- Default to `ToolOutput()` when no mode specified ✅
+- Default to `ToolMode()` when no mode specified ✅
 
 ### Task 1.2: Implement Output Mode Implementations ✅
-**Prompt:** Create the concrete output mode implementations in `src/strands/output/modes.py`. Implement `ToolOutput` (default), `NativeOutput`, and `PromptedOutput` classes. Each should implement the abstract methods from `OutputMode` and include model support detection. `ToolOutput` should always return `True` for `is_supported_by_model()`.
+**Prompt:** Create the concrete output mode implementations in `src/strands/output/modes.py`. Implement `ToolMode` (default), `NativeMode`, and `PromptMode` classes. Each should implement the abstract methods from `OutputMode` and include model support detection. `ToolMode` should always return `True` for `is_supported_by_model()`.
 
 **Files to create/modify:**
 - `src/strands/output/modes.py` ✅
 
 **Acceptance criteria:**
-- `ToolOutput` class converts Pydantic models to tool specs ✅
-- `NativeOutput` class returns empty tool specs and checks model support ✅
-- `PromptedOutput` class with customizable template ✅
+- `ToolMode` class converts Pydantic models to tool specs ✅
+- `NativeMode` class returns empty tool specs and checks model support ✅
+- `PromptMode` class with customizable template ✅
 - All classes implement `is_supported_by_model()` correctly ✅
 
 ### Task 1.3: Create Output Registry System ✅
@@ -89,15 +89,15 @@ This document breaks down the structured output implementation into discrete, ac
 ## Phase 3: Agent Interface Enhancement ✅
 
 ### Task 3.1: Enhance Agent Constructor ✅
-**Prompt:** Modify the `Agent` class constructor in `src/strands/agent/agent.py` to accept `output_type` (Pydantic models only) and `output_mode` parameters. Implement the `_resolve_output_schema()` method that defaults to `ToolOutput()` and includes model support validation with automatic fallback.
+**Prompt:** Modify the `Agent` class constructor in `src/strands/agent/agent.py` to accept `output_type` (Pydantic models only) and `output_mode` parameters. Implement the `_resolve_output_schema()` method that defaults to `ToolMode()` and includes model support validation with automatic fallback.
 
 **Files to create/modify:**
 - `src/strands/agent/agent.py` ✅
 
 **Acceptance criteria:**
 - Constructor accepts `output_type` (Pydantic models only) and `output_mode` parameters ✅
 - `_resolve_output_schema()` method implemented ✅
-- Default to `ToolOutput()` when no mode specified ✅
+- Default to `ToolMode()` when no mode specified ✅
 - Model support validation with fallback logic ✅
 - Proper logging for fallback scenarios ✅
 
@@ -115,7 +115,7 @@ This document breaks down the structured output implementation into discrete, ac
 - Backward compatibility for existing calls ✅
 
 ### Task 3.3: Implement Output Schema Resolution Logic ✅
-**Prompt:** Implement the complete output schema resolution logic in the `Agent` class. This includes handling runtime overrides, default schema application, model compatibility checking, and automatic fallback from unsupported modes to `ToolOutput()`.
+**Prompt:** Implement the complete output schema resolution logic in the `Agent` class. This includes handling runtime overrides, default schema application, model compatibility checking, and automatic fallback from unsupported modes to `ToolMode()`.
 
 **Files to create/modify:**
 - `src/strands/agent/agent.py` ✅
@@ -124,7 +124,7 @@ This document breaks down the structured output implementation into discrete, ac
 - Runtime output type override support ✅
 - Agent-level default schema application ✅
 - Model compatibility validation ✅
-- Automatic fallback to `ToolOutput()` ✅
+- Automatic fallback to `ToolMode()` ✅
 - Comprehensive error handling and logging ✅
 
 ## Phase 4: Event Loop Integration ✅

docs/migration_guide.md

@@ -69,13 +69,13 @@ user = result.get_structured_output(UserProfile)
 
 **New Feature:**
 ```python
-from strands import NativeOutput, ToolOutput
+from strands import NativeMode, ToolMode
 
 # Use native structured output when available
-agent = Agent(output_type=UserProfile, output_mode=NativeOutput())
+agent = Agent(output_type=UserProfile, output_mode=NativeMode())
 
 # Or explicitly use tool-based approach
-agent = Agent(output_type=UserProfile, output_mode=ToolOutput())
+agent = Agent(output_type=UserProfile, output_mode=ToolMode())
 ```
 
 ## Common Migration Patterns
@@ -170,14 +170,14 @@ with warnings.catch_warnings():
 ### 1. Output Modes
 
 ```python
-from strands import NativeOutput, PromptedOutput
+from strands import NativeMode, PromptMode
 
 # Use model's native structured output
-agent = Agent(output_type=UserProfile, output_mode=NativeOutput())
+agent = Agent(output_type=UserProfile, output_mode=NativeMode())
 
 # Use custom prompt template
 template = "Extract information: {prompt}\nFormat as JSON:"
-agent = Agent(output_type=UserProfile, output_mode=PromptedOutput(template=template))
+agent = Agent(output_type=UserProfile, output_mode=PromptMode(template=template))
 ```
 
 ### 2. Model Capability Detection
@@ -195,11 +195,11 @@ bedrock_agent = Agent(model=BedrockModel(model_id="claude-3"), output_type=UserP
 ### 3. Multiple Output Types
 
 ```python
-from strands import OutputSchema, ToolOutput
+from strands import OutputSchema, ToolMode
 
 schema = OutputSchema(
     types=[UserProfile, TaskInfo],
-    mode=ToolOutput(),
+    mode=ToolMode(),
     description="Can output user profile or task information"
 )