model-router

# Model Router **Intelligent AI model routing across multiple providers for optimal cost-performance balance.** Automatically select the best model for any task based on complexity, type, and your preferences. Support for 6 major AI providers with secure API key management and interactive configuration. ## 🎯 What It Does - **Analyzes tasks** and classifies them by type (coding, research, creative, simple, etc.) - **Routes to optimal models** from your configured providers - **Optimizes costs** by using cheaper models for simple tasks - **Secures API keys** with file permissions (600) and isolated storage - **Provides recommendations** with confidence scoring and reasoning ## 🚀 Quick Start ### Step 1: Run the Setup Wizard ```bash cd skills/model-router python3 scripts/setup-wizard.py ``` The wizard will guide you through: 1. **Provider setup** - Add your API keys (Anthropic, OpenAI, Gemini, etc.) 2. **Task mappings** - Choose which model for each task type 3. **Preferences** - Set cost optimization level ### Step 2: Use the Classifier ```bash # Get model recommendation for a task python3 scripts/classify_task.py "Build a React authentication system" # Output: # Recommended Model: claude-sonnet # Confidence: 85% # Cost Level: medium # Reasoning: Matched 2 keywords: build, system ``` ### Step 3: Route Tasks with Sessions ```bash # Spawn with recommended model sessions_spawn --task "Debug this memory leak" --model claude-sonnet # Use aliases for quick access sessions_spawn --task "What's the weather?" --model haiku ``` ## 📊 Supported Providers | Provider | Models | Best For | Key Format | |----------|--------|----------|------------| | **Anthropic** | claude-opus-4-5, claude-sonnet-4-5, claude-haiku-4-5 | Coding, reasoning, creative | `sk-ant-...` | | **OpenAI** | gpt-4o, gpt-4o-mini, o1-mini, o1-preview | Tools, deep reasoning | `sk-proj-...` | | **Gemini** | gemini-2.0-flash, gemini-1.5-pro, gemini-1.5-flash | Multimodal, huge context (2M) | `AIza...` | | **Moonshot** | moonshot-v1-8k/32k/128k | Chinese language | `sk-...` | | **Z.ai** | glm-4.5-air, glm-4.7 | Cheapest, fast | Various | | **GLM** | glm-4-flash, glm-4-plus, glm-4-0520 | Chinese, coding | `ID.secret` | ## 🎛️ Task Type Mappings Default routing (customizable via wizard): | Task Type | Default Model | Why | |-----------|---------------|-----| | `simple` | glm-4.5-air | Fastest, cheapest for quick queries | | `coding` | claude-sonnet-4-5 | Excellent code understanding | | `research` | claude-sonnet-4-5 | Balanced depth and speed | | `creative` | claude-opus-4-5 | Maximum creativity | | `math` | o1-mini | Specialized reasoning | | `vision` | gemini-1.5-flash | Fast multimodal | | `chinese` | glm-4.7 | Optimized for Chinese | | `long_context` | gemini-1.5-pro | Up to 2M tokens | ## 💰 Cost Optimization ### Aggressive Mode Always uses the cheapest capable model: - Simple → glm-4.5-air (~10% cost) - Coding → claude-haiku-4-5 (~25% cost) - Research → claude-sonnet-4-5 (~50% cost) **Savings:** 50-90% compared to always using premium models ### Balanced Mode (Default) Considers cost vs quality: - Simple tasks → Cheap models - Critical tasks → Premium models - Automatic escalation if cheap model fails ### Quality Mode Always uses the best model regardless of cost ## 🔒 Security ### API Key Storage ``` ~/.model-router/ ├── config.json # Model mappings (chmod 600) └── .api-keys # API keys (chmod 600) ``` **Features:** - File permissions restricted to owner (600) - Isolated from version control - Encrypted at rest (via OS filesystem encryption) - Never logged or printed ### Best Practices 1. **Never commit** `.api-keys` to version control 2. **Use environment variables** for production deployments 3. **Rotate keys** regularly via the wizard 4. **Audit access** with `ls -la ~/.model-router/` ## 📖 Usage Examples ### Example 1: Cost-Optimized Workflow ```bash # Classify task first python3 scripts/classify_task.py "Extract prices from this CSV" # Result: simple task → use glm-4.5-air sessions_spawn --task "Extract prices" --model glm-4.5-air # Then analyze with better model if needed sessions_spawn --task "Analyze price trends" --model claude-sonnet ``` ### Example 2: Progressive Escalation ```bash # Try cheap model first (60s timeout) sessions_spawn --task "Fix this bug" --model glm-4.5-air --runTimeoutSeconds 60 # If fails, escalate to premium sessions_spawn --task "Fix complex architecture bug" --model claude-opus ``` ### Example 3: Parallel Processing ```bash # Batch simple tasks in parallel with cheap model sessions_spawn --task "Summarize doc A" --model glm-4.5-air & sessions_spawn --task "Summarize doc B" --model glm-4.5-air & sessions_spawn --task "Summarize doc C" --model glm-4.5-air & wait ``` ### Example 4: Multimodal with Gemini ```bash # Vision task with 2M token context sessions_spawn --task "Analyze these 100 images" --model gemini-1.5-pro ``` ## 🛠️ Configuration Files ### `~/.model-router/config.json` ```json { "version": "1.1.0", "providers": { "anthropic": { "configured": true, "models": ["claude-opus-4-5", "claude-sonnet-4-5", "claude-haiku-4-5"] }, "openai": { "configured": true, "models": ["gpt-4o", "gpt-4o-mini", "o1-mini", "o1-preview"] } }, "task_mappings": { "simple": "glm-4.5-air", "coding": "claude-sonnet-4-5", "research": "claude-sonnet-4-5", "creative": "claude-opus-4-5" }, "preferences": { "cost_optimization": "balanced", "default_provider": "anthropic" } } ``` ### `~/.model-router/.api-keys` ```bash # Generated by setup wizard - DO NOT edit manually ANTHROPIC_API_KEY=sk-ant-... OPENAI_API_KEY=sk-proj-... GEMINI_API_KEY=AIza... ``` ## 🔄 Version 1.1 Changes ### New Features - ✅ **Interactive setup wizard** for guided configuration - ✅ **Secure API key storage** with file permissions - ✅ **Task-to-model mapping** customization - ✅ **Multi-provider support** (6 providers) - ✅ **Cost optimization levels** (aggressive/balanced/quality) ### Improvements - ✅ Better task classification with confidence scores - ✅ Provider-specific model recommendations - ✅ Enhanced security with isolated storage - ✅ Comprehensive documentation ### Migration from 1.0 Run the setup wizard to reconfigure: ```bash python3 scripts/setup-wizard.py ``` ## 📚 Command Reference ### Setup Wizard ```bash python3 scripts/setup-wizard.py ``` Interactive configuration of providers, mappings, and preferences. ### Task Classifier ```bash python3 scripts/classify_task.py "your task description" python3 scripts/classify_task.py "your task" --format json ``` Get model recommendation with reasoning. ### List Models ```bash python3 scripts/setup-wizard.py --list ``` Show all available models and their status. ## 🤝 Integration with Other Skills | Skill | Integration | |-------|-------------| | **model-usage** | Track cost per provider to optimize routing | | **sessions_spawn** | Primary tool for model delegation | | **session_status** | Check current model and usage | ## ⚡ Performance Tips 1. **Start simple** - Try cheap models first 2. **Batch tasks** - Combine multiple simple tasks 3. **Use cleanup** - Delete sessions after one-off tasks 4. **Set timeouts** - Prevent runaway sub-agents 5. **Monitor usage** - Track costs per provider ## 🐛 Troubleshooting ### "No suitable model found" - Run setup wizard to configure providers - Check API keys are valid - Verify permissions on `.api-keys` file ### "Module not found" ```bash pip3 install -r requirements.txt # if needed ``` ### Wrong model selected 1. Customize task mappings via wizard 2. Use explicit model in `sessions_spawn --model` 3. Adjust cost optimization preference ## 📖 Additional Resources - **Provider Docs:** - [Anthropic](https://docs.anthropic.com) - [OpenAI](https://platform.openai.com/docs) - [Gemini](https://ai.google.dev/docs) - [Moonshot](https://platform.moonshot.cn/docs) - [Z.ai](https://api.z.ai/docs) - [GLM](https://open.bigmodel.cn/dev/api) - **Setup:** Run `python3 scripts/setup-wizard.py` - **Support:** Check `references/` folder for detailed guides