Metadata-Version: 2.5
Name: modelhop
Version: 1.0.8
Summary: Intelligent LLM router that saves 60-90% on API costs by hopping to the cheapest capable model
Project-URL: Homepage, https://github.com/aalok101singh/modelhop
Project-URL: Documentation, https://github.com/aalok101singh/modelhop#readme
Project-URL: Repository, https://github.com/aalok101singh/modelhop
Project-URL: Issues, https://github.com/aalok101singh/modelhop/issues
Author-email: Aalok <aalok101singh@users.noreply.github.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.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.9
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

<p align="center">
  <img src="https://img.shields.io/badge/-frog-green?style=for-the-badge&logo=python&logoColor=white" alt="ModelHop Frog"/>
</p>

<h1 align="center">
  <br>
  ModelHop
  <br>
</h1>

<h4 align="center">Save 60-90% on LLM costs by hopping to the right model.</h4>

<p align="center">
  <a href="https://github.com/aalok101singh/modelhop/actions/workflows/ci.yml">
    <img src="https://img.shields.io/github/actions/workflow/status/aalok101singh/modelhop/ci.yml?style=flat-square" alt="CI Status"/>
  </a>
  <a href="https://pypi.org/project/modelhop/">
    <img src="https://img.shields.io/pypi/v/modelhop?style=flat-square" alt="PyPI Version"/>
  </a>
  <a href="https://pypi.org/project/modelhop/">
    <img src="https://img.shields.io/pypi/pyversions/modelhop?style=flat-square" alt="Python Versions"/>
  </a>
  <a href="https://github.com/aalok101singh/modelhop/blob/main/LICENSE">
    <img src="https://img.shields.io/github/license/aalok101singh/modelhop?style=flat-square" alt="License"/>
  </a>
</p>

---

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

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

| Provider | Key | Free Tier |
|----------|-----|-----------|
| Groq | [console.groq.com](https://console.groq.com) | Yes |
| Google Gemini | [aistudio.google.com](https://aistudio.google.com/apikey) | 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
```

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

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

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

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

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

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

## Development

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

```bash
# Build
python -m build

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

## Contributing

Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

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

## Security

For security vulnerabilities, please see [SECURITY.md](SECURITY.md).

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.

---

<p align="center">
  Made with love by <a href="https://github.com/aalok101singh">Aalok</a>
</p>
