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
• OpenAI
• Gemini
• Moonshot
• Z.ai
• GLM

• Setup: Run python3 scripts/setup-wizard.py
• Support: Check references/ folder for detailed guides