:frog: ModelHop

Save 60-90% on LLM costs by hopping to the right model.

ModelHop is an intelligent LLM router that automatically picks the cheapest capable model for each query. It uses multi-signal feature extraction, experience-based learning, and adaptive confidence thresholds to route simple queries to free models while reserving premium models for complex tasks.

:zap: Quick Start

pip install modelhop
modelhop init
modelhop route "How do I reset my password?"

:lock: Setup API Keys

Get at least one API key from a free provider:

Set your keys:

# Option 1: Interactive setup (recommended)
modelhop setup

# Option 2: Manual .env file
cp .env.example .env
# Edit .env with your keys

:hammer_and_wrench: Commands

:brain: How It Works

Query → Feature Extraction → AI Analysis → Learning Router → Model Selection
                                                                    |
                                                            ┌───────┴───────┐
                                                            │   Free Tier   │
                                                            │  (Groq/Gemini)│
                                                            └───────┬───────┘
                                                                    │
                                                            If complex/failed
                                                                    │
                                                            ┌───────┴───────┐
                                                            │ Premium Tier  │
                                                            │   (GPT-4)     │
                                                            └───────────────┘

Multi-Signal Analysis:

• Code keyword detection (algorithm, debugging, implementation)
• Query intent classification (explain, implement, debug, compare)
• Constraint detection (O(n), O(1), time/space complexity)
• Experience memory (past routing outcomes)
• Per-model performance tracking
• Adaptive confidence thresholds

Example:

# Simple query → Free model
modelhop r "What is Python?"
# Routes to: groq-qwen3-8-27b (FREE)

# Complex query → Premium model
modelhop r "Implement a red-black tree with O(log n) insertion"
# Routes to: openai-gpt-4 (PREMIUM)

# Failed premium → Automatic fallback
modelhop r "Complex query" # GPT-4 fails → falls back to Groq

:receipt: Cost Tracking

Every query shows cost savings:

╭────────────────────── Cost Analysis ──────────────────────╮
│ :moneybag: Actual cost:          $0.0000                  │
│ :x: Would cost (GPT-4):  $0.0625                         │
│ :sparkles: You saved:            $0.0625 (100%)          │
│ :tada: AMAZING SAVINGS                                    │
╰──────────────────────────────────────────────────────────╯

:bar_chart: Verbose Mode

Add --verbose for full intelligence stats:

modelhop r "Implement quicksort" --verbose

Shows: feature extraction, AI analysis, experience memory, routing decision, hop score, and system intelligence stats.

:gear: Configuration

ModelHop uses a modelhop.yaml config file. Generate the default with:

modelhop init

Default models:

:wrench: Development

# Clone the repo
git clone https://github.com/yourusername/modelhop.git
cd modelhop

# Install in dev mode
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black modelhop/

# Lint
ruff check modelhop/

:package: Publishing

# Build
python -m build

# Upload to PyPI
twine upload dist/*

:memo: License

MIT License - see LICENSE for details.

:heart: Contributing

Contributions welcome! Please open an issue or PR.