claude-task-master/tasks/task_061.txt

# Task ID: 61
# Title: Implement Flexible AI Model Management
# Status: pending
# Dependencies: None
# Priority: high
# Description: Currently, Task Master only supports Claude for main operations and Perplexity for research. Users are limited in flexibility when managing AI models. Adding comprehensive support for multiple popular AI models (OpenAI, Ollama, Gemini, OpenRouter, Grok) and providing intuitive CLI commands for model management will significantly enhance usability, transparency, and adaptability to user preferences and project-specific needs. This task will now leverage Vercel's AI SDK to streamline integration and management of these models.
# Details:
### Proposed Solution
Implement an intuitive CLI command for AI model management, leveraging Vercel's AI SDK for seamless integration:

- `task-master models`: Lists currently configured models for main operations and research.
- `task-master models --set-main="<model_name>" --set-research="<model_name>"`: Sets the desired models for main operations and research tasks respectively.

Supported AI Models:
- **Main Operations:** Claude (current default), OpenAI, Ollama, Gemini, OpenRouter
- **Research Operations:** Perplexity (current default), OpenAI, Ollama, Grok

If a user specifies an invalid model, the CLI lists available models clearly.

### Example CLI Usage

List current models:
```shell
task-master models
```
Output example:
```
Current AI Model Configuration:
- Main Operations: Claude
- Research Operations: Perplexity
```

Set new models:
```shell
task-master models --set-main="gemini" --set-research="grok"
```

Attempt invalid model:
```shell
task-master models --set-main="invalidModel"
```
Output example:
```
Error: "invalidModel" is not a valid model.

Available models for Main Operations:
- claude
- openai
- ollama
- gemini
- openrouter
```

### High-Level Workflow
1. Update CLI parsing logic to handle new `models` command and associated flags.
2. Consolidate all AI calls into `ai-services.js` for centralized management.
3. Utilize Vercel's AI SDK to implement robust wrapper functions for each AI API:
   - Claude (existing)
   - Perplexity (existing)
   - OpenAI
   - Ollama
   - Gemini
   - OpenRouter
   - Grok
4. Update environment variables and provide clear documentation in `.env_example`:
```env
# MAIN_MODEL options: claude, openai, ollama, gemini, openrouter
MAIN_MODEL=claude

# RESEARCH_MODEL options: perplexity, openai, ollama, grok
RESEARCH_MODEL=perplexity
```
5. Ensure dynamic model switching via environment variables or configuration management.
6. Provide clear CLI feedback and validation of model names.

### Vercel AI SDK Integration
- Use Vercel's AI SDK to abstract API calls for supported models, ensuring consistent error handling and response formatting.
- Implement a configuration layer to map model names to their respective Vercel SDK integrations.
- Example pattern for integration:
```javascript
import { createClient } from '@vercel/ai';

const clients = {
  claude: createClient({ provider: 'anthropic', apiKey: process.env.ANTHROPIC_API_KEY }),
  openai: createClient({ provider: 'openai', apiKey: process.env.OPENAI_API_KEY }),
  ollama: createClient({ provider: 'ollama', apiKey: process.env.OLLAMA_API_KEY }),
  gemini: createClient({ provider: 'gemini', apiKey: process.env.GEMINI_API_KEY }),
  openrouter: createClient({ provider: 'openrouter', apiKey: process.env.OPENROUTER_API_KEY }),
  perplexity: createClient({ provider: 'perplexity', apiKey: process.env.PERPLEXITY_API_KEY }),
  grok: createClient({ provider: 'grok', apiKey: process.env.GROK_API_KEY })
};

export function getClient(model) {
  if (!clients[model]) {
    throw new Error(`Invalid model: ${model}`);
  }
  return clients[model];
}
```
- Leverage `generateText` and `streamText` functions from the SDK for text generation and streaming capabilities.
- Ensure compatibility with serverless and edge deployments using Vercel's infrastructure.

### Key Elements
- Enhanced model visibility and intuitive management commands.
- Centralized and robust handling of AI API integrations via Vercel AI SDK.
- Clear CLI responses with detailed validation feedback.
- Flexible, easy-to-understand environment configuration.

### Implementation Considerations
- Centralize all AI interactions through a single, maintainable module (`ai-services.js`).
- Ensure comprehensive error handling for invalid model selections.
- Clearly document environment variable options and their purposes.
- Validate model names rigorously to prevent runtime errors.

### Out of Scope (Future Considerations)
- Automatic benchmarking or model performance comparison.
- Dynamic runtime switching of models based on task type or complexity.

# Test Strategy:
### Test Strategy
1. **Unit Tests**:
   - Test CLI commands for listing, setting, and validating models.
   - Mock Vercel AI SDK calls to ensure proper integration and error handling.

2. **Integration Tests**:
   - Validate end-to-end functionality of model management commands.
   - Test dynamic switching of models via environment variables.

3. **Error Handling Tests**:
   - Simulate invalid model names and verify error messages.
   - Test API failures for each model provider and ensure graceful degradation.

4. **Documentation Validation**:
   - Verify that `.env_example` and CLI usage examples are accurate and comprehensive.

5. **Performance Tests**:
   - Measure response times for API calls through Vercel AI SDK.
   - Ensure no significant latency is introduced by model switching.

6. **SDK-Specific Tests**:
   - Validate the behavior of `generateText` and `streamText` functions for supported models.
   - Test compatibility with serverless and edge deployments.

# Subtasks:
## 1. Create Configuration Management Module [pending]
### Dependencies: None
### Description: Develop a centralized configuration module to manage AI model settings and preferences, leveraging the Strategy pattern for model selection.
### Details:
1. Create a new `config-manager.js` module to handle model configuration
2. Implement functions to read/write model preferences to a local config file
3. Define model validation logic with clear error messages
4. Create mapping of valid models for main and research operations
5. Implement getters and setters for model configuration
6. Add utility functions to validate model names against available options
7. Include default fallback models
8. Testing approach: Write unit tests to verify config reading/writing and model validation logic

<info added on 2025-04-14T21:54:28.887Z>
Here's the additional information to add:

```
The configuration management module should:

1. Use a `.taskmasterconfig` JSON file in the project root directory to store model settings
2. Structure the config file with two main keys: `main` and `research` for respective model selections
3. Implement functions to locate the project root directory (using package.json as reference)
4. Define constants for valid models:
   ```javascript
   const VALID_MAIN_MODELS = ['gpt-4', 'gpt-3.5-turbo', 'gpt-4-turbo'];
   const VALID_RESEARCH_MODELS = ['gpt-4', 'gpt-4-turbo', 'claude-2'];
   const DEFAULT_MAIN_MODEL = 'gpt-3.5-turbo';
   const DEFAULT_RESEARCH_MODEL = 'gpt-4';
   ```
5. Implement model getters with priority order:
   - First check `.taskmasterconfig` file
   - Fall back to environment variables if config file missing/invalid
   - Use defaults as last resort
6. Implement model setters that validate input against valid model lists before updating config
7. Keep API key management in `ai-services.js` using environment variables (don't store keys in config file)
8. Add helper functions for config file operations:
   ```javascript
   function getConfigPath() { /* locate .taskmasterconfig */ }
   function readConfig() { /* read and parse config file */ }
   function writeConfig(config) { /* stringify and write config */ }
   ```
9. Include error handling for file operations and invalid configurations
```
</info added on 2025-04-14T21:54:28.887Z>

## 2. Implement CLI Command Parser for Model Management [pending]
### Dependencies: 61.1
### Description: Extend the CLI command parser to handle the new 'models' command and associated flags for model management.
### Details:
1. Update the CLI command parser to recognize the 'models' command
2. Add support for '--set-main' and '--set-research' flags
3. Implement validation for command arguments
4. Create help text and usage examples for the models command
5. Add error handling for invalid command usage
6. Connect CLI parser to the configuration manager
7. Implement command output formatting for model listings
8. Testing approach: Create integration tests that verify CLI commands correctly interact with the configuration manager

## 3. Integrate Vercel AI SDK and Create Client Factory [pending]
### Dependencies: 61.1
### Description: Set up Vercel AI SDK integration and implement a client factory pattern to create and manage AI model clients.
### Details:
1. Install Vercel AI SDK: `npm install @vercel/ai`
2. Create an `ai-client-factory.js` module that implements the Factory pattern
3. Define client creation functions for each supported model (Claude, OpenAI, Ollama, Gemini, OpenRouter, Perplexity, Grok)
4. Implement error handling for missing API keys or configuration issues
5. Add caching mechanism to reuse existing clients
6. Create a unified interface for all clients regardless of the underlying model
7. Implement client validation to ensure proper initialization
8. Testing approach: Mock API responses to test client creation and error handling

## 4. Develop Centralized AI Services Module [pending]
### Dependencies: 61.3
### Description: Create a centralized AI services module that abstracts all AI interactions through a unified interface, using the Decorator pattern for adding functionality like logging and retries.
### Details:
1. Create `ai-services.js` module to consolidate all AI model interactions
2. Implement wrapper functions for text generation and streaming
3. Add retry mechanisms for handling API rate limits and transient errors
4. Implement logging for all AI interactions for observability
5. Create model-specific adapters to normalize responses across different providers
6. Add caching layer for frequently used responses to optimize performance
7. Implement graceful fallback mechanisms when primary models fail
8. Testing approach: Create unit tests with mocked responses to verify service behavior

## 5. Implement Environment Variable Management [pending]
### Dependencies: 61.1, 61.3
### Description: Update environment variable handling to support multiple AI models and create documentation for configuration options.
### Details:
1. Update `.env.example` with all required API keys for supported models
2. Implement environment variable validation on startup
3. Create clear error messages for missing or invalid environment variables
4. Add support for model-specific configuration options
5. Document all environment variables and their purposes
6. Implement a check to ensure required API keys are present for selected models
7. Add support for optional configuration parameters for each model
8. Testing approach: Create tests that verify environment variable validation logic

## 6. Implement Model Listing Command [pending]
### Dependencies: 61.1, 61.2, 61.4
### Description: Implement the 'task-master models' command to display currently configured models and available options.
### Details:
1. Create handler for the models command without flags
2. Implement formatted output showing current model configuration
3. Add color-coding for better readability using a library like chalk
4. Include version information for each configured model
5. Show API status indicators (connected/disconnected)
6. Display usage examples for changing models
7. Add support for verbose output with additional details
8. Testing approach: Create integration tests that verify correct output formatting and content

## 7. Implement Model Setting Commands [pending]
### Dependencies: 61.1, 61.2, 61.4, 61.6
### Description: Implement the commands to set main and research models with proper validation and feedback.
### Details:
1. Create handlers for '--set-main' and '--set-research' flags
2. Implement validation logic for model names
3. Add clear error messages for invalid model selections
4. Implement confirmation messages for successful model changes
5. Add support for setting both models in a single command
6. Implement dry-run option to validate without making changes
7. Add verbose output option for debugging
8. Testing approach: Create integration tests that verify model setting functionality with various inputs

## 8. Update Main Task Processing Logic [pending]
### Dependencies: 61.4, 61.5
### Description: Refactor the main task processing logic to use the new AI services module and support dynamic model selection.
### Details:
1. Update task processing functions to use the centralized AI services
2. Implement dynamic model selection based on configuration
3. Add error handling for model-specific failures
4. Implement graceful degradation when preferred models are unavailable
5. Update prompts to be model-agnostic where possible
6. Add telemetry for model performance monitoring
7. Implement response validation to ensure quality across different models
8. Testing approach: Create integration tests that verify task processing with different model configurations

## 9. Update Research Processing Logic [pending]
### Dependencies: 61.4, 61.5, 61.8
### Description: Refactor the research processing logic to use the new AI services module and support dynamic model selection for research operations.
### Details:
1. Update research functions to use the centralized AI services
2. Implement dynamic model selection for research operations
3. Add specialized error handling for research-specific issues
4. Optimize prompts for research-focused models
5. Implement result caching for research operations
6. Add support for model-specific research parameters
7. Create fallback mechanisms for research operations
8. Testing approach: Create integration tests that verify research functionality with different model configurations

## 10. Create Comprehensive Documentation and Examples [pending]
### Dependencies: 61.6, 61.7, 61.8, 61.9
### Description: Develop comprehensive documentation for the new model management features, including examples, troubleshooting guides, and best practices.
### Details:
1. Update README.md with new model management commands
2. Create usage examples for all supported models
3. Document environment variable requirements for each model
4. Create troubleshooting guide for common issues
5. Add performance considerations and best practices
6. Document API key acquisition process for each supported service
7. Create comparison chart of model capabilities and limitations
8. Testing approach: Conduct user testing with the documentation to ensure clarity and completeness