README.md

metadata

title: MLX Model Explorer
emoji: 🧭
colorFrom: gray
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
license: mit
short_description: Find the right MLX model and quantization for your Mac
tags:
  - mlx
  - apple-silicon
  - quantization

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

Env var	Default	Meaning
EXPLORER_SINK	local	hub (write to the dataset), local (write Parquet under EXPLORER_DATA_DIR), off (collect nothing)
DATASET_REPO	mlx-community/mlx-model-explorer-data	dataset for hub mode
HF_TOKEN	(none)	Space secret, a fine-grained token with write access to the dataset only. It is never used for catalogue requests
HF_READ_TOKEN	(none)	optional token for Hub reads (rate limits only)
EXPLORER_FLUSH_SECONDS	3600	maximum time between writes
EXPLORER_FLUSH_ROWS	2000	write early once this many rows are buffered
EXPLORER_DATA_PREFIX	data/incoming	where the Space writes shards
EXPLORER_ORGS	mlx-community	organizations to list
EXPLORER_RATE_PER_MIN	120	event requests per client per minute

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.