Fix config_loader documentation inconsistencies

- Correct documentation to match actual implementation
- Focus on dictionary-based configuration vs file-based loading
- Remove hallucinated features and examples
- Add missing Swarm-as-Tool and Graph-as-Tool examples
- Clarify experimental nature of config loaders
- Ensure all examples match public interface
- Update API usage examples to be accurate

Author: vawsgit

src/strands/experimental/config_loader/config_schema/README.md

@@ -1,15 +1,14 @@
 # Strands Agents Configuration Schema Validation
 
-This directory contains a comprehensive schema validation system for Strands Agents configurations, providing JSON Schema validation, semantic validation, and IDE integration support.
+This directory contains JSON Schema definitions for validating Strands Agents configurations, providing schema validation and IDE integration support.
 
 ## 🎯 Features
 
 - **JSON Schema Validation**: Complete validation against JSON Schema Draft-07
 - **IDE Integration**: VSCode auto-completion and real-time validation
-- **Semantic Validation**: Business logic and best practice validation
-- **Compatibility Checking**: Cross-component reference validation
-- **Detailed Error Reporting**: Clear, actionable error messages with precise locations
+- **Flexible Configuration Formats**: Support for both direct and wrapped configuration formats
 - **Multiple Configuration Types**: Support for agents, swarms, graphs, tools, and composite configurations
+- **Clear Error Reporting**: Actionable error messages with precise locations
 
 ## 📁 Directory Structure
 
@@ -21,47 +20,17 @@ config_schema/
 │   ├── graph-config.schema.json      # Graph configuration schema
 │   ├── tool-config.schema.json       # Tool configuration schema
 │   └── composite-config.schema.json  # Composite configuration schema
-├── validators/                        # Python validation modules
-│   ├── schema_validator.py           # Core schema validation
-│   ├── semantic_validator.py         # Business logic validation
-│   └── compatibility_validator.py    # Cross-component validation
-├── examples/                          # Example configurations
-│   ├── valid/                        # Valid configuration examples
-│   └── invalid/                      # Invalid examples for testing
 ├── vscode/                           # VSCode integration files
 │   ├── settings.json                 # Schema associations
 │   └── README.md                     # IDE setup instructions
-└── test_schema_validation.py         # Comprehensive test script
+└── __init__.py                       # Module initialization
 ```
 
 ## 🚀 Quick Start
 
-### 1. Python Validation
+### 1. VSCode Integration
 
-```python
-from strands.experimental.config_loader.config_schema import SchemaValidator
-
-# Initialize validator
-validator = SchemaValidator()
-
-# Validate an agent configuration
-result = validator.validate_agent_config("path/to/agent.yml")
-
-if result.is_valid:
-    print("✅ Configuration is valid!")
-else:
-    print("❌ Validation failed:")
-    for error in result.errors:
-        print(f"  - {error}")
-
-# Validate other configuration types
-swarm_result = validator.validate_swarm_config("path/to/swarm.yml")
-graph_result = validator.validate_graph_config("path/to/graph.yml")
-```
-
-### 2. VSCode Integration
-
-1. Copy the VSCode settings:
+1. Copy the VSCode settings to your project:
    ```bash
    cp vscode/settings.json /path/to/your/project/.vscode/settings.json
    ```
@@ -72,26 +41,21 @@ graph_result = validator.validate_graph_config("path/to/graph.yml")
 
 3. Start editing YAML files with automatic validation and auto-completion!
 
-### 3. Running Tests
+### 2. Python Validation
 
-```bash
-# Run the comprehensive test suite
-python test_schema_validation.py
+For programmatic validation, use the schema validation system in the samples:
 
-# Test specific configuration files
-python -c "
-from validators import SchemaValidator
-validator = SchemaValidator()
-result = validator.validate_agent_config('examples/valid/weather-agent.yml')
-print('Valid!' if result.is_valid else 'Invalid!')
-"
+```python
+# See samples/01-tutorials/01-fundamentals/09-configuration-loader/
+# for comprehensive validation examples and notebooks
 ```
 
 ## 📋 Supported Configuration Types
 
 ### Agent Configurations
-Files matching: `*-agent.yml`, `agent.yml`
+Supports both direct and wrapped formats:
 
+**Direct format:**
 ```yaml
 name: "my_agent"
 model: "us.anthropic.claude-3-7-sonnet-20250219-v1:0"
@@ -101,62 +65,98 @@ tools:
 temperature: 0.7
 ```
 
-### Swarm Configurations  
-Files matching: `swarm*.yml`
+**Wrapped format:**
+```yaml
+agent:
+  name: "my_agent"
+  model: "us.anthropic.claude-3-7-sonnet-20250219-v1:0"
+  system_prompt: "You are a helpful assistant..."
+  tools:
+    - "weather_tool.weather"
+  temperature: 0.7
+```
 
+### Swarm Configurations  
 ```yaml
 swarm:
   max_handoffs: 15
   agents:
     - name: "research_agent"
       model: "us.anthropic.claude-3-7-sonnet-20250219-v1:0"
       system_prompt: "You are a research specialist..."
+      handoff_conditions:
+        - condition: "research_complete"
+          target_agent: "creative_agent"
     - name: "creative_agent"
       model: "us.anthropic.claude-3-7-sonnet-20250219-v1:0"
       system_prompt: "You are a creative specialist..."
 ```
 
 ### Graph Configurations
-Files matching: `graph*.yml`
-
 ```yaml
 graph:
-  graph_id: "my_workflow"
-  name: "My Workflow"
   nodes:
-    - node_id: "start"
-      type: "agent"
-      config:
-        name: "starter_agent"
+    - name: "validator"
+      agent:
+        model: "us.anthropic.claude-3-7-sonnet-20250219-v1:0"
+        system_prompt: "You validate documents..."
+    - name: "processor"
+      agent:
         model: "us.anthropic.claude-3-7-sonnet-20250219-v1:0"
-        system_prompt: "You coordinate the workflow..."
+        system_prompt: "You process documents..."
   edges:
-    - from_node: "start"
-      to_node: "end"
-  entry_points: ["start"]
+    - from: "validator"
+      to: "processor"
+      condition:
+        type: "expression"
+        expression: "state.results.get('validator', {}).get('status') == 'valid'"
+  entry_point: "validator"
 ```
 
-## 🔍 Validation Levels
+### Tool Configurations
+```yaml
+tools:
+  - name: "weather"
+    description: "Get current weather information"
+    function: "weather_tool.weather"
+    parameters:
+      type: "object"
+      properties:
+        location:
+          type: "string"
+          description: "City name"
+      required: ["location"]
+```
+
+### Composite Configurations (Agents/Swarms/Graphs as Tools)
+```yaml
+agent:
+  model: "us.anthropic.claude-3-7-sonnet-20250219-v1:0"
+  system_prompt: "You coordinate complex tasks..."
+  tools:
+    - name: "research_team"
+      description: "A collaborative research team"
+      swarm:
+        agents:
+          - name: "researcher"
+            model: "us.anthropic.claude-3-7-sonnet-20250219-v1:0"
+            system_prompt: "You gather information..."
+```
+
+## 🔍 Schema Features
+
+### Flexible Configuration Support
+- **Direct Format**: Configuration properties at root level
+- **Wrapped Format**: Configuration under `agent:`, `swarm:`, or `graph:` keys
+- **Automatic Detection**: Schemas support both formats seamlessly
 
-### 1. Schema Validation
+### Validation Capabilities
 - **Structure**: YAML/JSON structure validation
 - **Types**: Data type checking (string, number, boolean, etc.)
 - **Required Fields**: Ensures all required properties are present
 - **Constraints**: Validates ranges, patterns, and enums
 - **Additional Properties**: Prevents unknown configuration keys
-
-### 2. Semantic Validation
-- **Business Logic**: Validates configuration makes sense
-- **Best Practices**: Suggests improvements and optimizations
-- **Model Compatibility**: Checks model parameters and capabilities
-- **Tool References**: Validates tool availability and configuration
-- **Resource Limits**: Warns about performance implications
-
-### 3. Compatibility Validation
-- **Cross-References**: Validates references between components
-- **Circular Dependencies**: Detects circular references
-- **Tool Conflicts**: Identifies potential tool usage conflicts
-- **Version Compatibility**: Ensures component versions work together
+- **Complex Tools**: Validates agent-as-tool, swarm-as-tool, graph-as-tool configurations
 
 ## 🎨 IDE Integration
 
@@ -176,57 +176,6 @@ The schema system automatically detects configuration types based on file names:
 - **Tools**: `tool*.yml`, `tools.yml`
 - **Composite**: `*-as-tools.yml`, `agents-as-tools.yml`
 
-## 🧪 Testing
-
-### Test Categories
-
-1. **Schema Loading Tests**: Verify all schemas load correctly
-2. **Valid Configuration Tests**: Test known-good configurations
-3. **Invalid Configuration Tests**: Test error detection
-4. **Error Message Tests**: Verify error message quality
-5. **Semantic Validation Tests**: Test business logic validation
-6. **Compatibility Tests**: Test cross-component validation
-
-### Running Tests
-
-```bash
-# Run all tests
-python test_schema_validation.py
-
-# Test specific schema
-python -c "
-from validators import SchemaValidator
-validator = SchemaValidator()
-print('Available schemas:', validator.get_available_schemas())
-"
-```
-
-## 🔧 Extending the System
-
-### Adding New Schema Types
-
-1. Create a new JSON Schema file in `schemas/`
-2. Add validation method to `SchemaValidator`
-3. Add semantic validation to `SemanticValidator`
-4. Update VSCode settings for file pattern matching
-5. Add test examples
-
-### Custom Validation Rules
-
-```python
-from validators import SemanticValidator
-
-class CustomSemanticValidator(SemanticValidator):
-    def validate_agent_config(self, config):
-        result = super().validate_agent_config(config)
-        
-        # Add custom validation logic
-        if config.get("name", "").startswith("test_"):
-            result.add_warning("Agent name starts with 'test_' - is this intentional?")
-        
-        return result
-```
-
 ## 📚 Schema Reference
 
 ### Common Patterns
@@ -267,6 +216,14 @@ class CustomSemanticValidator(SemanticValidator):
 - **Temperatures**: Must be 0.0-2.0 for most models
 - **Tokens**: Must be positive integers within model limits
 
+## 🧪 Testing and Examples
+
+For comprehensive examples and testing:
+
+- **Tutorial Notebooks**: `samples/01-tutorials/01-fundamentals/09-configuration-loader/`
+- **Configuration Examples**: `samples/01-tutorials/01-fundamentals/09-configuration-loader/configs/`
+- **Schema Validation Demo**: `samples/01-tutorials/01-fundamentals/09-configuration-loader/09-yaml-schema-simple.ipynb`
+
 ## 🐛 Troubleshooting
 
 ### Common Issues
@@ -286,24 +243,20 @@ class CustomSemanticValidator(SemanticValidator):
    - Check YAML extension is active
    - Try "YAML: Reload Schema Cache" command
 
-### Debug Mode
+## 🔧 Schema Updates
 
-```python
-import logging
-logging.basicConfig(level=logging.DEBUG)
-
-from validators import SchemaValidator
-validator = SchemaValidator()
-result = validator.validate_agent_config("config.yml")
-```
+Recent improvements:
+- **Flexible Format Support**: Schemas now support both direct and wrapped configuration formats
+- **Enhanced Agent Schema**: Supports complex tool configurations (agent-as-tool, swarm-as-tool, graph-as-tool)
+- **Improved Swarm Schema**: More flexible handoff conditions
+- **Better Graph Schema**: Enhanced condition support with function-based conditions
 
 ## 🤝 Contributing
 
 1. **Adding Schemas**: Follow JSON Schema Draft-07 standards
-2. **Validation Logic**: Add comprehensive error messages
-3. **Testing**: Include both valid and invalid examples
-4. **Documentation**: Update README and inline docs
-5. **IDE Support**: Update VSCode settings for new patterns
+2. **Testing**: Use the validation notebooks in samples for testing changes
+3. **Documentation**: Update README and inline docs
+4. **IDE Support**: Update VSCode settings for new patterns
 
 ## 📄 License