codelion/mlx-model-explorer

MLX Model Explorer

Explore MLX models and quantizations for your Mac. Compare mlx-community models by memory, quantization, popularity and community experience. You can also contribute anonymous hardware and benchmark data to improve recommendations for everyone.

The question it answers: given my Mac, model family, size, context length and trade-off, which MLX model and quantization should I use?

What it does

• —Lists every model in `mlx-community`, refreshed from the Hub every 6 hours. Filter by family, size, quantization and context.
• —Estimates memory for each model: exact weight file sizes plus the KV cache at your context (read from config.json) plus runtime overhead. It then rates the fit against the GPU-usable memory of your Mac as Comfortable, Likely, Borderline or Unlikely.
• —Ranks results with a transparent score (hardware fit, quantization vs. your priority, context headroom, downloads and likes, recency, community data). Every result explains its score. The score never looks at who uploaded a model or what it is called.
• —Offers an optional browser hardware estimate (WebGPU). This is not an MLX benchmark; browsers can't run MLX or read unified memory size.
• —Provides an optional real MLX benchmark script (bench/mlx_explorer_bench.py) you run on your Mac with mlx-lm, and optional "how did it work?" reports.
• —Publishes anonymous event data to `mlx-community/mlx-model-explorer-data`, plus aggregate stats at /stats.

Privacy

No login, cookies, IP addresses, user-agent strings or fingerprints are stored. A random per-tab session ID counts sessions and is discarded when the tab closes. Browsers sending Global Privacy Control or Do Not Track send nothing unless the user opts in, and anyone can opt out on the page. Aggregates with fewer than 5 events are folded into "other". See the dataset card for the full schema.

Architecture

static/      index.html, app.js (UI + batched anonymous events), webgpu.js (browser estimate), stats page
app/         FastAPI
  catalogue.py      mlx-community listing, 6h refresh, disk cache + bundled snapshot fallback
  parsing.py        family / size / quantization / architecture from tags, config.json and names
  model_detail.py   lazy config.json + file sizes per model (cached, parallel, timeout-bounded)
  memory.py         weights + KV cache + overhead, GPU-usable memory, fit classes
  recommend.py      RecommendationEngine interface + HeuristicEngine v1
  events.py         strict event schema, bounds, note scrubbing, plausibility flags
  sink.py           buffered Parquet shards into data/incoming: local directory (dev) or Hub dataset (prod)
  stats.py          k-anonymous aggregates (one count per visit) + per-model community signals
bench/       mlx_explorer_bench.py (runs locally with mlx-lm; submits only with --submit)
data/        catalogue_snapshot.json.gz (fallback when the Hub API is unreachable)
scripts/     deploy.py (create/upload/publish), compact.py (monthly compaction)
tests/       pytest suite

The page records one summary row per visit (final filters, what was searched, hardware class, models opened/compared/visited) plus explicit contributions (feedback, MLX and browser benchmarks). Individual clicks are never logged. The Space buffers rows and writes one Parquet shard to data/incoming/YYYY/MM/DD/ at most hourly, or sooner after 2,000 rows. A failed upload stays spooled on disk and retries with backoff. Once a month, scripts/compact.py merges the previous month into data/events/YYYY-MM.parquet (see DEPLOY.md).

Configuration

Develop and test locally

uv venv .venv --python 3.12 && uv pip install --python .venv/bin/python -r requirements.txt pytest
.venv/bin/python -m pytest                        # unit + API tests
EXPLORER_SINK=local .venv/bin/uvicorn app.main:app --port 7860
open http://localhost:7860                        # events land in .runtime/local_dataset/

docker build -t mlx-model-explorer . && docker run --rm -p 7860:7860 -e EXPLORER_SINK=local mlx-model-explorer

Deploy

See DEPLOY.md. The Space and dataset are created private, tested end to end, and only made public once reviewed.