Metadata-Version: 2.4
Name: smartpull
Version: 0.1.0
Summary: Hardware-aware LLM orchestration — zero-config local model setup for any GPU
License: MIT
Project-URL: Homepage, https://github.com/punvesh/smartpull
Project-URL: Issues, https://github.com/punvesh/smartpull/issues
Keywords: ollama,llm,local-ai,vram,gpu,quantization,devops
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1
Requires-Dist: jinja2>=3.1
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"

# smartpull ⚡

[![CI](https://github.com/punvesh/smartpull/actions/workflows/ci.yml/badge.svg)](https://github.com/punvesh/smartpull/actions)
[![PyPI](https://img.shields.io/pypi/v/smartpull)](https://pypi.org/project/smartpull/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Docker](https://img.shields.io/badge/docker-ready-blue)](Dockerfile)

> **Hardware-aware LLM orchestration. Zero config. Zero VRAM crashes. Just works.**

---

## The Problem

Every local LLM runner (Ollama, LM Studio) is **hardware-blind**.

You have to manually figure out:
- Which quantization fits your VRAM?
- What context window is safe?
- Why is your model swapping to RAM and running at 2 tok/s?

This wastes **30+ minutes** every time a new model drops.

---

## The Solution

```bash
pip install smartpull
smartpull build
```

```
🔍 Scanning hardware...
  GPU     : NVIDIA GeForce RTX 3050 Ti Laptop GPU
  Usable  : 2.38 GB (after 15% safety buffer)

✅ Model          : gemma4:e2b
✅ Quantization   : IQ4_XS
✅ Context window : 4,608 tokens
✅ Headroom       : 780 MB
✅ Swap risk      : LOW

📝 Modelfile written to: ./Modelfile

Run these commands:
  ollama pull gemma4:e2b
  ollama create smartpull-gemma4-e2b -f ./Modelfile
  ollama run smartpull-gemma4-e2b
```

**30 minutes → 10 seconds.**

---

## Install

```bash
pip install smartpull
```

Or run from source:

```bash
git clone https://github.com/punvesh/smartpull
cd smartpull
pip install -e ".[dev]"
```

---

## Commands

| Command | What it does |
|---|---|
| `smartpull scan` | Show your GPU hardware profile |
| `smartpull recommend` | Best model for your current VRAM |
| `smartpull build` | Generate Modelfile + print ollama commands |
| `smartpull matrix` | Show full model matrix reference table |

---

## How It Works

```
nvidia-smi
    ↓
Real-time VRAM (free, not total)
    ↓
15% safety buffer applied
    ↓
Model matrix lookup (VRAM → model + quant)
    ↓
MoE awareness check
    ↓
Dynamic context window scaling
    ↓
Jinja2 Modelfile generation
    ↓
ollama create → run
```

---

## Supported Models

| VRAM | Model | Quant | CTX |
|---|---|---|---|
| < 1.8 GB | gemma2:2b | IQ4_XS | 2,048 |
| 1.8–2.8 GB | gemma4:e2b | IQ4_XS | 4,096 |
| 2.8–4.5 GB | qwen2.5-coder:3b | Q4_K_S | 8,192 |
| 4.5–6 GB | qwen2.5-coder:7b | Q4_K_S | 16,384 |
| 6–9 GB | llama3.1:8b | Q5_K_M | 32,768 |
| 9 GB+ | qwen2.5-coder:14b | Q5_K_M | 32,768 |

---

## Docker

```bash
docker build -t smartpull .
docker run --gpus all smartpull recommend
```

---

## Development

```bash
pip install -e ".[dev]"
pytest tests/ -v
black .
```

---

## Roadmap

- [x] NVIDIA GPU support
- [x] Ollama Modelfile generation
- [x] MoE model awareness
- [x] Dynamic context window scaling
- [ ] Apple Silicon (MLX) support
- [ ] AMD ROCm support
- [ ] Claude Code bridge (auto-set ANTHROPIC_BASE_URL)
- [ ] GUI dashboard

---

## Contributing

PRs welcome. Open an issue first for large changes.

---

## License

MIT © [Punvesh](https://github.com/punvesh)
