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

CODEBLOCK0

The wizard will guide you through:

1. 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

CODEBLOCK1

Step 3: Route Tasks with Sessions

CODEBLOCK2

📊 Supported Providers

Provider	Models	Best For	Key Format
Anthropic	claude-opus-4-5, claude-sonnet-4-5, claude-haiku-4-5	Coding, reasoning, creative	INLINECODE0
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
INLINECODE5	glm-4.5-air	Fastest, cheapest for quick queries
INLINECODE6

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

CODEBLOCK3

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. 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 INLINECODE14

📖 Usage Examples

Example 1: Cost-Optimized Workflow

CODEBLOCK4

Example 2: Progressive Escalation

CODEBLOCK5

Example 3: Parallel Processing

CODEBLOCK6

Example 4: Multimodal with Gemini

CODEBLOCK7

🛠️ Configuration Files

~/.model-router/config.json

CODEBLOCK8

~/.model-router/.api-keys

CODEBLOCK9

🔄 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: CODEBLOCK10

📚 Command Reference

Setup Wizard

python3 scripts/setup-wizard.py

Interactive configuration of providers, mappings, and preferences.

Task Classifier

python3 scripts/classify_task.py "your task description"
python3 scripts/classify_task.py "your task" --format json

Get model recommendation with reasoning.

List Models

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. 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"

CODEBLOCK14

Wrong model selected

1. 1. Customize task mappings via wizard
2. Use explicit model in INLINECODE18
3. Adjust cost optimization preference

📖 Additional Resources

• - Provider Docs:

- Anthropic - OpenAI - Gemini - Moonshot - Z.ai - GLM

• - Setup: Run INLINECODE19
• Support: Check references/ folder for detailed guides