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.

Quick Start

# Install
pip install modelhop

# Initialize config
modelhop init

# Route your first query
modelhop route "How do I reset my password?"

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

Commands

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

Examples:

# 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

Cost Tracking

Every query shows cost savings:

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

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.

Configuration

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

modelhop init

Default models:

Development

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

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

# Run tests
pytest

# Format code
black modelhop/

# Lint
ruff check modelhop/

Publishing

# Build
python -m build

# Upload to PyPI
twine upload dist/*

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Security

For security vulnerabilities, please see SECURITY.md.

Changelog

See CHANGELOG.md for version history.

Made with love by Aalok