Metadata-Version: 2.5
Name: modelhop
Version: 1.0.6
Summary: Intelligent LLM router that saves 60-90% on API costs by hopping to the cheapest capable model
Project-URL: Homepage, https://github.com/yourusername/modelhop
Project-URL: Documentation, https://github.com/yourusername/modelhop#readme
Project-URL: Repository, https://github.com/yourusername/modelhop
Project-URL: Issues, https://github.com/yourusername/modelhop/issues
Author-email: Aalok <your@email.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,cost-optimization,gemini,groq,llm,openai,routing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: click>=8.0
Requires-Dist: google-generativeai>=0.5
Requires-Dist: groq>=0.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: openai>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: black>=23.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# :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

```bash
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:

| Provider | Key | Free Tier |
|----------|-----|-----------|
| Groq | [console.groq.com](https://console.groq.com) | :white_check_mark: Yes |
| Google Gemini | [aistudio.google.com](https://aistudio.google.com/apikey) | :white_check_mark: Yes |
| OpenAI | [platform.openai.com](https://platform.openai.com/api-keys) | Paid |

Set your keys:

```bash
# 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

| Command | Alias | Description |
|---------|-------|-------------|
| `modelhop route <query>` | `modelhop r` | Route a query to the cheapest capable model |
| `modelhop setup` | `modelhop set` | Interactive API key setup wizard |
| `modelhop init` | `modelhop i` | Generate default config file |
| `modelhop stats` | `modelhop s` | Show routing statistics |
| `modelhop history` | `modelhop h` | Show recent query history |
| `modelhop providers` | `modelhop p` | List available providers and models |
| `modelhop benchmark` | `modelhop b` | Run benchmark queries |
| `modelhop config` | `modelhop c` | Show current configuration |
| `modelhop example` | `modelhop e` | Show example usage |
| `modelhop shield` | - | Show quality monitoring status |
| `modelhop hub` | - | Show community hub configs |
| `modelhop welcome` | - | Show welcome message |

## :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:**

```bash
# 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:

```bash
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:

```bash
modelhop init
```

**Default models:**

| Model | Provider | Tier | Cost |
|-------|----------|------|------|
| `qwen/qwen3.8-27b` | Groq | Free | $0.00 |
| `gemini-3.6-flash` | Google | Free | $0.00 |
| `gpt-4` | OpenAI | Premium | $0.03/$0.06 per 1K |

## :wrench: Development

```bash
# 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

```bash
# Build
python -m build

# Upload to PyPI
twine upload dist/*
```

## :memo: License

MIT License - see [LICENSE](LICENSE) for details.

## :heart: Contributing

Contributions welcome! Please open an issue or PR.
