# whichllm
> Your hardware fits which local LLM?

whichllm helps you find the best local LLM model for your GPU hardware. It provides a database of GPU-to-model rankings based on real benchmarks (LiveBench, Aider, Chatbot Arena ELO, etc.).

## Core Pages

- **Home** `https://whichllm.net/` — GPU rankings table with search/filter/pagination, KPI overview, hot hardware cards, changelog, data trends, explore section.
- **Guide** `https://whichllm.net/guide` — Usage guide: hardware detection scripts (Python/PowerShell), python installation, output interpretation, API reference.
- **Changelog** `https://whichllm.net/blog` — Data update history and change log.
- **API Docs (JSON)** `https://whichllm.net/api/docs` — Full structured API documentation (39 endpoints).
- **OpenAPI 3.0 Spec** `https://whichllm.net/api/openapi.json` — OpenAPI 3.0 compliant specification for all endpoints.

## Data Sources

Rankings data stored in Cloudflare D1 (SQLite), updated daily from HuggingFace. Contains ~3800 ranking rows across 66+ GPU hardware models, 4 usage profiles (general, coding, vision, math).

## API Reference

Base URL: `https://whichllm.net`
Format: JSON
Cache: Cache-Control max-age=60-600s

### Rankings & Search

- **GET /api/rankings** — Paginated rankings table with filtering (profile, category, search, vram range, min score) and multi-column sorting. Parameters: page, limit, profile, category, search, min_score, vram_min, vram_max, sort (g/v/c/p/r/m/s/sp/lk/dl), dir (asc/desc), order. Curl: `curl 'https://whichllm.net/api/rankings?page=1&limit=20&profile=general&sort=s&dir=desc'`
- **GET /api/models** — Models for a specific GPU. Parameters: gpu (required), profile, limit. Curl: `curl 'https://whichllm.net/api/models?gpu=RTX+4090&profile=general'`
- **GET /api/models/{id}** — Model detail + all compatible GPUs. Curl: `curl 'https://whichllm.net/api/models/Llama-3-70B'`
- **GET /api/models/related** — Find alternative models with similar VRAM requirements. Parameters: model_id. Curl: `curl 'https://whichllm.net/api/models/related?model_id=Llama-3-70B'`
- **GET /api/reverse** — Reverse lookup: which GPUs can run a given model. Parameters: model, profile, limit. Curl: `curl 'https://whichllm.net/api/reverse?model=Llama&profile=general'`
- **GET /api/autocomplete** — GPU name autocomplete. Parameters: q (min 1 char), limit. Curl: `curl 'https://whichllm.net/api/autocomplete?q=rtx'`
- **GET /api/search** — Full-text search across GPU and model names. Parameters: q, profile, limit. Curl: `curl 'https://whichllm.net/api/search?q=4090&limit=5'`

### Detection & Matching

- **POST /api/detect** — GPU hardware detection. Accepts GPU name/vRAM/OS, returns matched GPU, top models per profile, and upgrade path. Parameters (JSON body): gpu_name (or "gpu"), vram_gb, ram_gb, os, profile. Curl: `curl -X POST 'https://whichllm.net/api/detect' -H 'Content-Type: application/json' -d '{"gpu_name":"RTX 4090","vram_gb":24,"os":"Windows"}'`

### Hot/KPI/Stats

- **GET /api/hot** — Top-ranked model per GPU (general profile, rank=1), sorted by score. No parameters. Curl: `curl 'https://whichllm.net/api/hot'`
- **GET /api/kpi** — Key metrics: top_score, hardware_count, total_configs, row_count. No parameters. Curl: `curl 'https://whichllm.net/api/kpi'`
- **GET /api/leaderboard** — Condensed leaderboard: rank=1 GPUs for a profile. Parameters: profile, limit. Curl: `curl 'https://whichllm.net/api/leaderboard?profile=general'`
- **GET /api/top-per-category** — Top 3 rank-1 GPUs per category. Parameters: profile. Curl: `curl 'https://whichllm.net/api/top-per-category?profile=general'`

### Comparison & Upgrade

- **GET /api/compare** — Compare two GPUs' model performance. Parameters: gpu1, gpu2, profile. Curl: `curl 'https://whichllm.net/api/compare?gpu1=RTX+4090&gpu2=RTX+3090'`
- **GET /api/similar** — Find GPUs with similar VRAM. Parameters: gpu, margin (GB). Curl: `curl 'https://whichllm.net/api/similar?gpu=rtx-4090&margin=8'`
- **GET /api/upgrade** — VRAM upgrade path from a given GPU. Parameters: gpu, profile. Curl: `curl 'https://whichllm.net/api/upgrade?gpu=rtx-4090'`
- **GET /api/profile-compare** — Single GPU cross-profile comparison (general/coding/vision/math). Parameters: gpu. Curl: `curl 'https://whichllm.net/api/profile-compare?gpu=rtx-4090'`

### Trends & History

- **GET /api/trends** — 30-day score and popularity trends. Curl: `curl 'https://whichllm.net/api/trends'`
- **GET /api/trend** — Single GPU score trend. Parameters: gpu, profile, days. Curl: `curl 'https://whichllm.net/api/trend?gpu=rtx-4090&profile=general&days=30'`
- **GET /api/trending** — Top search queries (last 7 days). Curl: `curl 'https://whichllm.net/api/trending'`
- **GET /api/history** — Changelog history. Parameters: days, limit. Curl: `curl 'https://whichllm.net/api/history?days=14'`

### Data & Export

- **GET /api/export** — Export data in JSON/NDJSON/CSV. Parameters: profile, category, format (json/ndjson/csv), limit (max 10000), fields. Curl: `curl 'https://whichllm.net/api/export?format=csv&limit=100'`
- **GET /api/all** — All raw rows (no pagination). Curl: `curl 'https://whichllm.net/api/all'`
- **POST /api/batch** — Batch GPU query (max 10 GPUs). JSON body: {gpus: [...], profile, limit}. Curl: `curl -X POST 'https://whichllm.net/api/batch' -H 'Content-Type: application/json' -d '{"gpus":["RTX 4090","RTX 3090"],"profile":"general"}'`

### VRAM Estimation

- **GET /api/vram/estimate** — Estimate VRAM usage for a model at different quantization levels. Parameters: model, quant. Curl: `curl 'https://whichllm.net/api/vram/estimate?model=Llama-3-70B&quant=Q4_K_M'`

### Categories & Stats

- **GET /api/categories** — Category overview with GPU/model counts and avg scores. Curl: `curl 'https://whichllm.net/api/categories'`
- **GET /api/stats** — Full statistics: overview, by-profile, top-10/bottom-10. Curl: `curl 'https://whichllm.net/api/stats'`
- **GET /api/stats/summary** — Condensed stats: model/gpu counts, avg/max score. Curl: `curl 'https://whichllm.net/api/stats/summary'`
- **GET /api/stats/distribution** — Score/profile/VRAM distribution. Curl: `curl 'https://whichllm.net/api/stats/distribution'`

### Changelog

- **GET /api/changelog** — Latest changelog entry. Curl: `curl 'https://whichllm.net/api/changelog'`

### Meta & Monitoring

- **GET /api/meta** — Last update timestamp. Curl: `curl 'https://whichllm.net/api/meta'`
- **GET /api/d1** — D1 database diagnostics (internal). Curl: `curl 'https://whichllm.net/api/d1'`
- **GET /api/stats/monitor** — KV cache hit rate + D1 latency monitoring. Curl: `curl 'https://whichllm.net/api/stats/monitor'`
- **GET /api/validate** — Data integrity checks. Curl: `curl 'https://whichllm.net/api/validate'`

### Management (restricted)

- **POST /api/seed** — Seed data from KV to D1 (requires SEED_GUARD_KEY). Curl: `curl -X POST 'https://whichllm.net/api/seed' -H 'x-guard-key: YOUR_KEY'`
- **POST /api/models/enrich** — Fetch model metadata from HuggingFace. Curl: `curl -X POST 'https://whichllm.net/api/models/enrich'`
- **POST /api/cron/snapshot** — Take daily snapshot for trends. Curl: `curl -X POST 'https://whichllm.net/api/cron/snapshot'`
- **GET /api/cron/enrich** — Cron: enrich models. Parameters: trigger. Curl: `curl 'https://whichllm.net/api/cron/enrich?trigger=whichllm-cron-2024'`

## Hardware Detection Scripts

- `detect.py` (Python 3.7+, Linux/macOS/Windows): `curl -sL https://whichllm.net/detect.py | python3`
- `detect.ps1` (PowerShell, Windows): `irm https://whichllm.net/detect.ps1 | iex`