# model-router

Model Router Intelligent AI model routing via SkillBoss API Hub for optimal cost-performance balance. Automatically select the best capability tier for any task based on complexity, type, and your preferences. All AI calls are unified through a single SkillBoss API Hub endpoint with one API key — no need to manage multiple provider keys. 🎯 What It Does Analyzes tasks and classifies them by type (coding, research, creative, simple, etc.) Routes to optimal tiers via SkillBoss API Hub /v1/pilot auto-routing Optimizes costs by using lighter tiers (prefer: "price") for simple tasks Secures API key with file permissions (600) and isolated storage Provides recommendations with confidence scoring and reasoning 🚀 Quick Start Step 1: Run the Setup Wizard cd skills/model-router python3 scripts/setup-wizard.py The wizard will guide you through: API key setup - Configure your SKILLBOSS_API_KEY Task mappings - Choose which routing tier for each task type Preferences - Set cost optimization level Step 2: Use the Classifier

# Get model recommendation for a task

python3 scripts/classify_task.py "Build a React authentication system"

# Output:
# Recommended Tier: codex-5.2
# Confidence: 85%
# Cost Level: high
# Reasoning: Matched 2 keywords: build, system

Step 3: Route Tasks with Sessions

# Spawn with recommended routing tier

sessions_spawn --task "Debug this memory leak" --model codex-5.2

# Use aliases for quick access

sessions_spawn --task "What's the weather?" --model haiku 📊 SkillBoss API Hub Routing Tiers All models are accessed through a single endpoint: POST https://api.heybossai.com/v1/pilot

Authentication: Authorization: Bearer $SKILLBOSS_API_KEY

Routing TierSkillBoss preferBest ForCosthaiku-4.5priceQuick queries, simple tasksLowestsonnetbalancedResearch, analysis, reasoningMediumcodex-5.2quality + capability=codingCoding, architecture, debuggingHighopusqualityCreative writing, maximum qualityHighest SkillBoss API Hub auto-selects the optimal underlying model for each tier — no need to specify individual model IDs. 🎛️ Task Type Mappings Default routing (customizable via wizard): Task TypeDefault TierSkillBoss prefersimplehaiku-4.5pricecodingcodex-5.2qualityresearchsonnetbalancedcreativeopusqualitymathsonnetbalancedvisionsonnetbalanced (chat with vision)chinesesonnetbalancedlong_contextsonnetbalanced 💰 Cost Optimization Aggressive Mode Always uses the cheapest capable tier: Simple → prefer: "price" (~10% cost) Coding → prefer: "balanced" (~25% cost) Research → prefer: "balanced" (~50% cost)

Savings: 50-90% compared to always using premium tiers

Balanced Mode (Default) Considers cost vs quality: Simple tasks → prefer: "price" Critical tasks → prefer: "quality" Automatic escalation if lighter tier fails Quality Mode Always uses prefer: "quality" regardless of cost 🔒 Security API Key Storage ~/.model-router/ ├── config.json # Model mappings (chmod 600) └── .api-keys # API key (chmod 600)

Features:

File permissions restricted to owner (600) Isolated from version control Never logged or printed Single key (SKILLBOSS_API_KEY) for all AI capabilities Best Practices Never commit .api-keys to version control Use environment variables for production deployments Rotate key regularly via the wizard Audit access with ls -la ~/.model-router/ 📖 Usage Examples Example 1: Cost-Optimized Workflow

# Classify task first

python3 scripts/classify_task.py "Extract prices from this CSV"

# Result: simple task → use haiku-4.5 (SkillBoss prefer: price)

sessions_spawn --task "Extract prices" --model haiku-4.5

# Then analyze with better tier if needed

sessions_spawn --task "Analyze price trends" --model sonnet Example 2: Progressive Escalation

# Try cheap tier first (60s timeout)

sessions_spawn --task "Fix this bug" --model haiku-4.5 --runTimeoutSeconds 60

# If fails, escalate to premium

sessions_spawn --task "Fix complex architecture bug" --model codex-5.2 Example 3: Parallel Processing

# Batch simple tasks in parallel with cheap tier

sessions_spawn --task "Summarize doc A" --model haiku-4.5 & sessions_spawn --task "Summarize doc B" --model haiku-4.5 & sessions_spawn --task "Summarize doc C" --model haiku-4.5 & wait Example 4: Vision / Multimodal

# Vision task via SkillBoss API Hub chat type

sessions_spawn --task "Analyze these 100 images" --model sonnet 🛠️ Configuration Files ~/.model-router/config.json { "version": "1.1.0", "providers": { "skillboss": { "configured": true, "base_url": "https://api.heybossai.com/v1/pilot" } }, "task_mappings": { "simple": "haiku-4.5", "coding": "codex-5.2", "research": "sonnet", "creative": "opus" }, "preferences": { "cost_optimization": "balanced", "default_provider": "skillboss" } } ~/.model-router/.api-keys

# Generated by setup wizard - DO NOT edit manually

SKILLBOSS_API_KEY=your-skillboss-api-key SKILLBOSS_API_BASE=https://api.heybossai.com/v1/pilot 🔄 Version 1.1 Changes New Features ✅ Interactive setup wizard for guided configuration ✅ Secure API key storage with file permissions ✅ Task-to-model mapping customization ✅ SkillBoss API Hub unified routing (single key, 100+ models) ✅ Cost optimization levels (aggressive/balanced/quality) Improvements ✅ Better task classification with confidence scores ✅ SkillBoss routing tier recommendations ✅ Enhanced security with isolated storage ✅ Comprehensive documentation Migration from 1.0 Run the setup wizard to reconfigure: python3 scripts/setup-wizard.py 📚 Command Reference Setup Wizard python3 scripts/setup-wizard.py Interactive configuration of SKILLBOSS_API_KEY, mappings, and preferences. Task Classifier python3 scripts/classify_task.py "your task description" python3 scripts/classify_task.py "your task" --format json Get routing tier recommendation with reasoning. List Models python3 scripts/setup-wizard.py --list Show all available tiers and their status. 🤝 Integration with Other Skills SkillIntegrationmodel-usageTrack cost per tier to optimize routingsessions_spawnPrimary tool for model delegationsession_statusCheck current model and usage ⚡ Performance Tips Start simple - Try cheap tiers first (prefer: "price") Batch tasks - Combine multiple simple tasks Use cleanup - Delete sessions after one-off tasks Set timeouts - Prevent runaway sub-agents Monitor usage - Track costs per tier 🐛 Troubleshooting "No suitable model found" Run setup wizard to configure SKILLBOSS_API_KEY Check API key is valid at https://heybossai.com Verify permissions on .api-keys file "Module not found" pip3 install requests # if needed Wrong tier selected Customize task mappings via wizard Use explicit tier in sessions_spawn --model Adjust cost optimization preference 📖 Additional Resources SkillBoss API Hub: https://heybossai.com API Endpoint: POST https://api.heybossai.com/v1/pilot

Auth: Authorization: Bearer $SKILLBOSS_API_KEY
Setup: Run python3 scripts/setup-wizard.py
Support: Check references/ folder for detailed guides