# Migration Guide: Model Configuration System

## Overview

Version 1.0.5 introduces a new centralized configuration system for managing model settings across your Multi-Swarm agencies. This guide will help you migrate your existing code to use the new system.

## What's New

- Centralized YAML-based configuration
- Enhanced model selection based on tasks
- Support for experimental models
- Improved version compatibility checks
- Better configuration management utilities

## Backwards Compatibility

The new configuration system maintains full backwards compatibility with existing code. Your current agent configurations will continue to work without modification. However, we recommend migrating to the new system to take advantage of its benefits.

### Before (1.0.4 and earlier)
```python
agent = Agent(
    name="Developer",
    description="Code generation specialist",
    llm_provider="claude",
    provider_config={
        "model": "claude-3-5-sonnet-latest",
        "api_version": "2024-03",
        "max_tokens": 4096
    }
)
```

### After (1.0.5+)
```python
from multi_swarm.utils.config_manager import ConfigManager

# The agent will automatically use the best model for code tasks
agent = Agent(
    name="Developer",
    description="Code generation specialist"
)

# Or explicitly manage configurations
config_manager = ConfigManager()
config_manager.update_task_preference(
    provider="claude",
    task="code_generation",
    model_name="claude-3-5-sonnet-latest"
)
```

## Migration Steps

1. **Update Dependencies**
   ```bash
   pip install multi-swarm>=1.0.5
   ```

2. **Create Custom Configuration (Optional)**
   ```python
   from multi_swarm.utils.config_manager import ConfigManager

   config_manager = ConfigManager()
   
   # Update model configuration
   config_manager.update_model(
       provider="gemini",
       model_name="custom-model",
       model_config={
           "name": "custom-model",
           "provider": "gemini",
           "api_version": "2024-02",
           "max_tokens": 8192,
           "temperature": 0.7
       }
   )
   
   # Set default model
   config_manager.set_default_model("gemini", "custom-model")
   
   # Update task preferences
   config_manager.update_task_preference(
       provider="gemini",
       task="custom_task",
       model_name="custom-model"
   )
   ```

3. **Update Agent Creation**
   ```python
   # Let the framework choose the best model
   agent = Agent(
       name="CustomAgent",
       description="Handles custom tasks",
       # Provider and model will be selected based on description
   )
   
   # Or specify provider while letting the framework choose the model
   agent = Agent(
       name="CustomAgent",
       description="Handles custom tasks",
       llm_provider="gemini"  # Will use appropriate Gemini model
   )
   ```

## New Features

### Task-Based Model Selection
The framework now automatically selects the most appropriate model based on the agent's role and task:

```python
# Will use claude-3-5-sonnet-latest for code tasks
code_agent = Agent(
    name="CodeAgent",
    description="Generates and reviews code"
)

# Will use claude-3-5-opus-latest for research
research_agent = Agent(
    name="ResearchAgent",
    description="Conducts research and analysis"
)

# Will use gemini-2.0-flash-exp for real-time tasks
ops_agent = Agent(
    name="OperationsAgent",
    description="Handles system monitoring and metrics"
)
```

### Custom Configuration Files
You can create custom configuration files for different environments:

```python
# Load custom configuration
config_manager = ConfigManager("path/to/custom_config.yaml")

# Use in agency
agency = Agency(
    name="CustomAgency",
    agents=[agent1, agent2],
    config_manager=config_manager
)
```

### Version Compatibility
The framework now includes version compatibility checks:

```python
# Will raise ValueError if API version is incompatible
agent = Agent(
    name="ExperimentalAgent",
    llm_provider="gemini",
    provider_config={
        "model": "gemini-2.0-pro-exp-02-05",
        "api_version": "2024-02"  # Must be 2024-02 or later
    }
)
```

## Best Practices

1. **Let the Framework Choose**
   - Allow the framework to select models based on task descriptions
   - Only override when specific models are required

2. **Use Task Categories**
   - Organize tasks into categories for better model selection
   - Add new categories in the configuration file

3. **Version Management**
   - Keep track of API versions in your configuration
   - Test with experimental models before production use

4. **Configuration Management**
   - Use separate configuration files for different environments
   - Keep a backup of your custom configurations

## Troubleshooting

### Common Issues

1. **Model Not Found**
   ```python
   # Check if model exists
   model_config = config_manager.get_model_config(
       provider="gemini",
       model_name="custom-model"
   )
   if not model_config:
       # Handle missing model
   ```

2. **Version Incompatibility**
   ```python
   try:
       agent = Agent(...)
   except ValueError as e:
       if "incompatible API version" in str(e):
           # Handle version incompatibility
   ```

3. **Task Preference Issues**
   ```python
   # Verify task preference
   preferred_model = config_manager.get_task_model(
       provider="claude",
       task="custom_task"
   )
   if not preferred_model:
       # Handle missing task preference
   ```

## Support

If you encounter any issues during migration:
1. Check the [GitHub Issues](https://github.com/bartvanspitaels99/multi-swarm/issues)
2. Join our [GitHub Discussions](https://github.com/bartvanspitaels99/multi-swarm/discussions)
3. Read the [API Documentation](api/core.md) 