Deploy MLX Model Explorer (private test)

.dockerignore

@@ -0,0 +1,9 @@
+.venv
+.cache
+.runtime
+.runtime-server.log
+.pytest_cache
+**/__pycache__
+tests
+scripts
+dataset_card

DEPLOY.md

@@ -0,0 +1,76 @@
+# Deploying MLX Model Explorer
+
+The Space and dataset are created **private**, verified end to end, and only then made public.
+
+Prerequisites: `hf auth login` as a member of `mlx-community` with write access, plus the project venv (`uv pip install -r requirements.txt`).
+
+## 1. Verify locally
+
+```bash
+.venv/bin/python -m pytest
+EXPLORER_SINK=local EXPLORER_FLUSH_SECONDS=20 .venv/bin/uvicorn app.main:app --port 7860
+# walk through the UI; events land in .runtime/local_dataset/data/events/
+docker build --platform linux/amd64 -t mlx-model-explorer . \
+  && docker run --rm -p 7860:7860 -e EXPLORER_SINK=local mlx-model-explorer
+```
+
+## 2. Create private repos
+
+```bash
+.venv/bin/python scripts/deploy.py status
+.venv/bin/python scripts/deploy.py create      # refuses if the Space exists; add --allow-existing-dataset if the dataset was created earlier
+```
+
+This creates `mlx-community/mlx-model-explorer-data` (private dataset, card uploaded) and `codelion/mlx-model-explorer` (private Docker Space with `EXPLORER_SINK=hub`, `DATASET_REPO`, `EXPLORER_FLUSH_SECONDS=600`).
+
+> **Why the Space isn't in `mlx-community`:** Hugging Face now requires a Team or Enterprise plan for an organization to run Docker or Gradio Spaces on free CPU (`402 Payment Required`). The dataset can live in the org. Once an org admin has a plan or a hardware grant, deploy there with `SPACE_REPO=mlx-community/mlx-model-explorer scripts/deploy.py create --allow-existing-dataset` followed by `upload`.
+
+## 3. Dataset write token
+
+Create a **fine-grained** token at https://huggingface.co/settings/tokens with *write* permission on `mlx-community/mlx-model-explorer-data` only. Don't use a personal all-access token: anything in a Space secret is available to the running app.
+
+```bash
+HF_DATASET_WRITE_TOKEN=hf_xxx .venv/bin/python scripts/deploy.py secret
+```
+
+## 4. Test the ingestion path against the private dataset from this machine
+
+```bash
+EXPLORER_SINK=hub EXPLORER_DATA_PREFIX=data/_test EXPLORER_FLUSH_SECONDS=30 \
+  HF_TOKEN=$(cat ~/.cache/huggingface/token) .venv/bin/uvicorn app.main:app --port 7860
+```
+
+## 5. Upload and test the private Space
+
+```bash
+.venv/bin/python scripts/deploy.py variable EXPLORER_DATA_PREFIX data/_test   # keep test events separate
+.venv/bin/python scripts/deploy.py upload
+.venv/bin/python scripts/deploy.py status                                     # wait for RUNNING
+```
+
+Open https://huggingface.co/spaces/codelion/mlx-model-explorer while logged in. Run the full flow, then confirm a shard appears under `data/_test/` in the dataset (after the flush interval, or restart the Space to force a flush).
+
+To submit a benchmark to the private Space, use its direct URL and a token:
+
+```bash
+python bench/mlx_explorer_bench.py --model mlx-community/Qwen3-0.6B-4bit \
+  --submit https://codelion-mlx-model-explorer.hf.space --hf-token $(cat ~/.cache/huggingface/token)
+```
+
+## 6. Go public (only after review)
+
+```bash
+.venv/bin/python scripts/deploy.py variable EXPLORER_DATA_PREFIX data/events
+.venv/bin/python scripts/deploy.py clean-test-data
+.venv/bin/python scripts/deploy.py publish --yes-make-public
+```
+
+`publish` refuses while `data/_test/` still exists.
+
+## Updating
+
+Change code, run the tests, `docker build` locally, then `scripts/deploy.py upload -m "what changed"`. Events are append-only, so redeploys never touch existing data. On shutdown the app flushes buffered events, and anything that fails to upload is retried from the on-disk spool.
+
+## Kill switch
+
+`scripts/deploy.py variable EXPLORER_SINK off` stops all collection. The UI keeps working and the event endpoint accepts nothing.

Dockerfile

@@ -1,2 +1,23 @@
-FROM huggingface/autotrain-advanced:latest
-CMD uvicorn autotrain.app:app --host 0.0.0.0 --port 7860 --reload --workers 4
+FROM python:3.12-slim
+
+# Hugging Face Spaces run containers as uid 1000.
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    PYTHONUNBUFFERED=1 \
+    EXPLORER_DATA_DIR=/home/user/runtime \
+    EXPLORER_CACHE=/home/user/cache
+
+WORKDIR /home/user/app
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir --user -r requirements.txt
+
+COPY --chown=user app ./app
+COPY --chown=user static ./static
+COPY --chown=user bench ./bench
+COPY --chown=user data ./data
+
+EXPOSE 7860
+# --timeout-graceful-shutdown lets the sink flush buffered events when the Space stops.
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860", "--proxy-headers", "--forwarded-allow-ips", "*", "--timeout-graceful-shutdown", "20", "--no-access-log"]

README.md

@@ -1,10 +1,84 @@
 ---
-title: AutoTrain Advanced
-emoji: 🚀
-colorFrom: blue
-colorTo: green
+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
+datasets:
+  - mlx-community/mlx-model-explorer-data
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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`](https://huggingface.co/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`](https://huggingface.co/datasets/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           append-only Parquet shards: local directory (dev) or Hub dataset (prod)
+  stats.py          k-anonymous aggregates + 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)
+tests/       pytest suite
+```
+
+Events are buffered and written as **one Parquet shard per flush** (default every 10 minutes, only when there is data) under `data/events/YYYY/MM/DD/`. That caps Hub commits at about 144 a day. Shards are never rewritten, and a failed upload stays spooled on disk and retries with backoff.
+
+## 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` | `600` | flush interval |
+| `EXPLORER_DATA_PREFIX` | `data/events` | path prefix inside the dataset (tests use `data/_test`) |
+| `EXPLORER_ORGS` | `mlx-community` | organizations to list |
+| `EXPLORER_RATE_PER_MIN` | `120` | event requests per client per minute |
+
+## Develop and test locally
+
+```bash
+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](DEPLOY.md). The Space and dataset are created **private**, tested end to end, and only made public once reviewed.

app/catalogue.py

@@ -0,0 +1,329 @@
+"""Cached view of the mlx-community model catalogue.
+
+The whole org listing is ~6 paged requests, so we fetch it all on startup and
+every few hours, and serve every UI interaction from memory. If the Hub is down
+we fall back to the last good copy on disk, then to the snapshot bundled with
+the Space.
+"""
+
+from __future__ import annotations
+
+import gzip
+import json
+import logging
+import os
+import threading
+import time
+from collections import Counter
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable
+
+import httpx
+
+from .parsing import (
+    LLM_PIPELINES,
+    base_model_of,
+    detect_family,
+    detect_params,
+    detect_quant,
+    param_bucket,
+    quant_bucket,
+)
+
+log = logging.getLogger("explorer.catalogue")
+
+ROOT = Path(__file__).resolve().parent.parent
+BUNDLED_SNAPSHOT = ROOT / "data" / "catalogue_snapshot.json.gz"
+LIST_FIELDS = ["downloads", "likes", "lastModified", "createdAt", "tags", "safetensors",
+               "pipeline_tag", "library_name", "gated", "private"]
+
+
+def hf_endpoint() -> str:
+    return os.environ.get("HF_ENDPOINT", "https://huggingface.co").rstrip("/")
+
+
+def orgs() -> list[str]:
+    raw = os.environ.get("EXPLORER_ORGS", "mlx-community")
+    return [o.strip() for o in raw.split(",") if o.strip()]
+
+
+@dataclass
+class ModelRecord:
+    id: str
+    name: str
+    family: str
+    pipeline: str | None
+    is_llm: bool
+    downloads: int
+    likes: int
+    created: str | None
+    modified: str | None
+    base_model: str | None
+    params: float | None
+    active_params: float | None
+    params_source: str
+    moe: bool
+    size_bucket: str | None
+    partial: bool
+    quant: dict
+    quant_bucket: str
+    tags: list[str] = field(default_factory=list)
+
+    def public(self) -> dict:
+        d = self.__dict__.copy()
+        d["url"] = f"https://huggingface.co/{self.id}"
+        return d
+
+
+def _num(v: Any) -> int:
+    return int(v) if isinstance(v, (int, float)) and not isinstance(v, bool) and v >= 0 else 0
+
+
+def build_record(raw: dict) -> ModelRecord | None:
+    """One malformed entry must never take down the catalogue."""
+    try:
+        mid = raw.get("id") or raw.get("modelId")
+        if not isinstance(mid, str) or "/" not in mid:
+            return None
+        if raw.get("private") is True:
+            return None  # never list private repos, whatever token fetched them
+        tags = [t for t in (raw.get("tags") or []) if isinstance(t, str)]
+        quant = detect_quant(mid, tags)
+        params = detect_params(mid, raw.get("safetensors"), bits=quant.bits)
+        pipeline = raw.get("pipeline_tag") if isinstance(raw.get("pipeline_tag"), str) else None
+        return ModelRecord(
+            id=mid,
+            name=mid.split("/", 1)[1],
+            family=detect_family(mid, tags),
+            pipeline=pipeline,
+            is_llm=pipeline in LLM_PIPELINES or (pipeline is None and "conversational" in tags),
+            downloads=_num(raw.get("downloads")),
+            likes=_num(raw.get("likes")),
+            created=raw.get("createdAt") if isinstance(raw.get("createdAt"), str) else None,
+            modified=raw.get("lastModified") if isinstance(raw.get("lastModified"), str) else None,
+            base_model=base_model_of(tags),
+            params=params.total,
+            active_params=params.active,
+            params_source=params.source,
+            moe=params.moe,
+            size_bucket=param_bucket(params.total),
+            partial=params.partial,
+            quant=quant.to_dict(),
+            quant_bucket=quant_bucket(quant),
+            tags=[t for t in tags if not t.startswith(("region:", "base_model:"))][:20],
+        )
+    except Exception:  # pragma: no cover - defensive
+        log.warning("skipping malformed model entry", exc_info=True)
+        return None
+
+
+Fetcher = Callable[[], list[dict]]
+
+
+def fetch_listing(client: httpx.Client | None = None, timeout: float = 30.0) -> list[dict]:
+    own = client is None
+    client = client or httpx.Client(timeout=timeout, headers=_auth_headers())
+    try:
+        out: list[dict] = []
+        for org in orgs():
+            url = f"{hf_endpoint()}/api/models"
+            params: list[tuple[str, str]] | None = [("author", org), ("limit", "1000")] + [
+                ("expand[]", f) for f in LIST_FIELDS
+            ]
+            pages = 0
+            while url and pages < 50:
+                resp = _get_with_backoff(client, url, params)
+                out.extend(x for x in resp.json() if isinstance(x, dict))
+                url = resp.links.get("next", {}).get("url")
+                params = None
+                pages += 1
+        return out
+    finally:
+        if own:
+            client.close()
+
+
+def _auth_headers() -> dict:
+    # Deliberately NOT HF_TOKEN: the dataset write token may also see private org repos,
+    # which must never appear in a public catalogue. HF_READ_TOKEN is only for rate limits.
+    tok = os.environ.get("HF_READ_TOKEN")
+    return {"Authorization": f"Bearer {tok}"} if tok else {}
+
+
+def _get_with_backoff(client: httpx.Client, url: str, params=None, tries: int = 4) -> httpx.Response:
+    delay = 2.0
+    for attempt in range(tries):
+        resp = client.get(url, params=params)
+        if resp.status_code == 429 or resp.status_code >= 500:
+            if attempt == tries - 1:
+                resp.raise_for_status()
+            retry_after = resp.headers.get("Retry-After")
+            wait = float(retry_after) if retry_after and retry_after.isdigit() else delay
+            time.sleep(min(wait, 60))
+            delay *= 2
+            continue
+        resp.raise_for_status()
+        return resp
+    raise RuntimeError("unreachable")
+
+
+class Catalogue:
+    def __init__(
+        self,
+        fetcher: Fetcher = fetch_listing,
+        cache_dir: Path | None = None,
+        refresh_seconds: float = 6 * 3600,
+        snapshot: Path = BUNDLED_SNAPSHOT,
+    ):
+        self._fetcher = fetcher
+        self._cache_file = (cache_dir or Path(os.environ.get("EXPLORER_CACHE", ROOT / ".cache"))) / "catalogue.json.gz"
+        self._snapshot = snapshot
+        self.refresh_seconds = refresh_seconds
+        self._lock = threading.Lock()
+        self.records: list[ModelRecord] = []
+        self.by_id: dict[str, ModelRecord] = {}
+        self.source = "empty"  # live | disk-cache | snapshot | empty
+        self.loaded_at: float | None = None
+        self.last_error: str | None = None
+        self.skipped = 0
+
+    # -- loading
+    def load_offline(self) -> None:
+        """Serve something immediately (last cache, else bundled snapshot) while the live fetch runs."""
+        if self.records:
+            return
+        for path, src in ((self._cache_file, "disk-cache"), (self._snapshot, "snapshot")):
+            raw = _read_gz(path)
+            if raw:
+                self._install(raw, src)
+                return
+
+    def refresh(self) -> None:
+        try:
+            raw = self._fetcher()
+            if not raw:
+                raise RuntimeError("empty listing")
+            self._install(raw, "live")
+            self._write_cache(raw)
+            self.last_error = None
+            return
+        except Exception as e:
+            self.last_error = f"{type(e).__name__}: {e}"[:300]
+            log.warning("catalogue refresh failed: %s", self.last_error)
+        self.load_offline()  # keeps serving what we have, or falls back
+
+    def _install(self, raw: list[dict], source: str) -> None:
+        recs = [r for r in (build_record(x) for x in raw) if r is not None]
+        with self._lock:
+            self.records = recs
+            self.by_id = {r.id: r for r in recs}
+            self.source = source
+            self.loaded_at = time.time()
+            self.skipped = len(raw) - len(recs)
+
+    def _write_cache(self, raw: list[dict]) -> None:
+        try:
+            self._cache_file.parent.mkdir(parents=True, exist_ok=True)
+            tmp = self._cache_file.with_suffix(".tmp")
+            with gzip.open(tmp, "wt") as f:
+                json.dump(raw, f)
+            tmp.replace(self._cache_file)
+        except OSError:
+            log.warning("could not write catalogue cache", exc_info=True)
+
+    def start_background_refresh(self) -> threading.Thread:
+        def loop():
+            while True:
+                time.sleep(self.refresh_seconds)
+                self.refresh()
+
+        t = threading.Thread(target=loop, daemon=True, name="catalogue-refresh")
+        t.start()
+        return t
+
+    # -- queries
+    @property
+    def degraded(self) -> bool:
+        return self.source != "live"
+
+    def families(self, llm_only: bool = True, min_count: int = 8) -> list[dict]:
+        c = Counter(r.family for r in self.records if (r.is_llm or not llm_only))
+        fams = [{"family": f, "count": n} for f, n in c.most_common() if n >= min_count and f != "Other"]
+        other = sum(n for f, n in c.items() if n < min_count or f == "Other")
+        if other:
+            fams.append({"family": "Other", "count": other})
+        return fams
+
+    def matching(
+        self,
+        family: str | None = None,
+        size: str | None = None,
+        quant: str | None = None,
+        llm_only: bool = True,
+        search: str | None = None,
+    ) -> list[ModelRecord]:
+        known = {f["family"] for f in self.families(llm_only)} - {"Other"}
+        out = []
+        s = (search or "").strip().lower()
+        for r in self.records:
+            if llm_only and not r.is_llm:
+                continue
+            if family:
+                if family == "Other":
+                    if r.family in known:
+                        continue
+                elif r.family != family:
+                    continue
+            if size:
+                if size == "MoE":
+                    if not r.moe:
+                        continue
+                elif size == "unknown":
+                    if r.size_bucket is not None:
+                        continue
+                elif r.size_bucket != size:
+                    continue
+            if quant and r.quant_bucket != quant:
+                continue
+            if s and s not in r.id.lower():
+                continue
+            out.append(r)
+        return out
+
+    def siblings(self, rec: ModelRecord, limit: int = 12) -> list[ModelRecord]:
+        """Other quantizations of the same base model."""
+        if not rec.base_model:
+            return []
+        sib = sorted((r for r in self.records if r.base_model == rec.base_model and r.id != rec.id and not r.partial),
+                     key=lambda r: -r.downloads)
+        # The most downloaded repo of each bit width first, so 3/6/8-bit variants aren't
+        # crowded out by many 4-bit fine-tunes; then everything else by downloads.
+        best, seen = [], set()
+        for r in sib:
+            if r.quant_bucket not in seen:
+                seen.add(r.quant_bucket)
+                best.append(r)
+        rest = [r for r in sib if r not in best]
+        best.sort(key=lambda r: (r.quant["bits"] or 99, -r.downloads))
+        return (best + rest)[:limit]
+
+    def status(self) -> dict:
+        return {
+            "models": len(self.records),
+            "source": self.source,
+            "degraded": self.degraded,
+            "loaded_at": datetime.fromtimestamp(self.loaded_at, timezone.utc).isoformat() if self.loaded_at else None,
+            "last_error": self.last_error,
+            "skipped_malformed": self.skipped,
+        }
+
+
+def _read_gz(path: Path) -> list[dict] | None:
+    try:
+        with gzip.open(path, "rt") as f:
+            data = json.load(f)
+        return data if isinstance(data, list) else None
+    except (OSError, ValueError):
+        return None

app/events.py

@@ -0,0 +1,284 @@
+"""Event schema, validation and server-side enrichment.
+
+Clients send a small, typed event. Anything outside the schema is rejected
+(`extra="forbid"`), numbers are bounded, free text is capped and scrubbed, and the
+server fills in catalogue facts itself instead of trusting the client. Values that
+are allowed but implausible are kept and flagged, so dataset users can filter them.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from datetime import datetime, timezone
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from .memory import RAM_CLASSES, CONTEXTS, bits_per_weight
+from .parsing import PARAM_BUCKETS, QUANT_BUCKETS
+
+SCHEMA_VERSION = 1
+
+EventType = Literal[
+    "search", "filter", "model_view", "model_select", "model_click", "compare",
+    "hardware_test", "browser_benchmark", "feedback", "mlx_benchmark_submission",
+]
+
+CHIP_RE = re.compile(r"^Apple M[1-9]( (Pro|Max|Ultra))?$")
+MODEL_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,95}/[A-Za-z0-9][A-Za-z0-9._-]{0,95}$")
+SESSION_RE = re.compile(r"^[a-f0-9]{16,32}$")
+VERSION_RE = re.compile(r"^[0-9A-Za-z.+_-]{1,32}$")
+SHORT_TOKEN_RE = re.compile(r"^[A-Za-z0-9 ._+-]{1,40}$")
+
+_EMAIL = re.compile(r"[\w.+-]+@[\w-]+\.[\w.-]+")
+_URL = re.compile(r"(https?://|www\.)\S+", re.I)
+_LONG_DIGITS = re.compile(r"\+?\d[\d ()-]{7,}\d")
+
+MAX_NOTES = 280
+MAX_BATCH = 50
+
+
+def clean_notes(text: str | None) -> str | None:
+    if text is None:
+        return None
+    text = unicodedata.normalize("NFKC", str(text))
+    text = "".join(ch for ch in text if unicodedata.category(ch)[0] != "C" or ch == " ")
+    text = _EMAIL.sub("[email removed]", text)
+    text = _URL.sub("[link removed]", text)
+    text = _LONG_DIGITS.sub("[number removed]", text)
+    text = re.sub(r"\s+", " ", text).strip()
+    return text[:MAX_NOTES] or None
+
+
+class ClientEvent(BaseModel):
+    """What the browser (or the benchmark script) is allowed to send."""
+
+    model_config = ConfigDict(extra="forbid", str_max_length=200)
+
+    event_type: EventType
+    session_id: str | None = None
+
+    model_family: str | None = Field(None, max_length=40)
+    parameter_bucket: Literal[tuple(PARAM_BUCKETS + ["MoE", "unknown"])] | None = None  # type: ignore[valid-type]
+    quantization: Literal[tuple(QUANT_BUCKETS)] | None = None  # type: ignore[valid-type]
+    target_context: int | None = None
+    priority: Literal["balanced", "quality", "speed", "memory", "long_context"] | None = None
+    sort: Literal["recommended", "popular", "recent", "community", "all"] | None = None
+    result_count: int | None = Field(None, ge=0, le=100_000)
+
+    hardware_source: Literal["detected", "confirmed", "none"] | None = None
+    hardware_memory_class: int | None = None
+    webgpu_available: bool | None = None
+    webgpu_score: float | None = Field(None, ge=0, le=1_000_000)
+    gpu_capability_class: Literal["high", "mid", "entry", "unknown"] | None = None
+    gpu_vendor: str | None = Field(None, max_length=24)
+    gpu_arch: str | None = Field(None, max_length=24)
+    browser_family: Literal["chrome", "safari", "firefox", "edge", "other"] | None = None
+    os_family: Literal["macos", "ios", "windows", "linux", "android", "other"] | None = None
+    cpu_cores: int | None = Field(None, ge=1, le=256)
+
+    selected_model: str | None = None
+    selected_model_rank: int | None = Field(None, ge=0, le=10_000)
+    # what the user was shown for that model at the time (for studying recommendations)
+    recommendation_score: float | None = Field(None, ge=0, le=100)
+    fit_class: Literal["Comfortable", "Likely", "Borderline", "Unlikely"] | None = None
+    compare_models: list[str] | None = Field(None, max_length=5)
+
+    tried: Literal["yes", "no", "planning"] | None = None
+    quality_rating: Literal["excellent", "good", "acceptable"] | None = None
+    failure_reason: Literal["too_slow", "too_much_memory", "low_quality", "didnt_run"] | None = None
+    reported_ram_gb: int | None = None
+    reported_mac_model: str | None = None
+    reported_tokens_per_second: float | None = Field(None, gt=0, le=2000)
+    reported_context: int | None = Field(None, ge=128, le=4_194_304)
+    notes: str | None = Field(None, max_length=1000)
+
+    benchmark_type: Literal["webgpu_quick", "webgpu_full", "mlx_lm"] | None = None
+    benchmark_version: str | None = None
+    benchmark_duration_ms: int | None = Field(None, ge=0, le=600_000)
+    prompt_tokens: int | None = Field(None, ge=1, le=1_048_576)
+    generation_tokens: int | None = Field(None, ge=1, le=65_536)
+    prompt_tps: float | None = Field(None, gt=0, le=100_000)
+    generation_tps: float | None = Field(None, gt=0, le=2000)
+    ttft_ms: float | None = Field(None, ge=0, le=600_000)
+    peak_memory_gb: float | None = Field(None, gt=0, le=1024)
+    chip: str | None = None
+    mlx_version: str | None = None
+    mlx_lm_version: str | None = None
+    macos_major: int | None = Field(None, ge=11, le=40)
+
+    @field_validator("session_id")
+    @classmethod
+    def _session(cls, v):
+        if v is not None and not SESSION_RE.match(v):
+            raise ValueError("session_id must be 16-32 lowercase hex chars")
+        return v
+
+    @field_validator("selected_model")
+    @classmethod
+    def _model(cls, v):
+        if v is not None and not MODEL_ID_RE.match(v):
+            raise ValueError("invalid model id")
+        return v
+
+    @field_validator("compare_models")
+    @classmethod
+    def _models(cls, v):
+        if v is not None:
+            for m in v:
+                if not MODEL_ID_RE.match(m):
+                    raise ValueError("invalid model id in compare_models")
+        return v
+
+    @field_validator("target_context")
+    @classmethod
+    def _ctx(cls, v):
+        if v is not None and v not in CONTEXTS:
+            raise ValueError(f"target_context must be one of {CONTEXTS}")
+        return v
+
+    @field_validator("hardware_memory_class", "reported_ram_gb")
+    @classmethod
+    def _ram(cls, v):
+        if v is not None and v not in RAM_CLASSES:
+            raise ValueError(f"memory must be one of {RAM_CLASSES}")
+        return v
+
+    @field_validator("chip", "reported_mac_model")
+    @classmethod
+    def _chip(cls, v):
+        if v is not None and v != "other" and not CHIP_RE.match(v):
+            raise ValueError("chip must look like 'Apple M3 Max' or be 'other'")
+        return v
+
+    @field_validator("benchmark_version", "mlx_version", "mlx_lm_version")
+    @classmethod
+    def _ver(cls, v):
+        if v is not None and not VERSION_RE.match(v):
+            raise ValueError("invalid version string")
+        return v
+
+    @field_validator("model_family", "gpu_vendor", "gpu_arch")
+    @classmethod
+    def _short(cls, v):
+        if v is not None and not SHORT_TOKEN_RE.match(v):
+            raise ValueError("invalid token")
+        return v
+
+    @field_validator("notes")
+    @classmethod
+    def _notes(cls, v):
+        return clean_notes(v)
+
+
+class EventBatch(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    events: list[ClientEvent] = Field(..., min_length=1, max_length=MAX_BATCH)
+
+
+# Column order for the dataset. Every row has every column (null when unused).
+COLUMNS: dict[str, str] = {
+    "timestamp": "string", "schema_version": "int", "app_version": "string", "event_type": "string",
+    "session_id": "string",
+    "model_family": "string", "model_name": "string", "parameter_bucket": "string", "quantization": "string",
+    "quant_bits": "float", "quant_mixed": "bool",
+    "target_context": "int", "priority": "string", "sort": "string", "result_count": "int",
+    "hardware_source": "string", "hardware_memory_class": "int", "hardware_confirmed": "bool",
+    "webgpu_available": "bool", "webgpu_score": "float", "gpu_capability_class": "string",
+    "gpu_vendor": "string", "gpu_arch": "string", "browser_family": "string", "os_family": "string",
+    "cpu_cores": "int",
+    "selected_model": "string", "selected_model_rank": "int", "compare_models": "list",
+    "hf_downloads_at_selection": "int", "hf_likes_at_selection": "int",
+    "recommendation_score": "float", "fit_class": "string", "engine_version": "string",
+    "pipeline": "string",
+    "tried": "string", "outcome": "string", "quality_rating": "string", "failure_reason": "string",
+    "reported_ram_gb": "int", "reported_mac_model": "string", "reported_tokens_per_second": "float",
+    "reported_context": "int", "notes": "string",
+    "benchmark_type": "string", "benchmark_version": "string", "benchmark_duration_ms": "int",
+    "prompt_tokens": "int", "generation_tokens": "int", "prompt_tps": "float", "generation_tps": "float",
+    "ttft_ms": "float", "peak_memory_gb": "float", "chip": "string", "mlx_version": "string",
+    "mlx_lm_version": "string", "macos_major": "int",
+    "suspicious_flags": "list",
+}
+
+
+def utc_now_seconds() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def to_row(ev: ClientEvent, catalogue=None, app_version: str = "dev", engine_version: str | None = None) -> dict:
+    """Validated client event -> dataset row, with server-side facts and suspicion flags."""
+    d = ev.model_dump()
+    row = {k: None for k in COLUMNS}
+    for k, v in d.items():
+        if k in row:
+            row[k] = v
+    row["timestamp"] = utc_now_seconds()
+    row["schema_version"] = SCHEMA_VERSION
+    row["app_version"] = app_version
+    row["engine_version"] = engine_version
+    row["hardware_confirmed"] = ev.hardware_source == "confirmed" if ev.hardware_source else None
+    if ev.tried == "yes":
+        if ev.failure_reason:
+            row["outcome"] = "problem"
+        elif ev.quality_rating:
+            row["outcome"] = "worked"
+    flags: list[str] = []
+
+    rec = None
+    if ev.selected_model and catalogue is not None:
+        rec = catalogue.by_id.get(ev.selected_model)
+        if rec is None:
+            flags.append("unknown_model")
+        else:
+            row["model_name"] = rec.name
+            row["model_family"] = row["model_family"] or rec.family
+            row["parameter_bucket"] = row["parameter_bucket"] or rec.size_bucket
+            row["quantization"] = row["quantization"] or rec.quant_bucket
+            row["quant_bits"] = rec.quant.get("bits")
+            row["quant_mixed"] = rec.quant.get("mixed")
+            row["hf_downloads_at_selection"] = rec.downloads
+            row["hf_likes_at_selection"] = rec.likes
+            row["pipeline"] = rec.pipeline
+    if ev.compare_models and catalogue is not None:
+        if any(m not in catalogue.by_id for m in ev.compare_models):
+            flags.append("unknown_model_in_compare")
+
+    flags += plausibility_flags(ev, rec)
+    row["suspicious_flags"] = sorted(set(flags))
+    return row
+
+
+# Apple Silicon memory bandwidth tops out around 800 GB/s; decode speed is bounded
+# by bandwidth / bytes read per token. Allow 3x headroom for speculative decoding.
+MAX_BANDWIDTH_GBPS = 800
+TPS_HEADROOM = 3.0
+
+
+def plausibility_flags(ev: ClientEvent, rec=None) -> list[str]:
+    flags = []
+    tps_values = [v for v in (ev.generation_tps, ev.reported_tokens_per_second) if v]
+    if rec is not None and tps_values:
+        active = rec.active_params or rec.params
+        bpw = bits_per_weight(rec.quant.get("bits"), rec.quant.get("mode"))
+        if active and bpw:
+            gb_per_token = active * bpw / 8 / 1e9
+            ceiling = MAX_BANDWIDTH_GBPS / max(gb_per_token, 0.05) * TPS_HEADROOM
+            if max(tps_values) > ceiling:
+                flags.append("implausible_tps")
+    ram = ev.reported_ram_gb or ev.hardware_memory_class
+    if ev.peak_memory_gb and ram and ev.peak_memory_gb > ram * 1.05:
+        flags.append("peak_memory_exceeds_ram")
+    if ev.event_type == "mlx_benchmark_submission":
+        if not (ev.selected_model and ev.generation_tps and ev.benchmark_version):
+            flags.append("incomplete_benchmark")
+        if ev.benchmark_type not in (None, "mlx_lm"):
+            flags.append("benchmark_type_mismatch")
+    if ev.event_type == "browser_benchmark" and ev.benchmark_type == "mlx_lm":
+        flags.append("benchmark_type_mismatch")
+    if ev.webgpu_score and ev.webgpu_score > 200_000:
+        flags.append("implausible_webgpu_score")
+    if ev.failure_reason and ev.quality_rating:
+        flags.append("conflicting_feedback")
+    return flags

app/main.py

@@ -0,0 +1,275 @@
+"""MLX Model Explorer: FastAPI backend + static frontend."""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+import time
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Literal
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel, Field, ValidationError
+
+from .catalogue import ROOT, Catalogue
+from .events import EventBatch, to_row
+from .memory import CONTEXTS, RAM_CLASSES
+from .model_detail import DetailCache
+from .parsing import PARAM_BUCKETS, QUANT_BUCKETS
+from .ratelimit import RateLimiter
+from .recommend import PRIORITIES, HeuristicEngine, Query, sort_results
+from .sink import make_sink
+from .stats import StatsCache
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(levelname)s %(message)s")
+log = logging.getLogger("explorer")
+# Never log client addresses: silence uvicorn's per-request access log.
+logging.getLogger("uvicorn.access").disabled = True
+logging.getLogger("httpx").setLevel(logging.WARNING)  # per-request Hub fetch logs are noise
+
+APP_VERSION = os.environ.get("EXPLORER_VERSION", "0.1.0")
+STATIC = ROOT / "static"
+MAX_BODY = 64 * 1024
+DETAIL_TOP_N = int(os.environ.get("EXPLORER_DETAIL_TOP_N", "24"))
+PREWARM_N = int(os.environ.get("EXPLORER_PREWARM", "300"))
+
+
+class RecommendRequest(BaseModel):
+    family: str | None = Field(None, max_length=40)
+    size: str | None = Field(None, max_length=10)
+    quant: str | None = Field(None, max_length=10)
+    context: int = 8192
+    ram_gb: float | None = Field(None, gt=0, le=1024)
+    ram_source: Literal["confirmed", "estimated"] | None = None
+    priority: Literal["balanced", "quality", "speed", "memory", "long_context"] = "balanced"
+    sort: Literal["recommended", "popular", "recent", "community", "all"] = "recommended"
+    llm_only: bool = True
+    search: str | None = Field(None, max_length=80)
+    offset: int = Field(0, ge=0, le=100_000)
+    limit: int = Field(24, ge=1, le=100)
+
+
+class State:
+    """Everything a request needs; swapped for fakes in tests."""
+
+    def __init__(self, catalogue=None, details=None, sink=None, fetch_live=True):
+        base = Path(os.environ.get("EXPLORER_DATA_DIR", ROOT / ".runtime"))
+        self.catalogue = catalogue or Catalogue()
+        self.details = details or DetailCache()
+        self.sink = sink or make_sink(base)
+        self.engine = HeuristicEngine()
+        self.limiter = RateLimiter(rate_per_minute=float(os.environ.get("EXPLORER_RATE_PER_MIN", "120")), burst=60)
+        self.existing_rows: list[dict] = []
+        self.stats = StatsCache(lambda: self.existing_rows + self.sink.all_rows)
+        self.fetch_live = fetch_live
+        self.collection_enabled = os.environ.get("EXPLORER_SINK", "local") != "off"
+
+    def prewarm(self):
+        """Fetch config + file sizes for the most downloaded LLMs, gently, so first results are exact."""
+        top = sorted((r for r in self.catalogue.records if r.is_llm), key=lambda r: -r.downloads)[:PREWARM_N]
+        for r in top:
+            try:
+                if self.details.peek(r.id) is None:
+                    self.details.get(r.id)
+                    time.sleep(0.25)
+            except Exception:
+                pass
+
+    def boot(self):
+        self.catalogue.load_offline()
+        if self.fetch_live:
+            def initial():
+                self.catalogue.refresh()
+                self.prewarm()
+
+            threading.Thread(target=initial, daemon=True, name="catalogue-initial").start()
+            self.catalogue.start_background_refresh()
+        self.sink.start()
+
+        def load_existing():
+            self.existing_rows = self.sink.read_existing()
+            self.stats.invalidate()
+
+        threading.Thread(target=load_existing, daemon=True, name="load-existing").start()
+
+
+def create_app(state: State | None = None) -> FastAPI:
+    st = state or State()
+
+    @asynccontextmanager
+    async def lifespan(app):
+        if state is None:
+            st.boot()
+        yield
+        st.sink.flush()  # don't lose buffered events on shutdown
+
+    app = FastAPI(title="MLX Model Explorer", version=APP_VERSION, lifespan=lifespan,
+                  docs_url=None, redoc_url=None, openapi_url=None)
+    app.state.st = st
+
+    @app.middleware("http")
+    async def guard(request: Request, call_next):
+        cl = request.headers.get("content-length")
+        if cl and cl.isdigit() and int(cl) > MAX_BODY:
+            return JSONResponse({"error": "payload too large"}, status_code=413)
+        resp = await call_next(request)
+        resp.headers["X-Content-Type-Options"] = "nosniff"
+        resp.headers["Referrer-Policy"] = "no-referrer"
+        resp.headers["Content-Security-Policy"] = (
+            "default-src 'self'; img-src 'self' data:; style-src 'self'; script-src 'self'; "
+            "connect-src 'self'; frame-ancestors https://huggingface.co https://*.hf.space 'self'"
+        )
+        return resp
+
+    @app.exception_handler(RequestValidationError)
+    async def _invalid(request, exc):
+        errs = [{"loc": [str(x) for x in e.get("loc", [])][-3:], "msg": str(e.get("msg"))[:160]}
+                for e in exc.errors()[:10]]
+        return JSONResponse({"error": "invalid request", "details": errs}, status_code=422)
+
+    def client_key(request: Request) -> str:
+        fwd = request.headers.get("x-forwarded-for", "")
+        return fwd.split(",")[0].strip() or (request.client.host if request.client else "unknown")
+
+    # ------------------------------------------------------------------ pages
+    @app.get("/", include_in_schema=False)
+    def index():
+        return FileResponse(STATIC / "index.html")
+
+    @app.get("/bench/mlx_explorer_bench.py", include_in_schema=False)
+    def bench_script():
+        return FileResponse(ROOT / "bench" / "mlx_explorer_bench.py", media_type="text/x-python")
+
+    @app.get("/stats", include_in_schema=False)
+    def stats_page():
+        return FileResponse(STATIC / "stats.html")
+
+    @app.get("/healthz")
+    def healthz():
+        cat = st.catalogue.status()
+        sink = st.sink.status()
+        ok = cat["models"] > 0
+        return JSONResponse({"ok": ok, "version": APP_VERSION, "catalogue": cat, "sink": sink},
+                            status_code=200 if ok else 503)
+
+    # ------------------------------------------------------------------ api
+    @app.get("/api/meta")
+    def meta(llm_only: bool = True):
+        return {
+            "version": APP_VERSION,
+            "engine": st.engine.version,
+            "families": st.catalogue.families(llm_only),
+            "sizes": PARAM_BUCKETS + ["MoE"],
+            "quantizations": [q for q in QUANT_BUCKETS if q != "unknown"] + ["unknown"],
+            "contexts": CONTEXTS,
+            "ram_classes": RAM_CLASSES,
+            "priorities": PRIORITIES,
+            "catalogue": st.catalogue.status(),
+            "collection_enabled": st.collection_enabled,
+        }
+
+    @app.post("/api/recommend")
+    def recommend(req: RecommendRequest):
+        if req.context not in CONTEXTS:
+            raise HTTPException(422, "context must be one of " + ",".join(map(str, CONTEXTS)))
+        q = Query(req.family or None, req.size or None, req.quant or None, req.context,
+                  req.ram_gb, req.ram_source, req.priority)
+        matches = st.catalogue.matching(q.family, q.size, q.quant, req.llm_only, req.search)
+        community = st.stats.community()
+        cached = {m.id: d for m in matches if (d := st.details.peek(m.id))}
+        norms = st.engine.norms(matches, q, cached)
+        prelim = sort_results(st.engine.score(matches, q, cached, community, norms), req.sort)
+        window = prelim[: max(DETAIL_TOP_N, req.offset + req.limit)]
+        details = st.details.get_many([s.model.id for s in window], timeout=6.0)
+        rescored = st.engine.score([s.model for s in window], q, details, community, norms)
+        final = sort_results(rescored, req.sort) + prelim[len(window):]
+        page = final[req.offset: req.offset + req.limit]
+        notices = []
+        if st.catalogue.degraded:
+            notices.append("Showing a cached copy of the model list; some model information isn't available.")
+        missing = sum(1 for s in page if not s.detail_loaded)
+        if missing:
+            notices.append(f"Some model information isn't available for {missing} result(s); "
+                           "their memory estimates use parameter counts only.")
+        return {
+            "total": len(matches),
+            "offset": req.offset,
+            "results": [s.to_dict() for s in page],
+            "notices": notices,
+            "engine": st.engine.version,
+        }
+
+    @app.get("/api/model/{model_id:path}")
+    def model(model_id: str, context: int = 8192, ram_gb: float | None = None,
+              priority: str = "balanced", ram_source: str | None = None):
+        rec = st.catalogue.by_id.get(model_id)
+        if rec is None:
+            raise HTTPException(404, "model not found in the mlx-community catalogue")
+        if context not in CONTEXTS:
+            context = 8192
+        if priority not in PRIORITIES:
+            priority = "balanced"
+        detail = st.details.get(model_id)
+        community = st.stats.community()
+        if ram_gb is not None and not (0 < ram_gb <= 1024):
+            ram_gb = None
+        q = Query(context=context, ram_gb=ram_gb, priority=priority,
+                  ram_source="confirmed" if ram_source == "confirmed" else ("estimated" if ram_gb else None))
+        scored = st.engine.score([rec], q, {model_id: detail}, community)[0]
+        by_context = []
+        for c in CONTEXTS:
+            mem, _ = st.engine.memory_for(rec, Query(context=c, ram_gb=ram_gb), detail)
+            by_context.append(mem.to_dict())
+        sibs = st.catalogue.siblings(rec)
+        sib_details = st.details.get_many([s.id for s in sibs], timeout=4.0)
+        sib_scored = st.engine.score(sibs, q, sib_details, community)
+        weight_files = [f for f in detail.files if f["path"].endswith((".safetensors", ".npz", ".gguf"))]
+        return {
+            **scored.to_dict(),
+            "files": detail.files[:60],
+            "file_count": len(detail.files),
+            "weight_files": len(weight_files),
+            "detail_error": detail.error,
+            "memory_by_context": by_context,
+            "siblings": [s.to_dict() for s in sib_scored],
+        }
+
+    @app.post("/api/events", status_code=202)
+    async def events(request: Request):
+        if not st.limiter.allow(client_key(request)):
+            return JSONResponse({"error": "rate limited"}, status_code=429)
+        raw = await request.body()
+        if len(raw) > MAX_BODY:  # also covers chunked uploads with no content-length
+            return JSONResponse({"error": "payload too large"}, status_code=413)
+        try:
+            import json as _json
+            body = _json.loads(raw)
+        except Exception:
+            return JSONResponse({"error": "invalid json"}, status_code=400)
+        try:
+            batch = EventBatch.model_validate(body)
+        except ValidationError as e:
+            errs = [{"loc": [str(x) for x in err.get("loc", [])][-3:], "msg": str(err.get("msg"))[:160]}
+                    for err in e.errors()[:10]]
+            return JSONResponse({"error": "invalid events", "details": errs}, status_code=422)
+        if not st.collection_enabled:
+            return {"accepted": 0}
+        rows = [to_row(ev, st.catalogue, APP_VERSION, st.engine.version) for ev in batch.events]
+        st.sink.add(rows)
+        st.stats.invalidate()
+        return {"accepted": len(rows), "flags": [r["suspicious_flags"] for r in rows]}
+
+    @app.get("/api/stats")
+    def stats():
+        return st.stats.stats()
+
+    app.mount("/static", StaticFiles(directory=STATIC), name="static")
+    return app
+
+
+app = create_app() if os.environ.get("EXPLORER_NO_AUTOAPP") != "1" else None

app/memory.py

@@ -0,0 +1,126 @@
+"""Conservative memory estimates. Every number here is an estimate, not a measurement."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+
+from .parsing import Arch
+
+GB = 1024**3
+
+RAM_CLASSES = [8, 16, 18, 24, 32, 36, 48, 64, 96, 128, 192, 256, 512]
+CONTEXTS = [4096, 8192, 16384, 32768, 65536, 131072, 262144]
+
+FIT_ORDER = ["Comfortable", "Likely", "Borderline", "Unlikely"]
+
+
+def bits_per_weight(bits: float | None, mode: str | None = None) -> float | None:
+    """Effective storage bits including per-group scales/biases."""
+    if bits is None:
+        return None
+    if bits >= 16:
+        return 16.0
+    if mode in ("mxfp4", "nvfp4", "mxfp8"):
+        return bits + 0.5  # one 8-bit scale per 16-32 weights
+    return bits + 0.5  # affine gs64: fp16 scale + bias per 64 weights
+
+
+def weights_bytes(
+    file_bytes: int | None, params: float | None, bits: float | None, mode: str | None = None
+) -> tuple[int | None, str]:
+    if isinstance(file_bytes, (int, float)) and file_bytes > 0:
+        return int(file_bytes), "files"
+    bpw = bits_per_weight(bits, mode)
+    if params and bpw:
+        return int(params * bpw / 8), "params"
+    return None, "unknown"
+
+
+def kv_cache_bytes(arch: Arch, context: int, kv_bytes_per_elem: float = 2.0) -> tuple[int | None, bool]:
+    """Returns (bytes, is_upper_bound). fp16 K and V for every cached token."""
+    if not arch.known:
+        return None, True
+    per_token_layer = 2 * arch.kv_heads * arch.head_dim * kv_bytes_per_elem
+    full = arch.full_attention_layers if arch.full_attention_layers is not None else arch.layers
+    total = full * context * per_token_layer
+    if arch.sliding_layers and arch.sliding_window:
+        total += arch.sliding_layers * min(context, arch.sliding_window) * per_token_layer
+    upper = arch.full_attention_layers is None
+    return int(total), upper
+
+
+def usable_gpu_bytes(ram_gb: float) -> int:
+    """macOS lets Metal wire roughly 2/3 of RAM on small machines and 3/4 on larger ones
+    by default (raisable with `sudo sysctl iogpu.wired_limit_mb`)."""
+    frac = 0.67 if ram_gb <= 36 else 0.75
+    return int(ram_gb * GB * frac)
+
+
+def overhead_bytes(weights: int | None) -> int:
+    return int(1.0 * GB + 0.05 * (weights or 0))
+
+
+def fit_class(total_bytes: int | None, ram_gb: float | None) -> str | None:
+    if total_bytes is None or not ram_gb:
+        return None
+    ratio = total_bytes / usable_gpu_bytes(ram_gb)
+    if ratio < 0.70:
+        return "Comfortable"
+    if ratio < 0.85:
+        return "Likely"
+    if ratio < 1.0:
+        return "Borderline"
+    return "Unlikely"
+
+
+@dataclass
+class MemoryEstimate:
+    weights_gb: float | None
+    weights_source: str
+    kv_gb: float | None
+    kv_rough: bool
+    overhead_gb: float | None
+    total_gb: float | None
+    context: int
+    fit: str | None
+    usable_gb: float | None
+    exceeds_model_context: bool
+    ratio: float | None = None  # total / usable GPU memory
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def estimate(
+    *,
+    params: float | None,
+    bits: float | None,
+    mode: str | None,
+    file_bytes: int | None,
+    arch: Arch,
+    context: int,
+    ram_gb: float | None,
+) -> MemoryEstimate:
+    w, wsrc = weights_bytes(file_bytes, params, bits, mode)
+    kv, upper = kv_cache_bytes(arch, context)
+    if kv is None and params:
+        # No architecture: rule of thumb between GQA (~0.02) and full multi-head (~0.07)
+        # models, in MB of fp16 KV per token per billion params.
+        kv = int(params / 1e9 * 0.05 * 1024**2 * context)
+        upper = True
+    oh = overhead_bytes(w) if w is not None else None
+    total = (w + (kv or 0) + oh) if w is not None else None
+    r = lambda b: None if b is None else round(b / GB, 2)
+    return MemoryEstimate(
+        weights_gb=r(w),
+        weights_source=wsrc,
+        kv_gb=r(kv),
+        kv_rough=upper,
+        overhead_gb=r(oh),
+        total_gb=r(total),
+        context=context,
+        fit=fit_class(total, ram_gb),
+        usable_gb=r(usable_gpu_bytes(ram_gb)) if ram_gb else None,
+        exceeds_model_context=bool(arch.max_context and context > arch.max_context),
+        ratio=round(total / usable_gpu_bytes(ram_gb), 3) if total is not None and ram_gb else None,
+    )

app/model_detail.py

@@ -0,0 +1,142 @@
+"""Per-model details (config.json + file sizes), fetched lazily and cached.
+
+Only models a user actually looks at, or the top of a result list, get fetched.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Callable
+
+import httpx
+
+from .catalogue import ROOT, _auth_headers, hf_endpoint
+
+log = logging.getLogger("explorer.detail")
+
+WEIGHT_SUFFIXES = (".safetensors", ".npz", ".gguf", ".bin")
+MAX_CONFIG_BYTES = 2_000_000
+
+
+@dataclass
+class ModelDetail:
+    id: str
+    config: dict | None
+    files: list[dict]  # [{path, size}]
+    weight_bytes: int | None
+    fetched_at: float
+    error: str | None = None
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d.pop("config", None)
+        return d
+
+
+Fetch = Callable[[str], ModelDetail]
+
+
+def fetch_detail(model_id: str, client: httpx.Client | None = None) -> ModelDetail:
+    own = client is None
+    client = client or httpx.Client(timeout=15.0, headers=_auth_headers(), follow_redirects=True)
+    errors = []
+    files: list[dict] = []
+    config = None
+    try:
+        try:
+            r = client.get(f"{hf_endpoint()}/api/models/{model_id}", params={"blobs": "true", "expand[]": "siblings"})
+            r.raise_for_status()
+            for s in r.json().get("siblings") or []:
+                if isinstance(s, dict) and isinstance(s.get("rfilename"), str):
+                    size = s.get("size") if isinstance(s.get("size"), int) else None
+                    files.append({"path": s["rfilename"][:200], "size": size})
+        except Exception as e:
+            errors.append(f"files: {type(e).__name__}")
+        try:
+            r = client.get(f"{hf_endpoint()}/{model_id}/resolve/main/config.json")
+            r.raise_for_status()
+            if len(r.content) <= MAX_CONFIG_BYTES:
+                parsed = r.json()
+                config = parsed if isinstance(parsed, dict) else None
+        except Exception as e:
+            errors.append(f"config: {type(e).__name__}")
+    finally:
+        if own:
+            client.close()
+    wb = sum(f["size"] for f in files if f["size"] and f["path"].endswith(WEIGHT_SUFFIXES)) or None
+    return ModelDetail(model_id, config, files[:500], wb, time.time(), "; ".join(errors) or None)
+
+
+class DetailCache:
+    def __init__(self, fetch: Fetch | None = None, cache_dir: Path | None = None,
+                 ttl: float = 24 * 3600, error_ttl: float = 600, workers: int = 12):
+        self._client = httpx.Client(timeout=15.0, headers=_auth_headers(), follow_redirects=True)
+        self._fetch = fetch or (lambda mid: fetch_detail(mid, self._client))
+        self._dir = (cache_dir or Path(os.environ.get("EXPLORER_CACHE", ROOT / ".cache"))) / "details"
+        self._mem: dict[str, ModelDetail] = {}
+        self._lock = threading.Lock()
+        self.ttl, self.error_ttl = ttl, error_ttl
+        self._pool = ThreadPoolExecutor(max_workers=workers, thread_name_prefix="detail")
+
+    def _path(self, mid: str) -> Path:
+        return self._dir / (hashlib.sha1(mid.encode()).hexdigest() + ".json")
+
+    def _fresh(self, d: ModelDetail) -> bool:
+        ttl = self.error_ttl if d.error else self.ttl
+        return time.time() - d.fetched_at < ttl
+
+    def peek(self, mid: str) -> ModelDetail | None:
+        with self._lock:
+            d = self._mem.get(mid)
+        if d and self._fresh(d):
+            return d
+        try:
+            raw = json.loads(self._path(mid).read_text())
+            d = ModelDetail(**raw)
+            if self._fresh(d):
+                with self._lock:
+                    self._mem[mid] = d
+                return d
+        except (OSError, ValueError, TypeError):
+            pass
+        return None
+
+    def get(self, mid: str) -> ModelDetail:
+        d = self.peek(mid)
+        if d:
+            return d
+        d = self._fetch(mid)
+        with self._lock:
+            self._mem[mid] = d
+        try:
+            self._dir.mkdir(parents=True, exist_ok=True)
+            self._path(mid).write_text(json.dumps(asdict(d)))
+        except OSError:
+            pass
+        return d
+
+    def get_many(self, ids: list[str], timeout: float = 8.0) -> dict[str, ModelDetail]:
+        """Fetch several in parallel; whatever isn't back within `timeout` is left out."""
+        out = {}
+        pending = {}
+        for mid in ids:
+            d = self.peek(mid)
+            if d:
+                out[mid] = d
+            else:
+                pending[mid] = self._pool.submit(self.get, mid)
+        deadline = time.time() + timeout
+        for mid, fut in pending.items():
+            try:
+                out[mid] = fut.result(timeout=max(0.0, deadline - time.time()))
+            except Exception:
+                pass
+        return out

app/parsing.py

@@ -0,0 +1,398 @@
+"""Turn raw Hugging Face model metadata into the fields the explorer filters on.
+
+Every function here takes untrusted, possibly incomplete metadata and returns a
+best guess plus where the guess came from. Nothing raises on junk input.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass, field, asdict
+from typing import Any
+
+# Canonical display names for family keywords. This is normalization, not a
+# closed list: a family we have never seen falls through to its leading token.
+FAMILY_ALIASES: dict[str, str] = {
+    "qwen": "Qwen", "qwq": "Qwen", "qwen2": "Qwen", "qwen3": "Qwen",
+    "gemma": "Gemma", "paligemma": "Gemma", "medgemma": "Gemma",
+    "translategemma": "Gemma", "codegemma": "Gemma", "shieldgemma": "Gemma",
+    "llama": "Llama", "codellama": "Llama", "tinyllama": "Llama",
+    "deepseek": "DeepSeek",
+    "mistral": "Mistral", "ministral": "Mistral", "mixtral": "Mistral",
+    "devstral": "Mistral", "magistral": "Mistral", "codestral": "Mistral",
+    "glm": "GLM", "chatglm": "GLM", "codegeex": "GLM",
+    "phi": "Phi",
+    "minimax": "MiniMax",
+    "kimi": "Kimi",
+    "granite": "Granite",
+    "falcon": "Falcon",
+    "lfm": "LFM",
+    "smollm": "SmolLM", "smolvlm": "SmolLM",
+    "olmo": "OLMo",
+    "nemotron": "Nemotron",
+    "minicpm": "MiniCPM",
+    "internvl": "InternVL",
+    "hunyuan": "Hunyuan",
+    "ernie": "ERNIE",
+    "gpt": "GPT-OSS",
+    "whisper": "Whisper",
+    "yi": "Yi",
+    "jp": "LLM-jp",
+    "exaone": "EXAONE",
+    "laguna": "Laguna",
+    "longcat": "LongCat",
+    "mamba": "Mamba",
+    "aya": "Aya",
+    "llava": "LLaVA",
+    "starcoder": "StarCoder",
+    "mimo": "MiMo",
+    "ling": "Ling",
+    "ring": "Ling",
+}
+
+# Keys distinctive enough to match inside a longer word ("ling" would catch "Starling").
+GLUE_SAFE = ["gemma", "llama", "qwen", "olmo", "mistral", "deepseek", "granite", "nemotron", "smolvlm", "minicpm"]
+
+# Tokens that are publishers or fine-tune brands rather than families; skip past
+# them and look at the next token (e.g. "Meta-Llama-3", "Josiefied-Qwen3").
+NON_FAMILY_PREFIXES = {
+    "meta", "nvidia", "microsoft", "google", "ibm", "apple", "amd", "open",
+    "josiefied", "josie", "dolphin", "hermes", "openhermes", "huihui", "abliterated",
+    "nous", "the", "mlx", "community", "unsloth", "llm", "ui", "c", "s", "hy",
+    # generic words that show up first in fine-tune names
+    "instruct", "thinking", "chat", "base", "preview", "mini", "big", "small", "tiny", "vl", "mt", "su",
+    "ai", "ii", "agents", "swe", "got", "unlimited", "model", "quantized", "uncensored", "v", "it", "ocr", "bf", "fp", "mlx",
+}
+
+LLM_PIPELINES = {"text-generation", "image-text-to-text", "any-to-any"}
+
+PARAM_BUCKETS = ["<3B", "3-8B", "8-15B", "15-35B", "35-70B", "70B+"]
+
+_TOKEN_SPLIT = re.compile(r"[-_. /]+")
+
+
+def _tokens(name: str) -> list[str]:
+    out = []
+    for tok in _TOKEN_SPLIT.split(name.lower()):
+        alpha = re.match(r"[a-z]+", tok)
+        if alpha:
+            out.append(alpha.group(0))
+    return out
+
+
+def base_model_of(tags: list[str] | None) -> str | None:
+    """First `base_model:org/name` tag (ignores `base_model:quantized:...` forms)."""
+    for t in tags or []:
+        if isinstance(t, str) and t.startswith("base_model:") and t.count(":") == 1:
+            return t.split(":", 1)[1]
+    return None
+
+
+def detect_family(model_id: str, tags: list[str] | None = None) -> str:
+    base = base_model_of(tags)
+    candidates = []
+    if base:
+        candidates.append(base.split("/")[-1])
+    candidates.append(model_id.split("/")[-1])
+    # Known keyword anywhere in the name wins (catches "Josiefied-Qwen3-8B").
+    for name in candidates:
+        for tok in _tokens(name):
+            if tok in FAMILY_ALIASES:
+                return FAMILY_ALIASES[tok]
+    # ...or glued onto another word ("FunctionGemma", "OLMoE", "SmolVLM").
+    for name in candidates:
+        for tok in _tokens(name):
+            for key in GLUE_SAFE:
+                if tok.startswith(key) or tok.endswith(key):
+                    return FAMILY_ALIASES[key]
+    # Otherwise the first non-publisher token, title-cased.
+    for name in candidates:
+        for tok in _tokens(name):
+            if tok not in NON_FAMILY_PREFIXES and len(tok) >= 2:
+                return tok[:1].upper() + tok[1:]
+    return "Other"
+
+
+# ---------------------------------------------------------------- parameters
+
+_PARAM_RE = re.compile(r"(?<![a-z0-9])(\d+(?:\.\d+)?)\s*([bm])(?![a-z])", re.I)
+_MOE_ACTIVE_RE = re.compile(r"(?<![a-z0-9])a(\d+(?:\.\d+)?)b(?![a-z])", re.I)
+_EXPERTS_RE = re.compile(r"(?<![a-z0-9])(\d+)x(\d+(?:\.\d+)?)b(?![a-z])", re.I)
+
+
+@dataclass
+class Params:
+    total: float | None  # parameters, not billions
+    active: float | None
+    moe: bool
+    source: str  # safetensors | name | config | unknown
+    name_total: float | None = None  # size claimed by the repo name, if any
+
+    @property
+    def partial(self) -> bool:
+        """The repo holds far fewer weights than its name claims (draft head, adapter, shard)."""
+        return bool(self.source == "safetensors" and self.name_total and self.total
+                    and self.total < 0.25 * self.name_total)
+
+
+def _unpacked_total(safetensors: dict, bits: float | None, name_total: float | None = None) -> tuple[float | None, str]:
+    """Hub parameter counts for MLX repos come in two styles.
+
+    Newer indexing reports unpacked weights (Qwen3-8B-4bit: U32=8.19B). Older indexing
+    counts packed U32 elements, so a 4-bit 7.8B model shows U32=0.98B plus F16=0.24B of
+    group scales/biases. In packed style the float count is about U32/bits (one scale
+    and one bias per 64 weights); in unpacked style floats are only norms, embeddings
+    or a vision tower, typically under a tenth of U32. When the repo name states a
+    size, whichever reading is closer to it wins.
+    """
+    total = safetensors.get("total")
+    if not isinstance(total, (int, float)) or total <= 0:
+        return None, "unknown"
+    by_dtype = safetensors.get("parameters")
+    packed = by_dtype.get("U32") if isinstance(by_dtype, dict) else None
+    if not isinstance(packed, (int, float)) or packed <= 0 or not bits or bits >= 16:
+        return float(total), "safetensors"
+    floats = sum(v for k, v in by_dtype.items() if k != "U32" and isinstance(v, (int, float)))
+    quantized = packed * 32 / bits
+    unpacked = quantized + max(0.0, floats - quantized / 32)  # minus one scale + one bias per 64 weights
+    if name_total:
+        closer = min((float(total), unpacked), key=lambda t: abs(math.log(t / name_total)))
+        return closer, "safetensors"
+    looks_packed = floats >= 0.9 * packed / bits
+    return (unpacked if looks_packed else float(total)), "safetensors"
+
+
+def detect_params(model_id: str, safetensors: Any = None, config: dict | None = None,
+                  bits: float | None = None) -> Params:
+    name = model_id.split("/")[-1]
+    moe = False
+    active = None
+    m = _MOE_ACTIVE_RE.search(name)
+    if m:
+        moe = True
+        active = float(m.group(1)) * 1e9
+    if _EXPERTS_RE.search(name):
+        moe = True
+    if isinstance(config, dict):
+        cfg = config.get("text_config") if isinstance(config.get("text_config"), dict) else config
+        for k in ("num_experts", "num_local_experts", "n_routed_experts", "moe_num_experts"):
+            v = cfg.get(k)
+            if isinstance(v, (int, float)) and v > 1:
+                moe = True
+
+    name_total = None
+    ex = _EXPERTS_RE.search(name)
+    if ex:
+        # "8x7B" is a rough upper bound; shared weights make the real total smaller.
+        name_total = float(ex.group(1)) * float(ex.group(2)) * 1e9
+        moe = True
+    else:
+        sizes = [float(num) * (1e9 if unit.lower() == "b" else 1e6) for num, unit in _PARAM_RE.findall(name)]
+        sizes = [x for x in sizes if x <= 3e12]  # "2026.27B" is a date next to a size, not a size
+        if sizes:
+            # The active-param token ("A3B") also matches; the total is the largest.
+            name_total = max(sizes)
+            if active is not None and name_total == active and len(sizes) == 1:
+                name_total = None
+
+    if isinstance(safetensors, dict):
+        t, src = _unpacked_total(safetensors, bits, name_total)
+        if t:
+            return Params(t, active, moe, src, name_total)
+    if name_total:
+        return Params(name_total, active, moe, "name", name_total)
+    return Params(None, active, moe, "unknown")
+
+
+def param_bucket(total: float | None) -> str | None:
+    if not total:
+        return None
+    b = total / 1e9
+    if b < 3:
+        return "<3B"
+    if b < 8:
+        return "3-8B"
+    if b < 15:
+        return "8-15B"
+    if b < 35:
+        return "15-35B"
+    if b < 70:
+        return "35-70B"
+    return "70B+"
+
+
+# -------------------------------------------------------------- quantization
+
+@dataclass
+class Quant:
+    bits: float | None  # nominal bits for the bulk of the weights (16 = unquantized)
+    mode: str | None  # affine | mxfp4 | nvfp4 | mxfp8 | dwq | float | None
+    mixed: bool
+    source: str  # tags | config | name | unknown
+    label: str = field(default="")
+
+    def __post_init__(self):
+        if not self.label:
+            self.label = quant_label(self.bits, self.mixed)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+QUANT_BUCKETS = ["2-bit", "3-bit", "4-bit", "5-bit", "6-bit", "8-bit", "16-bit", "unknown"]
+
+
+def quant_label(bits: float | None, mixed: bool = False) -> str:
+    if bits is None:
+        return "unknown"
+    if bits >= 16:
+        return "16-bit"
+    b = int(round(bits))
+    label = f"{b}-bit" if b in (2, 3, 4, 5, 6, 8) else ("unknown" if b < 2 else f"{b}-bit")
+    return label + (" mixed" if mixed and label != "unknown" else "")
+
+
+def quant_bucket(q: Quant) -> str:
+    return q.label.replace(" mixed", "")
+
+
+_NAME_BITS = [
+    (re.compile(r"(?<![a-z0-9])(?:mx|nv)fp4(?![a-z0-9])", re.I), 4, None),
+    (re.compile(r"(?<![a-z0-9])mxfp8(?![a-z0-9])", re.I), 8, "mxfp8"),
+    (re.compile(r"(?<![a-z0-9])(?:qnt)?(\d)[-_]?bits?(?![a-z0-9])", re.I), None, None),
+    (re.compile(r"(?<![a-z0-9])q(\d)(?![a-z0-9])", re.I), None, None),
+    (re.compile(r"(?<![a-z0-9])(?:bf16|fp16|f16|float16|bfloat16)(?![a-z0-9])", re.I), 16, "float"),
+]
+
+
+def _bits_from_config(config: dict | None) -> tuple[float | None, str | None, bool]:
+    if not isinstance(config, dict):
+        return None, None, False
+    q = None
+    for holder in (config, config.get("text_config") if isinstance(config.get("text_config"), dict) else None):
+        if not holder:
+            continue
+        q = holder.get("quantization") or holder.get("quantization_config")
+        if isinstance(q, dict):
+            break
+        q = None
+    if not isinstance(q, dict):
+        return None, None, False
+    bits = q.get("bits")
+    mode = q.get("mode") if isinstance(q.get("mode"), str) else None
+    per_layer = [v for v in q.values() if isinstance(v, dict) and "bits" in v]
+    layer_bits = {v.get("bits") for v in per_layer if isinstance(v.get("bits"), (int, float))}
+    mixed = bool(layer_bits and (len(layer_bits | ({bits} if isinstance(bits, (int, float)) else set())) > 1))
+    if not isinstance(bits, (int, float)):
+        bits = min(layer_bits) if layer_bits else None
+    return (float(bits) if bits else None), (mode or "affine"), mixed
+
+
+def detect_quant(model_id: str, tags: list[str] | None = None, config: dict | None = None) -> Quant:
+    name = model_id.split("/")[-1]
+    tags = [t for t in (tags or []) if isinstance(t, str)]
+    lname = name.lower()
+    name_mode = None
+    if "dwq" in lname:
+        name_mode = "dwq"
+    elif "nvfp4" in lname:
+        name_mode = "nvfp4"
+    elif "mxfp4" in lname:
+        name_mode = "mxfp4"
+
+    # 1. config.json is the most direct evidence when we have it.
+    cbits, cmode, cmixed = _bits_from_config(config)
+    if cbits:
+        return Quant(cbits, name_mode or cmode, cmixed, "config")
+    if isinstance(config, dict) and (config.get("model_type") or config.get("architectures")):
+        holders = [config] + [v for v in config.values() if isinstance(v, dict)]
+        if not any(k in h for h in holders for k in ("quantization", "quantization_config")):
+            # A real MLX config with no quantization block at all means unquantized weights.
+            return Quant(16.0, "float", False, "config")
+        # A quantization block in a format we don't parse: fall through to tags and name.
+
+    # 2. Hub tags: "4-bit" is the canonical form; "4bit"/"8bit" pairs signal mixed maps.
+    tag_bits = sorted({int(m.group(1)) for t in tags for m in [re.fullmatch(r"(\d)-bit", t)] if m})
+    loose_bits = {int(m.group(1)) for t in tags for m in [re.fullmatch(r"(\d)bit", t)] if m}
+    if tag_bits:
+        bits = tag_bits[0]
+        mixed = len(set(tag_bits) | loose_bits) > 1
+        return Quant(float(bits), name_mode or "affine", mixed, "tags")
+
+    # 3. Name conventions.
+    for rx, fixed, mode in _NAME_BITS:
+        m = rx.search(name)
+        if m:
+            bits = fixed if fixed is not None else int(m.group(1))
+            if bits in (2, 3, 4, 5, 6, 8, 16):
+                return Quant(float(bits), name_mode or mode or ("float" if bits == 16 else "affine"), False, "name")
+    if loose_bits:
+        b = sorted(loose_bits)
+        return Quant(float(b[0]), name_mode or "affine", len(b) > 1, "tags")
+    return Quant(None, name_mode, False, "unknown")
+
+
+# ------------------------------------------------------------ architecture
+
+@dataclass
+class Arch:
+    layers: int | None
+    full_attention_layers: int | None
+    sliding_layers: int
+    kv_heads: int | None
+    head_dim: int | None
+    sliding_window: int | None
+    max_context: int | None
+    known: bool
+
+
+def _int(v: Any) -> int | None:
+    if isinstance(v, bool):
+        return None
+    if isinstance(v, (int, float)) and v > 0:
+        return int(v)
+    return None
+
+
+def detect_arch(config: dict | None) -> Arch:
+    """Pull the fields a KV-cache estimate needs. Missing -> known=False."""
+    if not isinstance(config, dict):
+        return Arch(None, None, 0, None, None, None, None, False)
+    cfg = config.get("text_config") if isinstance(config.get("text_config"), dict) else config
+    layers = _int(cfg.get("num_hidden_layers") or cfg.get("n_layer") or cfg.get("num_layers"))
+    heads = _int(cfg.get("num_attention_heads") or cfg.get("n_head"))
+    kv = _int(cfg.get("num_key_value_heads") or cfg.get("n_head_kv")) or heads
+    hidden = _int(cfg.get("hidden_size") or cfg.get("n_embd"))
+    head_dim = _int(cfg.get("head_dim")) or (hidden // heads if hidden and heads else None)
+    # MLA (DeepSeek-style) caches a compressed latent instead of full K/V.
+    kv_lora = _int(cfg.get("kv_lora_rank"))
+    if kv_lora:
+        rope_dim = _int(cfg.get("qk_rope_head_dim")) or 0
+        kv, head_dim = 1, (kv_lora + rope_dim) // 2 or None
+    sliding = _int(cfg.get("sliding_window")) if cfg.get("use_sliding_window", True) is not False else None
+    max_ctx = _int(cfg.get("max_position_embeddings") or cfg.get("max_seq_len") or cfg.get("seq_length"))
+
+    full = layers
+    sliding_layers = 0
+    layer_types = cfg.get("layer_types")
+    if isinstance(layer_types, list) and layer_types and all(isinstance(t, str) for t in layer_types):
+        full = sum(1 for t in layer_types if t in ("full_attention", "attention", "global_attention"))
+        sliding_layers = sum(1 for t in layer_types if "sliding" in t)
+        if not sliding_layers:
+            sliding = None
+    else:
+        interval = _int(cfg.get("full_attention_interval"))
+        if layers and interval:
+            full = max(1, layers // interval)  # the rest are linear-attention layers
+            sliding = None
+        elif sliding and layers and _int(cfg.get("sliding_window_pattern")):
+            # Gemma-style: one global layer every `pattern` layers.
+            full = max(1, layers // _int(cfg.get("sliding_window_pattern")))
+            sliding_layers = layers - full
+        # A bare sliding_window with no layer map: keep every layer as full
+        # attention so the estimate stays an upper bound.
+    if not sliding:
+        sliding_layers = 0
+    known = bool(layers and kv and head_dim)
+    return Arch(layers, full, sliding_layers, kv, head_dim, sliding, max_ctx, known)

app/ratelimit.py

@@ -0,0 +1,45 @@
+"""In-memory token bucket.
+
+Clients are keyed by a salted hash of their address. The salt is random, lives
+only in this process, and rotates hourly, so the key can't be reversed, joined
+across restarts, or stored. Nothing here is logged or persisted.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+import threading
+import time
+
+
+class RateLimiter:
+    def __init__(self, rate_per_minute: float = 60, burst: int = 30, rotate_seconds: float = 3600):
+        self.rate = rate_per_minute / 60.0
+        self.burst = burst
+        self.rotate_seconds = rotate_seconds
+        self._salt = secrets.token_bytes(16)
+        self._salt_at = time.time()
+        self._buckets: dict[str, tuple[float, float]] = {}
+        self._lock = threading.Lock()
+
+    def _key(self, client: str) -> str:
+        if time.time() - self._salt_at > self.rotate_seconds:
+            self._salt = secrets.token_bytes(16)
+            self._salt_at = time.time()
+            self._buckets.clear()
+        return hashlib.blake2b(client.encode(), key=self._salt, digest_size=12).hexdigest()
+
+    def allow(self, client: str, cost: float = 1.0) -> bool:
+        now = time.time()
+        with self._lock:
+            key = self._key(client)
+            tokens, last = self._buckets.get(key, (float(self.burst), now))
+            tokens = min(self.burst, tokens + (now - last) * self.rate)
+            if tokens < cost:
+                self._buckets[key] = (tokens, now)
+                return False
+            self._buckets[key] = (tokens - cost, now)
+            if len(self._buckets) > 50_000:
+                self._buckets.clear()
+            return True

app/recommend.py

@@ -0,0 +1,304 @@
+"""Recommendation scoring.
+
+The engine only looks at measurable properties: estimated memory fit, bit width,
+context, size, Hub popularity, recency and community data. It never looks at a
+model's name, uploader or brand. `tests/test_recommend.py` enforces that.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Protocol
+
+from .catalogue import ModelRecord
+from .memory import MemoryEstimate, estimate
+from .parsing import Arch, detect_arch, detect_quant
+from .model_detail import ModelDetail
+
+PRIORITIES = ["balanced", "quality", "speed", "memory", "long_context"]
+
+# How much each priority cares about each component. Rows sum to 1.
+WEIGHTS: dict[str, dict[str, float]] = {
+    "balanced":     {"fit": 0.30, "quant": 0.15, "context": 0.10, "capacity": 0.15, "popularity": 0.20, "recency": 0.05, "community": 0.05},
+    "quality":      {"fit": 0.25, "quant": 0.25, "context": 0.05, "capacity": 0.25, "popularity": 0.12, "recency": 0.03, "community": 0.05},
+    "speed":        {"fit": 0.35, "quant": 0.25, "context": 0.05, "capacity": 0.00, "popularity": 0.15, "recency": 0.05, "community": 0.15},
+    "memory":       {"fit": 0.35, "quant": 0.35, "context": 0.05, "capacity": 0.00, "popularity": 0.15, "recency": 0.05, "community": 0.05},
+    "long_context": {"fit": 0.25, "quant": 0.15, "context": 0.30, "capacity": 0.05, "popularity": 0.15, "recency": 0.05, "community": 0.05},
+}
+
+# Preference over nominal bit width per priority (1 = most preferred).
+QUANT_PREF: dict[str, dict[int, float]] = {
+    "quality":      {16: 1.0, 8: 0.95, 6: 0.85, 5: 0.75, 4: 0.6, 3: 0.35, 2: 0.15},
+    "balanced":     {4: 1.0, 5: 0.95, 6: 0.85, 8: 0.75, 3: 0.55, 16: 0.45, 2: 0.25},
+    "speed":        {4: 1.0, 3: 0.85, 5: 0.85, 6: 0.7, 2: 0.6, 8: 0.55, 16: 0.25},
+    "memory":       {2: 1.0, 3: 0.9, 4: 0.8, 5: 0.6, 6: 0.5, 8: 0.3, 16: 0.1},
+    "long_context": {4: 1.0, 5: 0.9, 6: 0.8, 3: 0.7, 8: 0.65, 2: 0.4, 16: 0.3},
+}
+
+def fit_score(ratio: float) -> float:
+    """Continuous version of the fit classes, so 'a bit too big' beats 'far too big'."""
+    if ratio < 0.70:
+        return 1.0
+    if ratio < 0.85:
+        return 1.0 - (ratio - 0.70) / 0.15 * 0.2
+    if ratio < 1.0:
+        return 0.8 - (ratio - 0.85) / 0.15 * 0.4
+    return max(0.0, 0.4 * (1 - (ratio - 1.0)))
+
+
+@dataclass
+class Query:
+    family: str | None = None
+    size: str | None = None
+    quant: str | None = None
+    context: int = 8192
+    ram_gb: float | None = None
+    ram_source: str | None = None  # confirmed | estimated | None
+    priority: str = "balanced"
+
+
+@dataclass
+class CommunitySignal:
+    feedback_count: int = 0
+    positive_share: float | None = None
+    benchmark_count: int = 0
+    median_generation_tps: float | None = None
+
+
+@dataclass
+class Scored:
+    model: ModelRecord
+    score: float
+    components: dict[str, float]
+    reasons: list[str]
+    memory: MemoryEstimate
+    detail_loaded: bool
+    community: CommunitySignal = field(default_factory=CommunitySignal)
+    quant: dict = field(default_factory=dict)  # effective quantization (config beats name/tags)
+
+    def to_dict(self) -> dict:
+        return {
+            "model": self.model.public(),
+            "score": round(self.score, 1),
+            "components": {k: round(v, 3) for k, v in self.components.items()},
+            "reasons": self.reasons,
+            "memory": self.memory.to_dict(),
+            "detail_loaded": self.detail_loaded,
+            "quant": self.quant or self.model.quant,
+            "community": self.community.__dict__,
+        }
+
+
+class RecommendationEngine(Protocol):
+    version: str
+
+    def score(self, models: list[ModelRecord], query: Query,
+              details: dict[str, ModelDetail], community: dict[str, CommunitySignal]) -> list[Scored]: ...
+
+
+def _months_since(iso: str | None, now: datetime) -> float | None:
+    if not iso:
+        return None
+    try:
+        dt = datetime.fromisoformat(iso.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return max(0.0, (now - dt).days / 30.4)
+
+
+def _fmt_ctx(n: int) -> str:
+    return f"{n // 1024}k" if n >= 1024 else str(n)
+
+
+def _fmt_downloads(n: int) -> str:
+    if n >= 1_000_000:
+        return f"{n / 1e6:.1f}M"
+    if n >= 1000:
+        return f"{n / 1e3:.0f}k"
+    return str(n)
+
+
+class HeuristicEngine:
+    version = "heuristic-v1"
+
+    def __init__(self, now: datetime | None = None):
+        self._now = now
+
+    def memory_for(self, m: ModelRecord, query: Query, detail: ModelDetail | None) -> tuple[MemoryEstimate, dict]:
+        quant = m.quant
+        arch = Arch(None, None, 0, None, None, None, None, False)
+        file_bytes = None
+        if detail:
+            arch = detect_arch(detail.config)
+            file_bytes = detail.weight_bytes
+            if detail.config:
+                q = detect_quant(m.id, m.tags, detail.config)
+                if q.bits is not None:
+                    quant = q.to_dict()
+        mem = estimate(params=m.params, bits=quant["bits"], mode=quant["mode"], file_bytes=file_bytes,
+                       arch=arch, context=query.context, ram_gb=query.ram_gb)
+        return mem, quant
+
+    def norms(self, models, query, details=None) -> dict:
+        """Set-wide reference values, computed once over ALL matches so a model's score
+        doesn't depend on which page of results it is rescored in."""
+        details = details or {}
+        fitting = []
+        for m in models:
+            if not m.params or m.partial:
+                continue
+            if query.ram_gb is None:
+                fitting.append(m.params)
+                continue
+            mem, _ = self.memory_for(m, query, details.get(m.id))
+            if mem.fit in ("Comfortable", "Likely"):
+                fitting.append(m.params)
+        return {
+            "max_downloads": max((m.downloads for m in models), default=0),
+            "max_likes": max((m.likes for m in models), default=0),
+            "max_fitting_params": max(fitting, default=0),
+        }
+
+    def score(self, models, query, details=None, community=None, norms=None) -> list[Scored]:
+        details = details or {}
+        community = community or {}
+        now = self._now or datetime.now(timezone.utc)
+        priority = query.priority if query.priority in WEIGHTS else "balanced"
+        weights = WEIGHTS[priority]
+        norms = norms or self.norms(models, query, details)
+        max_dl, max_likes = norms["max_downloads"], norms["max_likes"]
+        max_fit_params = norms["max_fitting_params"]
+        out = []
+        for m in models:
+            detail = details.get(m.id)
+            mem, quant = self.memory_for(m, query, detail)
+            comm = community.get(m.id) or CommunitySignal()
+            comp: dict[str, float] = {}
+            reasons: list[str] = []
+
+            # Hardware fit
+            if mem.total_gb is None:
+                comp["fit"] = 0.5
+                reasons.append("Memory need unknown: some model information isn't available.")
+            elif query.ram_gb is None:
+                comp["fit"] = 0.6
+                reasons.append(f"Needs roughly {mem.total_gb:.1f} GB at {_fmt_ctx(query.context)} context (estimate). "
+                               "Set your memory to check fit.")
+            else:
+                comp["fit"] = fit_score(mem.ratio)
+                src = "confirmed" if query.ram_source == "confirmed" else "estimated"
+                reasons.append(f"{mem.fit} fit: ~{mem.total_gb:.1f} GB needed vs ~{mem.usable_gb:.0f} GB "
+                               f"GPU-usable on a {query.ram_gb:g} GB Mac ({src}).")
+
+            # Quantization vs priority
+            bits = quant["bits"]
+            if bits is None:
+                comp["quant"] = 0.4
+                reasons.append("Quantization unknown.")
+            else:
+                key = 16 if bits >= 16 else int(round(bits))
+                comp["quant"] = QUANT_PREF[priority].get(key, 0.4)
+                if query.ram_gb and mem.fit == "Unlikely":
+                    comp["quant"] *= 0.25  # bit-width preference is moot if it won't load
+                label = quant.get("label") or f"{key}-bit"
+                if quant is not m.quant and m.quant.get("bits") and quant.get("bits") != m.quant.get("bits"):
+                    reasons.append(f"Its config.json says {label}, although the name or tags say {m.quant['label']}.")
+                note = {
+                    "quality": "more bits keep more of the original model's quality",
+                    "memory": "fewer bits mean a smaller download and less memory",
+                    "speed": "fewer bits usually decode faster on unified memory, but speed depends on the model and Mac",
+                    "long_context": "leaves more memory for the KV cache",
+                    "balanced": "4 to 6 bits is the usual quality/memory middle ground",
+                }[priority]
+                reasons.append(f"{label}: {note}.")
+
+            # Context
+            if mem.exceeds_model_context:
+                comp["context"] = 0.0
+                reasons.append(f"The model's config lists a shorter maximum context than {_fmt_ctx(query.context)}.")
+            elif mem.total_gb is not None and mem.kv_gb is not None:
+                if query.ram_gb:
+                    headroom = 1 - mem.total_gb / max(mem.usable_gb or 1, 0.1)
+                    comp["context"] = max(0.0, min(1.0, 0.5 + headroom))
+                else:
+                    share = mem.kv_gb / max(mem.total_gb, 0.01)
+                    comp["context"] = max(0.0, 1 - share)
+                bound = " (rough, architecture unknown)" if mem.kv_rough else ""
+                reasons.append(f"KV cache at {_fmt_ctx(query.context)}: ~{mem.kv_gb:.1f} GB{bound}.")
+            else:
+                comp["context"] = 0.5
+
+            # Capacity: among models that fit, more parameters usually means a more capable model
+            if query.ram_gb is None:
+                comp["capacity"] = 0.5  # without a memory budget, "bigger" would just mean "won't fit"
+            elif m.params and max_fit_params and mem.fit not in ("Borderline", "Unlikely"):
+                comp["capacity"] = min(1.0, math.log10(1 + m.params / 1e8) / math.log10(1 + max_fit_params / 1e8))
+                if weights["capacity"] and m.params < 0.5 * max_fit_params:
+                    reasons.append(f"{m.params / 1e9:.1f}B parameters; models up to {max_fit_params / 1e9:.0f}B "
+                                   f"in these results fit your Mac, and larger models are usually more capable.")
+            elif m.params and max_fit_params:
+                comp["capacity"] = 0.0
+            else:
+                comp["capacity"] = 0.5
+
+            # Popularity: downloads and likes, log-scaled against the best in this result set
+            dl = math.log10(m.downloads + 1) / math.log10(max_dl + 1) if max_dl > 0 else 0.0
+            lk = math.log10(m.likes + 1) / math.log10(max_likes + 1) if max_likes > 0 else 0.0
+            comp["popularity"] = 0.7 * dl + 0.3 * lk
+            if m.downloads:
+                reasons.append(f"{_fmt_downloads(m.downloads)} Hugging Face downloads.")
+
+            # Recency: half-life of a year
+            months = _months_since(m.modified, now)
+            comp["recency"] = 0.5 ** (months / 12) if months is not None else 0.3
+
+            # Community data (zero until people contribute)
+            if comm.benchmark_count or comm.feedback_count:
+                c = min(1.0, math.log10(1 + comm.benchmark_count + comm.feedback_count) / 2)
+                if comm.positive_share is not None:
+                    c = 0.5 * c + 0.5 * comm.positive_share
+                comp["community"] = c
+                bits_ = []
+                if comm.benchmark_count:
+                    tps = f", median {comm.median_generation_tps:.0f} tok/s" if comm.median_generation_tps else ""
+                    bits_.append(f"{comm.benchmark_count} MLX benchmark(s){tps}")
+                if comm.feedback_count:
+                    bits_.append(f"{comm.feedback_count} community report(s)")
+                reasons.append("Community: " + "; ".join(bits_) + ".")
+            else:
+                comp["community"] = 0.0
+
+            score = 100 * sum(weights[k] * comp[k] for k in weights)
+            if m.partial:
+                score *= 0.6
+                reasons.insert(0, "This repo holds far fewer weights than its name suggests. It may be an add-on "
+                                  "(draft head, adapter or partial upload) rather than a complete model.")
+            if query.ram_gb and mem.fit == "Unlikely":
+                score *= 0.5  # never recommend something that likely won't load over something that will
+            out.append(Scored(m, score, comp, reasons, mem, detail is not None and detail.config is not None, comm, quant))
+        return out
+
+
+def sort_results(scored: list[Scored], sort: str) -> list[Scored]:
+    if sort == "popular":
+        key = lambda s: (-s.model.downloads, s.model.id)
+    elif sort == "recent":
+        key = lambda s: (-(_ts(s.model.modified)), s.model.id)
+    elif sort == "community":
+        key = lambda s: (-(s.community.benchmark_count + s.community.feedback_count), -s.score, s.model.id)
+    elif sort == "all":
+        key = lambda s: s.model.id.lower()
+    else:
+        key = lambda s: (-s.score, -s.model.downloads, s.model.id)
+    return sorted(scored, key=key)
+
+
+def _ts(iso: str | None) -> float:
+    if not iso:
+        return 0.0
+    try:
+        return datetime.fromisoformat(iso.replace("Z", "+00:00")).timestamp()
+    except ValueError:
+        return 0.0

app/sink.py

@@ -0,0 +1,255 @@
+"""Append-only event storage.
+
+Rows are buffered in memory and mirrored to a local spool file. On each flush the
+buffer becomes ONE new Parquet shard (one Hub commit), so a busy day costs at most
+~144 commits at the default 10-minute interval. Existing shards are never
+rewritten. If an upload fails, the rows stay spooled and go out with the next flush.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import logging
+import os
+import threading
+import time
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+
+from .events import COLUMNS
+
+log = logging.getLogger("explorer.sink")
+
+_PA = {"string": pa.string(), "int": pa.int64(), "float": pa.float64(), "bool": pa.bool_(),
+       "list": pa.list_(pa.string())}
+SCHEMA = pa.schema([(k, _PA[t]) for k, t in COLUMNS.items()])
+MAX_BUFFER = 100_000
+
+
+def rows_to_parquet_bytes(rows: list[dict]) -> bytes:
+    cols = {k: [r.get(k) for r in rows] for k in COLUMNS}
+    table = pa.Table.from_pydict(cols, schema=SCHEMA)
+    buf = io.BytesIO()
+    pq.write_table(table, buf, compression="zstd")
+    return buf.getvalue()
+
+
+def shard_path(prefix: str, instance: str, when: datetime | None = None) -> str:
+    when = when or datetime.now(timezone.utc)
+    return f"{prefix.strip('/')}/{when:%Y/%m/%d}/{instance}-{when:%Y%m%dT%H%M%S}-{uuid.uuid4().hex[:6]}.parquet"
+
+
+class EventSink:
+    kind = "base"
+
+    def __init__(self, spool_dir: Path, flush_seconds: float = 600, prefix: str = "data/events"):
+        self.prefix = prefix
+        self.flush_seconds = flush_seconds
+        self.instance = uuid.uuid4().hex[:8]
+        self._spool = spool_dir / f"spool-{self.kind}.jsonl"
+        self._buf: list[dict] = []
+        self._lock = threading.Lock()
+        self._flush_lock = threading.Lock()
+        self.dropped = 0
+        self.written_rows = 0
+        self.written_shards = 0
+        self.last_flush_at: float | None = None
+        self.last_error: str | None = None
+        self.consecutive_failures = 0
+        self.all_rows: list[dict] = []  # everything accepted this process (for live stats)
+        spool_dir.mkdir(parents=True, exist_ok=True)
+        self._recover_spool()
+
+    def _recover_spool(self):
+        try:
+            with open(self._spool) as f:
+                for line in f:
+                    try:
+                        self._buf.append(json.loads(line))
+                    except ValueError:
+                        continue
+            if self._buf:
+                log.info("recovered %d spooled rows", len(self._buf))
+        except FileNotFoundError:
+            pass
+
+    def add(self, rows: list[dict]) -> None:
+        with self._lock:
+            overflow = len(self._buf) + len(rows) - MAX_BUFFER
+            if overflow > 0:
+                self._buf = self._buf[overflow:]
+                self.dropped += overflow
+            self._buf.extend(rows)
+            self.all_rows.extend(rows)
+            if len(self.all_rows) > MAX_BUFFER:
+                self.all_rows = self.all_rows[-MAX_BUFFER:]
+            try:
+                with open(self._spool, "a") as f:
+                    for r in rows:
+                        f.write(json.dumps(r) + "\n")
+            except OSError:
+                log.warning("spool write failed", exc_info=True)
+
+    @property
+    def pending(self) -> int:
+        return len(self._buf)
+
+    def flush(self) -> bool:
+        """Write everything buffered as one shard. Returns True if nothing is left pending."""
+        with self._flush_lock:
+            with self._lock:
+                rows = list(self._buf)
+            if not rows:
+                return True
+            path = shard_path(self.prefix, self.instance)
+            try:
+                self._write_shard(path, rows_to_parquet_bytes(rows))
+            except Exception as e:
+                self.consecutive_failures += 1
+                self.last_error = f"{type(e).__name__}: {str(e)[:200]}"
+                log.warning("flush failed (%d pending): %s", len(rows), self.last_error)
+                return False
+            with self._lock:
+                self._buf = self._buf[len(rows):]
+                self._rewrite_spool()
+            self.written_rows += len(rows)
+            self.written_shards += 1
+            self.last_flush_at = time.time()
+            self.last_error = None
+            self.consecutive_failures = 0
+            return not self._buf
+
+    def _rewrite_spool(self):
+        try:
+            tmp = self._spool.with_suffix(".tmp")
+            with open(tmp, "w") as f:
+                for r in self._buf:
+                    f.write(json.dumps(r) + "\n")
+            tmp.replace(self._spool)
+        except OSError:
+            log.warning("spool rewrite failed", exc_info=True)
+
+    def _write_shard(self, path: str, data: bytes) -> None:
+        raise NotImplementedError
+
+    def read_existing(self) -> list[dict]:
+        return []
+
+    def start(self) -> threading.Thread:
+        def loop():
+            while True:
+                # back off when the Hub is failing: 1x, 2x, 4x... capped at 1h
+                wait = min(self.flush_seconds * (2 ** min(self.consecutive_failures, 3)), 3600)
+                time.sleep(wait)
+                self.flush()
+
+        t = threading.Thread(target=loop, daemon=True, name=f"sink-{self.kind}")
+        t.start()
+        return t
+
+    def status(self) -> dict:
+        return {
+            "kind": self.kind,
+            "pending": self.pending,
+            "written_rows": self.written_rows,
+            "written_shards": self.written_shards,
+            "dropped": self.dropped,
+            "last_flush_at": self.last_flush_at,
+            "last_error": self.last_error,
+            "healthy": self.consecutive_failures == 0,
+        }
+
+
+class LocalParquetSink(EventSink):
+    kind = "local"
+
+    def __init__(self, root: Path, **kw):
+        self.root = root
+        super().__init__(spool_dir=root / "_spool", **kw)
+
+    def _write_shard(self, path: str, data: bytes) -> None:
+        target = self.root / path
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if target.exists():
+            raise FileExistsError(path)
+        tmp = target.with_suffix(".tmp")
+        tmp.write_bytes(data)
+        tmp.replace(target)
+
+    def read_existing(self) -> list[dict]:
+        rows = []
+        for p in sorted((self.root / self.prefix).rglob("*.parquet")):
+            try:
+                rows.extend(pq.read_table(p).to_pylist())
+            except Exception:
+                log.warning("unreadable shard %s", p)
+        return rows
+
+
+class HubParquetSink(EventSink):
+    kind = "hub"
+
+    def __init__(self, repo_id: str, token: str | None, spool_dir: Path, api=None, **kw):
+        from huggingface_hub import HfApi
+
+        self.repo_id = repo_id
+        self.api = api or HfApi(token=token)
+        super().__init__(spool_dir=spool_dir, **kw)
+
+    def _write_shard(self, path: str, data: bytes) -> None:
+        from huggingface_hub import CommitOperationAdd
+
+        self.api.create_commit(
+            repo_id=self.repo_id,
+            repo_type="dataset",
+            operations=[CommitOperationAdd(path_in_repo=path, path_or_fileobj=data)],
+            commit_message=f"Add {path.rsplit('/', 1)[-1]}",
+        )
+
+    def read_existing(self) -> list[dict]:
+        from huggingface_hub import hf_hub_download
+
+        rows = []
+        try:
+            files = [f for f in self.api.list_repo_files(self.repo_id, repo_type="dataset")
+                     if f.startswith(self.prefix.strip("/") + "/") and f.endswith(".parquet")]
+        except Exception as e:
+            self.last_error = f"read: {type(e).__name__}"
+            return rows
+        for f in files:
+            try:
+                local = hf_hub_download(self.repo_id, f, repo_type="dataset", token=self.api.token)
+                rows.extend(pq.read_table(local).to_pylist())
+            except Exception:
+                log.warning("unreadable shard %s", f)
+        return rows
+
+
+class NullSink(EventSink):
+    """Used when collection is disabled server-side: accepts nothing, stores nothing."""
+
+    kind = "null"
+
+    def add(self, rows):
+        pass
+
+    def _write_shard(self, path, data):
+        pass
+
+
+def make_sink(base_dir: Path) -> EventSink:
+    mode = os.environ.get("EXPLORER_SINK", "local")
+    flush = float(os.environ.get("EXPLORER_FLUSH_SECONDS", "600"))
+    prefix = os.environ.get("EXPLORER_DATA_PREFIX", "data/events")
+    if mode == "hub":
+        repo = os.environ.get("DATASET_REPO", "mlx-community/mlx-model-explorer-data")
+        return HubParquetSink(repo, os.environ.get("HF_TOKEN"), spool_dir=base_dir / "_spool",
+                              flush_seconds=flush, prefix=prefix)
+    if mode == "off":
+        return NullSink(spool_dir=base_dir / "_spool_null", flush_seconds=flush, prefix=prefix)
+    return LocalParquetSink(base_dir / "local_dataset", flush_seconds=flush, prefix=prefix)

app/stats.py

@@ -0,0 +1,147 @@
+"""Aggregate statistics. Only counts and shares leave this module, never rows.
+
+Any bucket seen fewer than K_MIN times is folded into "other", so a rare
+configuration can't be traced back to one visitor.
+"""
+
+from __future__ import annotations
+
+import statistics
+import threading
+import time
+from collections import Counter, defaultdict
+from typing import Callable, Iterable
+
+from .recommend import CommunitySignal
+
+K_MIN = 5
+
+
+def _suppress(counter: Counter, k: int = K_MIN, top: int = 15) -> list[dict]:
+    total = sum(counter.values())
+    items, other = [], 0
+    for key, n in counter.most_common():
+        if key is None or n < k or len(items) >= top:
+            other += n
+        else:
+            items.append({"key": key, "count": n, "share": round(n / total, 4) if total else 0})
+    if other:
+        items.append({"key": "other", "count": other, "share": round(other / total, 4) if total else 0})
+    return items
+
+
+def compute(rows: Iterable[dict], k: int = K_MIN) -> dict:
+    rows = [r for r in rows if not r.get("suspicious_flags")]
+    by_type = Counter(r.get("event_type") for r in rows)
+    sessions = len({r.get("session_id") for r in rows if r.get("session_id")})
+    # A "query" is a distinct configuration a session looked at (explicit search, or re-running
+    # it after changing sort/hardware). Counting each once keeps re-renders from inflating shares.
+    seen, searches = set(), []
+    for r in rows:
+        if r.get("event_type") in ("search", "filter"):
+            key = (r.get("session_id") or id(r), r.get("model_family"), r.get("parameter_bucket"),
+                   r.get("quantization"), r.get("target_context"), r.get("priority"), r.get("hardware_memory_class"))
+            if key not in seen:
+                seen.add(key)
+                searches.append(r)
+
+    quant = Counter(r.get("quantization") for r in searches if r.get("quantization"))
+    qtotal = sum(quant.values())
+    share = lambda b: round(quant.get(b, 0) / qtotal, 4) if qtotal else None
+    contexts = [r["target_context"] for r in searches if r.get("target_context")]
+
+    hw_seen, hw = set(), []
+    for r in rows:  # one count per session and memory class
+        if r.get("hardware_memory_class"):
+            key = (r.get("session_id") or id(r), r["hardware_memory_class"])
+            if key not in hw_seen:
+                hw_seen.add(key)
+                hw.append(r)
+    return {
+        "k_min": k,
+        "totals": {
+            "events": len(rows),
+            "sessions": sessions,
+            "searches": by_type.get("search", 0),
+            "distinct_queries": len(searches),
+            "model_views": by_type.get("model_view", 0),
+            "model_clicks": by_type.get("model_click", 0),
+            "hardware_tests": by_type.get("hardware_test", 0),
+            "browser_benchmarks": by_type.get("browser_benchmark", 0),
+            "feedback": by_type.get("feedback", 0),
+            "mlx_benchmarks": by_type.get("mlx_benchmark_submission", 0),
+        },
+        "quant_share": {"2-bit": share("2-bit"), "3-bit": share("3-bit"), "4-bit": share("4-bit"),
+                        "5-bit": share("5-bit"), "6-bit": share("6-bit"), "8-bit": share("8-bit")},
+        "average_target_context": round(statistics.mean(contexts)) if len(contexts) >= k else None,
+        "families": _suppress(Counter(r.get("model_family") for r in searches), k),
+        "quantizations": _suppress(quant, k),
+        "sizes": _suppress(Counter(r.get("parameter_bucket") for r in searches), k),
+        "ram_classes": _suppress(Counter(r.get("hardware_memory_class") for r in hw), k),
+        "contexts": _suppress(Counter(r.get("target_context") for r in searches), k),
+        "priorities": _suppress(Counter(r.get("priority") for r in searches), k),
+        "selected_models": _suppress(Counter(r.get("selected_model") for r in rows
+                                             if r.get("event_type") in ("model_select", "model_click")), k),
+        "gpu_capability": _suppress(Counter(r.get("gpu_capability_class") for r in rows
+                                            if r.get("event_type") == "hardware_test"), k),
+        "webgpu_available": _suppress(Counter(r.get("webgpu_available") for r in rows
+                                              if r.get("event_type") == "hardware_test"), k),
+    }
+
+
+def community_signals(rows: Iterable[dict]) -> dict[str, CommunitySignal]:
+    fb: dict[str, list[dict]] = defaultdict(list)
+    bench: dict[str, list[float]] = defaultdict(list)
+    for r in rows:
+        if r.get("suspicious_flags"):
+            continue
+        m = r.get("selected_model")
+        if not m:
+            continue
+        if r.get("event_type") == "feedback" and r.get("tried") == "yes":
+            fb[m].append(r)
+        elif r.get("event_type") == "mlx_benchmark_submission" and r.get("generation_tps"):
+            bench[m].append(float(r["generation_tps"]))
+    out = {}
+    for m in set(fb) | set(bench):
+        f = fb.get(m, [])
+        rated = [x for x in f if x.get("outcome") in ("worked", "problem")]
+        pos = sum(1 for x in rated if x.get("outcome") == "worked")
+        b = bench.get(m, [])
+        out[m] = CommunitySignal(
+            feedback_count=len(f),
+            positive_share=round(pos / len(rated), 3) if rated else None,
+            benchmark_count=len(b),
+            median_generation_tps=round(statistics.median(b), 1) if b else None,
+        )
+    return out
+
+
+class StatsCache:
+    def __init__(self, rows_source: Callable[[], list[dict]], ttl: float = 60):
+        self._src = rows_source
+        self.ttl = ttl
+        self._at = 0.0
+        self._stats: dict = {}
+        self._community: dict[str, CommunitySignal] = {}
+        self._lock = threading.Lock()
+
+    def _refresh(self):
+        with self._lock:
+            if time.time() - self._at < self.ttl and self._stats:
+                return
+            rows = self._src()
+            self._stats = compute(rows)
+            self._community = community_signals(rows)
+            self._at = time.time()
+
+    def invalidate(self):
+        self._at = 0.0
+
+    def stats(self) -> dict:
+        self._refresh()
+        return self._stats
+
+    def community(self) -> dict[str, CommunitySignal]:
+        self._refresh()
+        return self._community

bench/mlx_explorer_bench.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""MLX Model Explorer community benchmark.
+
+Measures one MLX model on this Mac with mlx-lm and prints an anonymous JSON result:
+prompt speed, generation speed, time to first token and peak memory. It uses the
+same approach as `mlx_lm.benchmark` (random prompt tokens, EOS disabled, warm-up
+run, several timed trials) and reports medians.
+
+Nothing is sent anywhere unless you pass --submit URL, and even then the exact
+payload is shown and you are asked to confirm. The payload holds no hostname,
+username, paths or serial numbers: only the chip name (e.g. "Apple M3 Max"), the
+RAM size class, OS major version and library versions.
+
+    pip install -U mlx-lm
+    python mlx_explorer_bench.py --model mlx-community/Qwen3-0.6B-4bit
+    python mlx_explorer_bench.py --model mlx-community/Qwen3-0.6B-4bit --submit https://<space-url>
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import platform
+import statistics
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+
+BENCHMARK_VERSION = "mlxbench-1"
+RAM_CLASSES = [8, 16, 18, 24, 32, 36, 48, 64, 96, 128, 192, 256, 512]
+CONTEXTS = [4096, 8192, 16384, 32768, 65536, 131072, 262144]
+
+
+def sysctl(name: str) -> str | None:
+    try:
+        return subprocess.run(["sysctl", "-n", name], capture_output=True, text=True, timeout=5).stdout.strip() or None
+    except (OSError, subprocess.SubprocessError):
+        return None
+
+
+def chip_name() -> str:
+    brand = sysctl("machdep.cpu.brand_string") or ""
+    import re
+
+    m = re.match(r"^Apple (M[1-9])( (Pro|Max|Ultra))?", brand)
+    return f"Apple {m.group(1)}{m.group(2) or ''}" if m else "other"
+
+
+def ram_class() -> int | None:
+    raw = sysctl("hw.memsize")
+    if not raw or not raw.isdigit():
+        return None
+    gb = int(raw) / 1024**3
+    return min(RAM_CLASSES, key=lambda c: abs(c - gb))
+
+
+def context_bucket(tokens: int) -> int:
+    return next((c for c in CONTEXTS if c >= tokens), CONTEXTS[-1])
+
+
+def run(args) -> dict:
+    import mlx.core as mx
+    import mlx_lm
+    from mlx_lm import load, stream_generate
+
+    mx.random.seed(0)
+    print(f"Loading {args.model} …", file=sys.stderr)
+    model, tokenizer, config = load(args.model, return_config=True)
+    tokenizer._eos_token_ids = {}  # never stop early, like mlx_lm.benchmark
+    vocab = config.get("vocab_size") or (config.get("text_config") or {}).get("vocab_size")
+    prompt = mx.random.randint(0, vocab, (args.prompt_tokens,)).tolist()
+
+    def once():
+        start = time.perf_counter()
+        first = None
+        last = None
+        for resp in stream_generate(model, tokenizer, prompt, max_tokens=args.generation_tokens):
+            if first is None:
+                first = time.perf_counter() - start
+            last = resp
+        return last, first
+
+    print("Warm-up run …", file=sys.stderr)
+    once()
+    mx.reset_peak_memory()
+    trials = []
+    for i in range(args.trials):
+        resp, ttft = once()
+        trials.append((resp, ttft))
+        print(f"trial {i + 1}: prompt {resp.prompt_tps:.1f} tok/s, generation {resp.generation_tps:.1f} tok/s, "
+              f"TTFT {ttft * 1000:.0f} ms, peak {resp.peak_memory:.2f} GB", file=sys.stderr)
+
+    med = lambda xs: statistics.median(xs)
+    mac = platform.mac_ver()[0]
+    return {
+        "event_type": "mlx_benchmark_submission",
+        "benchmark_type": "mlx_lm",
+        "benchmark_version": BENCHMARK_VERSION,
+        "selected_model": args.model,
+        "prompt_tokens": args.prompt_tokens,
+        "generation_tokens": args.generation_tokens,
+        "prompt_tps": round(med([r.prompt_tps for r, _ in trials]), 2),
+        "generation_tps": round(med([r.generation_tps for r, _ in trials]), 2),
+        "ttft_ms": round(med([t for _, t in trials]) * 1000, 1),
+        "peak_memory_gb": round(max(r.peak_memory for r, _ in trials), 3),
+        "target_context": context_bucket(args.prompt_tokens + args.generation_tokens),
+        "chip": chip_name(),
+        "reported_ram_gb": ram_class(),
+        "macos_major": int(mac.split(".")[0]) if mac and mac.split(".")[0].isdigit() else None,
+        "mlx_version": getattr(mx, "__version__", None),
+        "mlx_lm_version": getattr(mlx_lm, "__version__", None),
+    }
+
+
+def submit(result: dict, url: str, token: str | None, assume_yes: bool) -> int:
+    payload = {"events": [{k: v for k, v in result.items() if v is not None}]}
+    body = json.dumps(payload).encode()
+    print("\nThis exact payload will be sent to", url.rstrip("/") + "/api/events", file=sys.stderr)
+    print(json.dumps(payload, indent=2), file=sys.stderr)
+    if not assume_yes:
+        if input("Send it? [y/N] ").strip().lower() not in ("y", "yes"):
+            print("Not sent.", file=sys.stderr)
+            return 0
+    headers = {"content-type": "application/json", "user-agent": f"mlx-explorer-bench/{BENCHMARK_VERSION}"}
+    if token:
+        headers["authorization"] = f"Bearer {token}"
+    req = urllib.request.Request(url.rstrip("/") + "/api/events", data=body, headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=30) as r:
+            reply = json.loads(r.read() or b"{}")
+            flags = (reply.get("flags") or [[]])[0]
+            print("Submitted." + (f" Flagged for review: {', '.join(flags)}" if flags else " Thank you!"), file=sys.stderr)
+            return 0
+    except urllib.error.HTTPError as e:
+        print(f"Not accepted: HTTP {e.code} {e.read()[:500].decode(errors='replace')}", file=sys.stderr)
+        return 1
+    except urllib.error.URLError as e:
+        print(f"Couldn't reach {url}: {e.reason}", file=sys.stderr)
+        return 1
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    p.add_argument("--model", required=True, help="Hugging Face repo id, e.g. mlx-community/Qwen3-0.6B-4bit")
+    p.add_argument("--prompt-tokens", "-p", type=int, default=512)
+    p.add_argument("--generation-tokens", "-g", type=int, default=256)
+    p.add_argument("--trials", "-n", type=int, default=3)
+    p.add_argument("--submit", metavar="URL", help="MLX Model Explorer URL to submit the result to")
+    p.add_argument("--yes", action="store_true", help="submit without asking for confirmation")
+    p.add_argument("--hf-token", default=None,
+                   help="only needed while the Space is private: a Hugging Face token sent as a bearer header")
+    args = p.parse_args(argv)
+    if not (1 <= args.prompt_tokens <= 1_048_576 and 1 <= args.generation_tokens <= 65_536 and 1 <= args.trials <= 20):
+        p.error("prompt/generation tokens or trials out of range")
+    if platform.system() != "Darwin" or platform.machine() != "arm64":
+        print("MLX runs on Apple Silicon Macs; this machine can't run the benchmark.", file=sys.stderr)
+        return 2
+    result = run(args)
+    print(json.dumps(result, indent=2))
+    if args.submit:
+        return submit(result, args.submit, args.hf_token, args.yes)
+    print("\nTo contribute this result, paste the JSON into MLX Model Explorer or rerun with --submit URL.", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

data/catalogue_snapshot.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9d2dbfdeddb91d46cb16141299100e673e448e7e96fe7ca06f975cfaeb2539c3
+size 357655

pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+testpaths = tests
+addopts = -q

requirements.txt

@@ -0,0 +1,6 @@
+fastapi==0.119.1
+uvicorn[standard]==0.52.4
+huggingface_hub==1.31.0
+pyarrow==25.0.1
+pydantic==2.13.5
+httpx==0.28.1

static/app.js

@@ -0,0 +1,812 @@
+"use strict";
+
+(function () {
+  const $ = (s, r = document) => r.querySelector(s);
+  const $$ = (s, r = document) => [...r.querySelectorAll(s)];
+
+  // Build DOM safely: all text goes through text nodes, never innerHTML.
+  function el(tag, attrs, ...kids) {
+    const n = document.createElement(tag);
+    for (const [k, v] of Object.entries(attrs || {})) {
+      if (v == null || v === false) continue;
+      if (k === "class") n.className = v;
+      else if (k.startsWith("on")) n.addEventListener(k.slice(2), v);
+      else n.setAttribute(k, v === true ? "" : v);
+    }
+    for (const kid of kids.flat()) {
+      if (kid == null || kid === false) continue;
+      n.append(kid instanceof Node ? kid : document.createTextNode(String(kid)));
+    }
+    return n;
+  }
+
+  const TOP_FAMILIES = 9;
+  const RAM_CHIPS = [8, 16, 18, 24, 32, 36, 48, 64, 96, 128, 192];
+  const SIZE_LABEL = { "<3B": "Under 3B", "3-8B": "3–8B", "8-15B": "8–15B", "15-35B": "15–35B", "35-70B": "35–70B", "70B+": "70B+", MoE: "MoE" };
+  const PRIORITY_LABEL = { balanced: "Balanced", quality: "Quality", speed: "Speed", memory: "Least memory", long_context: "Long context" };
+  const CHIPS = [];
+  for (const g of [1, 2, 3, 4, 5]) for (const t of ["", " Pro", " Max", " Ultra"]) CHIPS.push(`Apple M${g}${t}`);
+
+  const state = {
+    meta: null,
+    sort: "recommended",
+    offset: 0,
+    results: [],
+    total: 0,
+    lastQuery: null,
+    hw: null,
+    ramSource: null, // "confirmed" | "estimated" | null
+    compare: new Map(),
+    pinned: null,
+    requestId: 0,
+  };
+
+  // ------------------------------------------------------------------ formatting
+  const fmtCtx = (n) => (n >= 262144 ? "256k" : n >= 1024 ? `${Math.round(n / 1024)}k` : String(n));
+  const fmtNum = (n) => (n == null ? "unknown" : n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : n >= 1e3 ? `${Math.round(n / 1e3)}k` : String(n));
+  const fmtParams = (p) => (p == null ? "size unknown" : p >= 1e9 ? `${(p / 1e9).toFixed(p >= 1e10 ? 0 : 1)}B` : `${Math.round(p / 1e6)}M`);
+  const fmtGB = (g) => (g == null ? "unknown" : `${g < 10 ? g.toFixed(1) : Math.round(g)}\u00a0GB`);
+  function fmtAgo(iso) {
+    if (!iso) return "unknown";
+    const days = (Date.now() - Date.parse(iso)) / 864e5;
+    if (!isFinite(days)) return "unknown";
+    if (days < 1) return "today";
+    const plural = (n, unit) => `${n} ${unit}${n === 1 ? "" : "s"} ago`;
+    if (days < 31) return plural(Math.round(days), "day");
+    if (days < 365) return plural(Math.max(1, Math.round(days / 30.4)), "month");
+    const y = days / 365;
+    return `${y < 1.95 ? y.toFixed(1) : Math.round(y)} years ago`;
+  }
+  const fitText = (fit) => ({ Comfortable: "comfortable fit", Likely: "likely fits", Borderline: "borderline", Unlikely: "unlikely to fit" }[fit] || "");
+
+  // ------------------------------------------------------------------ telemetry
+  const Telemetry = (() => {
+    // A browser privacy signal (GPC / Do Not Track) means "off" unless the user explicitly opts in here.
+    const gpc = navigator.globalPrivacyControl === true || navigator.doNotTrack === "1";
+    let optedOut = gpc;
+    try {
+      if (localStorage.getItem("mme-optout") === "1") optedOut = true;
+      else if (gpc && localStorage.getItem("mme-optin") === "1") optedOut = false;
+    } catch (e) {}
+    let sid = null;
+    try { sid = sessionStorage.getItem("mme-sid"); } catch (e) {}
+    if (!sid || !/^[a-f0-9]{16}$/.test(sid)) {
+      const b = new Uint8Array(8);
+      crypto.getRandomValues(b);
+      sid = [...b].map((x) => x.toString(16).padStart(2, "0")).join("");
+      try { sessionStorage.setItem("mme-sid", sid); } catch (e) {}
+    }
+    let queue = [];
+    let enabled = true;
+
+    function send(beacon) {
+      if (!queue.length || optedOut || !enabled) { queue = []; return; }
+      const batch = queue.splice(0, 50);
+      const body = JSON.stringify({ events: batch });
+      if (beacon && navigator.sendBeacon) {
+        navigator.sendBeacon("/api/events", new Blob([body], { type: "application/json" }));
+      } else {
+        fetch("/api/events", { method: "POST", headers: { "content-type": "application/json" }, body, keepalive: true }).catch(() => {});
+      }
+      if (queue.length) send(beacon);
+    }
+    setInterval(() => send(false), 10000);
+    document.addEventListener("visibilitychange", () => { if (document.visibilityState === "hidden") send(true); });
+    window.addEventListener("pagehide", () => send(true));
+
+    return {
+      gpc,
+      get optedOut() { return optedOut; },
+      setOptOut(v) {
+        optedOut = v;
+        try {
+          if (v) { localStorage.setItem("mme-optout", "1"); localStorage.removeItem("mme-optin"); }
+          else { localStorage.removeItem("mme-optout"); if (gpc) localStorage.setItem("mme-optin", "1"); }
+        } catch (e) {}
+        if (optedOut) queue = [];
+      },
+      setEnabled(v) { enabled = v; },
+      track(type, fields) {
+        if (optedOut || !enabled) return;
+        const ev = { event_type: type, session_id: sid };
+        for (const [k, v] of Object.entries(fields || {})) if (v !== undefined && v !== null && v !== "") ev[k] = v;
+        queue.push(ev);
+        if (queue.length >= 20) send(false);
+      },
+      // Submissions the user explicitly asked to send go out immediately, with a result.
+      async submit(type, fields) {
+        if (optedOut) return { ok: false, message: "Sending is turned off in Privacy settings on this page." };
+        const ev = { event_type: type, session_id: sid, ...fields };
+        Object.keys(ev).forEach((k) => (ev[k] === undefined || ev[k] === null || ev[k] === "") && delete ev[k]);
+        try {
+          const r = await fetch("/api/events", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ events: [ev] }) });
+          const j = await r.json().catch(() => ({}));
+          if (r.status === 202) return { ok: true, flags: (j.flags || [])[0] || [] };
+          if (r.status === 429) return { ok: false, message: "Too many submissions from this network. Try again in a minute." };
+          const d = (j.details || []).map((x) => `${(x.loc || []).slice(-1)[0]}: ${x.msg}`).join("; ");
+          return { ok: false, message: `Not accepted${d ? ` (${d})` : ""}.` };
+        } catch (e) {
+          return { ok: false, message: "Couldn't reach the server. Check your connection and try again." };
+        }
+      },
+    };
+  })();
+
+  // ------------------------------------------------------------------ controls
+  function chip(name, value, label, small, checked) {
+    const input = el("input", { type: "radio", name, value });
+    input.checked = !!checked;
+    return el("label", { class: "chip" }, input, el("span", {}, label, small ? el("small", {}, small) : null));
+  }
+
+  function radioValue(name) {
+    const r = $(`#query input[name="${name}"]:checked`);
+    return r ? r.value : "";
+  }
+
+  function setRadio(name, value) {
+    const r = $$(`#query input[name="${name}"]`).find((x) => x.value === String(value));
+    if (r) { r.checked = true; return true; }
+    return false;
+  }
+
+  function uncheck(name) {
+    $$(`#query input[name="${name}"]`).forEach((x) => (x.checked = false));
+  }
+
+  function currentRam() {
+    const v = parseInt(radioValue("ram"), 10);
+    return Number.isFinite(v) ? v : null;
+  }
+
+  function currentFamily() {
+    return radioValue("family") || $("#family-more").value || "";
+  }
+
+  function buildControls(m) {
+    const ramOpts = RAM_CHIPS.filter((g) => m.ram_classes.includes(g));
+    $("#ram-chips").replaceChildren(chip("ram", "", "Not sure", null, true), ...ramOpts.map((g) => chip("ram", g, `${g} GB`)));
+    $("#context-chips").replaceChildren(...m.contexts.map((c) => chip("context", c, fmtCtx(c), null, c === 8192)));
+
+    const fams = m.families.filter((f) => f.family !== "Other");
+    $("#family-chips").replaceChildren(chip("family", "", "Any", null, true),
+      ...fams.slice(0, TOP_FAMILIES).map((f) => chip("family", f.family, f.family, String(f.count))));
+    const more = $("#family-more");
+    more.length = 1;
+    fams.slice(TOP_FAMILIES).forEach((f) => more.append(el("option", { value: f.family }, `${f.family} (${f.count})`)));
+    const other = m.families.find((f) => f.family === "Other");
+    if (other) more.append(el("option", { value: "Other" }, `Other (${other.count})`));
+
+    $("#size-chips").replaceChildren(chip("size", "", "Any", null, true), ...m.sizes.map((s) => chip("size", s, SIZE_LABEL[s] || s)));
+    const quants = m.quantizations.filter((q) => q !== "unknown");
+    $("#quant-chips").replaceChildren(chip("quant", "", "Any", null, true),
+      ...quants.map((q) => chip("quant", q, q.replace("-bit", " bit"))), chip("quant", "unknown", "Unknown"));
+    $("#priority-chips").replaceChildren(...m.priorities.map((p) => chip("priority", p, PRIORITY_LABEL[p] || p, null, p === "balanced")));
+  }
+
+  function hwFields() {
+    const f = {};
+    const ram = currentRam();
+    if (ram) f.hardware_memory_class = ram;
+    f.hardware_source = state.ramSource === "confirmed" ? "confirmed" : state.hw ? "detected" : "none";
+    if (state.hw) {
+      f.webgpu_available = state.hw.webgpu_available;
+      f.gpu_capability_class = state.hw.capability;
+      f.gpu_vendor = state.hw.gpu_vendor;
+      f.gpu_arch = state.hw.gpu_arch;
+      f.cpu_cores = state.hw.cpu_cores;
+      f.browser_family = state.hw.browser_family;
+      f.os_family = state.hw.os_family;
+    }
+    return f;
+  }
+
+  async function loadMeta() {
+    const r = await fetch("/api/meta");
+    if (!r.ok) throw new Error("meta");
+    const m = await r.json();
+    state.meta = m;
+    buildControls(m);
+    $("#app-version").textContent = m.version;
+    $("#engine-version").textContent = m.engine;
+    const c = m.catalogue;
+    $("#cat-status").textContent = `${c.models.toLocaleString()} models indexed${c.degraded ? " from a cached copy" : ""}`;
+    if (!m.collection_enabled) Telemetry.setEnabled(false);
+    restoreFromUrl();
+  }
+
+  function restoreFromUrl() {
+    const p = new URLSearchParams(location.search);
+    const fam = p.get("family");
+    if (fam && !setRadio("family", fam) && [...$("#family-more").options].some((o) => o.value === fam)) {
+      $("#family-more").value = fam;
+      uncheck("family");
+    }
+    ["size", "quant", "context", "priority"].forEach((k) => p.get(k) && setRadio(k, p.get(k)));
+    if (p.get("ram") && setRadio("ram", p.get("ram"))) state.ramSource = "confirmed";
+    updateRamHint();
+  }
+
+  function readQuery() {
+    const ram = currentRam();
+    return {
+      family: currentFamily() || null,
+      size: radioValue("size") || null,
+      quant: radioValue("quant") || null,
+      context: parseInt(radioValue("context"), 10) || 8192,
+      ram_gb: ram,
+      ram_source: ram ? (state.ramSource === "confirmed" ? "confirmed" : "estimated") : null,
+      priority: radioValue("priority") || "balanced",
+      sort: state.sort,
+      llm_only: !$("#non-llm").checked,
+      search: $("#search").value.trim() || null,
+    };
+  }
+
+  function syncUrl(q) {
+    const p = new URLSearchParams();
+    if (q.family) p.set("family", q.family);
+    if (q.size) p.set("size", q.size);
+    if (q.quant) p.set("quant", q.quant);
+    if (q.context !== 8192) p.set("context", q.context);
+    if (q.ram_gb && state.ramSource === "confirmed") p.set("ram", q.ram_gb);
+    if (q.priority !== "balanced") p.set("priority", q.priority);
+    history.replaceState(null, "", p.toString() ? `?${p}` : location.pathname);
+  }
+
+  function updateRamHint() {
+    if (!currentRam()) $("#ram-hint").textContent = "Or pick it above.";
+    else if (state.ramSource === "confirmed") $("#ram-hint").textContent = "Set by you.";
+  }
+
+  // ------------------------------------------------------------------ memory budget
+  function usableGB(ram) {
+    return ram ? ram * (ram <= 36 ? 0.67 : 0.75) : null;
+  }
+
+  // One scale per set of bars so they compare honestly. Very large models clip at
+  // twice the usable limit instead of squashing everything else.
+  function scaleFor(ram, totals) {
+    const usable = usableGB(ram);
+    const biggest = Math.max(0, ...totals.filter((t) => t != null));
+    if (usable) return Math.max(usable, Math.min(biggest, usable * 2)) * 1.06;
+    return Math.max(biggest, 4) * 1.1;
+  }
+
+  function paintBar(track, mem, scale, ram) {
+    const segs = track.querySelectorAll(".seg");
+    const limit = track.querySelector(".limit");
+    const w = mem && mem.weights_gb != null ? mem.weights_gb : 0;
+    const kv = mem && mem.kv_gb != null ? mem.kv_gb : 0;
+    const oh = mem && mem.overhead_gb != null ? mem.overhead_gb : 0;
+    const pct = (x) => `${Math.max(0, Math.min(100, (x / scale) * 100))}%`;
+    segs[0].style.width = pct(w);
+    segs[1].style.width = pct(Math.min(kv, Math.max(0, scale - w)));
+    segs[2].style.width = pct(Math.min(oh, Math.max(0, scale - w - kv)));
+    const usable = usableGB(ram);
+    limit.hidden = !usable;
+    if (usable) limit.style.left = pct(usable);
+    track.classList.toggle("over", !!(mem && usable && mem.total_gb > usable));
+  }
+
+  function miniBar(mem, scale, ram) {
+    const track = el("div", { class: "mini", "aria-hidden": "true" },
+      el("span", { class: "seg seg-w" }), el("span", { class: "seg seg-kv" }), el("span", { class: "seg seg-oh" }), el("span", { class: "limit" }));
+    paintBar(track, mem, scale, ram);
+    return track;
+  }
+
+  function renderBudget(r) {
+    const q = state.lastQuery || readQuery();
+    const ram = q.ram_gb;
+    const usable = usableGB(ram);
+    $("#budget-mac").textContent = ram ? `${ram} GB Mac${state.ramSource === "confirmed" ? "" : " (estimated)"}` : "Pick your Mac's memory to see what fits";
+    $("#budget-usable").textContent = usable ? `About ${Math.round(usable)} GB usable by the GPU` : "";
+    const mem = r && r.memory;
+    paintBar($("#budget-track"), mem, scaleFor(ram, [mem && mem.total_gb]), ram);
+    const line = $("#budget-model");
+    if (!r) {
+      line.textContent = state.lastQuery && state.total === 0 ? "No models match these filters." : "Loading models";
+      return;
+    }
+    const name = el("strong", {}, r.model.name);
+    if (!mem || mem.total_gb == null) {
+      line.replaceChildren(name, " has no size information, so its memory can't be estimated.");
+      return;
+    }
+    const parts = [name, ` at ${fmtCtx(q.context)} context needs about ${fmtGB(mem.total_gb)}`];
+    if (mem.fit) parts.push(": ", el("span", { class: `fit-${mem.fit}` }, fitText(mem.fit)), ".");
+    else parts.push(". Pick your Mac's memory to check the fit.");
+    parts.push(` ${fmtGB(mem.weights_gb)} of weights and ${fmtGB(mem.kv_gb)} of KV cache${mem.kv_rough ? " (rough)" : ""}.`);
+    line.replaceChildren(...parts);
+    $("#budget-track").setAttribute("aria-label",
+      `${r.model.name}: weights ${fmtGB(mem.weights_gb)}, KV cache ${fmtGB(mem.kv_gb)}, overhead ${fmtGB(mem.overhead_gb)}${usable ? `, GPU limit about ${Math.round(usable)} GB` : ""}`);
+  }
+
+  // ------------------------------------------------------------------ results
+  let debounce = null;
+  function scheduleExplore(reason) {
+    clearTimeout(debounce);
+    debounce = setTimeout(() => explore({ reason }), 220);
+  }
+
+  async function explore({ append = false, reason = "search" } = {}) {
+    const q = readQuery();
+    if (!append) state.offset = 0;
+    state.lastQuery = q;
+    const id = ++state.requestId;
+    $("#results").setAttribute("aria-busy", "true");
+    if (!append) $("#summary").textContent = "Finding models";
+    try {
+      const r = await fetch("/api/recommend", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ ...q, offset: state.offset, limit: 24 }),
+      });
+      if (!r.ok) throw new Error(`HTTP ${r.status}`);
+      const data = await r.json();
+      if (id !== state.requestId) return; // a newer query superseded this one
+      state.total = data.total;
+      state.results = append ? state.results.concat(data.results) : data.results;
+      renderResults(data, append);
+      syncUrl(q);
+      if (!append) {
+        Telemetry.track(reason, {
+          model_family: q.family, parameter_bucket: q.size, quantization: q.quant, target_context: q.context,
+          priority: q.priority, sort: q.sort, result_count: data.total, ...hwFields(),
+        });
+      }
+    } catch (e) {
+      if (id !== state.requestId) return;
+      $("#summary").textContent = "";
+      $("#notices").replaceChildren(el("p", { class: "note" }, "Models couldn't be loaded. Check your connection, then change a filter to retry."));
+    } finally {
+      if (id === state.requestId) $("#results").removeAttribute("aria-busy");
+    }
+  }
+
+  function describeQuery(q) {
+    return [q.family || "all families", q.size ? SIZE_LABEL[q.size] || q.size : null, q.quant, `${fmtCtx(q.context)} context`]
+      .filter(Boolean).join(", ");
+  }
+
+  function renderResults(data, append) {
+    const q = state.lastQuery;
+    $("#summary").textContent = `${data.total.toLocaleString()} ${data.total === 1 ? "model" : "models"} for ${describeQuery(q)}`;
+    const notices = data.notices.map((n) => el("p", { class: "note" }, n));
+    if (!data.total) notices.push(el("p", { class: "note" }, "Nothing matches. Set Size or Quantization to Any, or clear the name filter."));
+    $("#notices").replaceChildren(...notices);
+    const list = $("#list");
+    if (!append) list.replaceChildren();
+    const scale = scaleFor(q.ram_gb, state.results.map((r) => r.memory.total_gb));
+    if (append) $$(".row .mini", list).forEach((bar, i) => state.results[i] && paintBar(bar, state.results[i].memory, scale, q.ram_gb));
+    data.results.forEach((r, i) => list.append(resultRow(r, data.offset + i, scale)));
+    state.offset = data.offset + data.results.length;
+    $("#more").hidden = state.offset >= data.total;
+    if (!append) {
+      state.pinned = state.results[0] || null;
+      renderBudget(state.pinned);
+    }
+  }
+
+  function resultRow(r, rank, scale) {
+    const m = r.model;
+    const mem = r.memory;
+    const q = state.lastQuery;
+    const quant = r.quant || m.quant;
+    const cmp = el("input", { type: "checkbox" });
+    cmp.checked = state.compare.has(m.id);
+    cmp.addEventListener("change", () => toggleCompare(r, cmp, rank));
+    const fitLabel = mem.fit
+      ? el("span", { class: `fit-label fit-${mem.fit}` }, mem.fit)
+      : el("span", { class: "fit-label fit-none" }, mem.total_gb == null ? "size unknown" : q.ram_gb ? "unknown" : "set memory");
+    const moe = m.moe ? (m.active_params ? `, MoE with ${fmtParams(m.active_params)} active` : ", MoE") : "";
+    const row = el("li", { class: "row" },
+      el("div", { class: "row-main" },
+        el("div", { class: "row-title" },
+          el("button", { class: "row-name", type: "button", onclick: () => openDetail(m.id, rank, r) }, m.name)),
+        el("div", { class: "facts" },
+          el("span", { class: "tag" }, quant.label === "unknown" ? "quantization unknown" : quant.label),
+          el("span", {}, fmtParams(m.params) + moe),
+          m.pipeline === "image-text-to-text" ? el("span", {}, "vision") : null,
+          m.partial ? el("span", { class: "warn", title: "The repo holds far fewer weights than its name suggests" }, "partial or add-on") : null,
+          el("span", {}, `${fmtNum(m.downloads)} downloads`),
+          m.likes ? el("span", {}, `${fmtNum(m.likes)} likes`) : null,
+          el("span", {}, `updated ${fmtAgo(m.modified)}`),
+          r.community.benchmark_count ? el("span", {}, `${r.community.benchmark_count} MLX benchmark${r.community.benchmark_count > 1 ? "s" : ""}`) : null),
+        el("p", { class: "why" }, rowReason(r)),
+        el("div", { class: "row-actions" },
+          el("button", { type: "button", class: "linkish", onclick: () => openDetail(m.id, rank, r) }, "Details"),
+          el("label", { class: "check" }, cmp, "Compare"),
+          el("a", { href: m.url, target: "_blank", rel: "noopener", onclick: () => trackClick(m.id, rank, r) }, "View on Hugging Face"))),
+      el("div", { class: "row-fit" },
+        el("div", { class: "fit-line" }, el("span", { class: "fit-gb" }, mem.total_gb == null ? "?" : fmtGB(mem.total_gb)), fitLabel),
+        miniBar(mem, scale, q.ram_gb),
+        state.sort === "recommended" ? el("span", { class: "score", title: "Best-fit score from 0 to 100, explained under How it works" }, `Score ${Math.round(r.score)}`) : null));
+    const show = () => {
+      $$(".row.active").forEach((x) => x.classList.remove("active"));
+      row.classList.add("active");
+      renderBudget(r);
+    };
+    row.addEventListener("mouseenter", show);
+    row.addEventListener("focusin", show);
+    return row;
+  }
+
+  // The bar already shows fit and size, so lead with the reason that adds something.
+  function rowReason(r) {
+    const skip = /fit:|^Needs roughly|downloads\.$|^KV cache at/;
+    return r.reasons.find((t) => !skip.test(t)) || r.reasons[0] || "";
+  }
+
+  function shown(r) {
+    return r ? { recommendation_score: Math.round(r.score * 10) / 10, fit_class: r.memory && r.memory.fit } : {};
+  }
+
+  function trackClick(id, rank, r) {
+    const q = state.lastQuery || readQuery();
+    Telemetry.track("model_click", { selected_model: id, selected_model_rank: rank, target_context: q.context, priority: q.priority, ...shown(r), ...hwFields() });
+  }
+
+  // ------------------------------------------------------------------ compare
+  function toggleCompare(r, box, rank) {
+    if (box.checked) {
+      if (state.compare.size >= 4) {
+        box.checked = false;
+        flashTray("Compare up to 4 models at a time.");
+        return;
+      }
+      state.compare.set(r.model.id, r);
+      const q = state.lastQuery || readQuery();
+      Telemetry.track("model_select", { selected_model: r.model.id, selected_model_rank: rank, target_context: q.context, priority: q.priority, ...shown(r), ...hwFields() });
+    } else {
+      state.compare.delete(r.model.id);
+    }
+    renderTray();
+  }
+
+  function flashTray(msg) {
+    renderTray();
+    $("#compare-tray").hidden = false;
+    $("#compare-count").textContent = msg;
+    setTimeout(renderTray, 2200);
+  }
+
+  function renderTray() {
+    const n = state.compare.size;
+    $("#compare-tray").hidden = n === 0;
+    $("#compare-count").textContent = n === 1 ? "1 selected, pick another to compare" : `${n} models selected`;
+    $("#compare-open").disabled = n < 2;
+  }
+
+  function relQuality(bits) {
+    if (bits == null) return "unknown";
+    if (bits >= 16) return "reference (unquantized)";
+    if (bits >= 8) return "near reference";
+    if (bits >= 5) return "high";
+    if (bits >= 4) return "good";
+    if (bits >= 3) return "lower";
+    return "lowest";
+  }
+
+  function openCompare() {
+    const items = [...state.compare.values()];
+    const q = state.lastQuery || readQuery();
+    Telemetry.track("compare", { compare_models: items.map((x) => x.model.id), target_context: q.context, priority: q.priority, ...hwFields() });
+    const scale = scaleFor(q.ram_gb, items.map((r) => r.memory.total_gb));
+    const qt = (r) => r.quant || r.model.quant;
+    const rows = [
+      ["Quantization", (r) => qt(r).label],
+      ["Parameters", (r) => fmtParams(r.model.params) + (r.model.moe ? ", MoE" : "")],
+      [`Memory at ${fmtCtx(q.context)}`, (r) => fmtGB(r.memory.total_gb)],
+      ["Memory budget", (r) => miniBar(r.memory, scale, q.ram_gb), "compare-bar"],
+      ["Weights", (r) => fmtGB(r.memory.weights_gb)],
+      ["KV cache", (r) => (r.memory.kv_gb == null ? "unknown" : fmtGB(r.memory.kv_gb) + (r.memory.kv_rough ? " (rough)" : ""))],
+      ["Fit", (r) => r.memory.fit || (q.ram_gb ? "unknown" : "set your memory")],
+      ["Relative quality", (r) => relQuality(qt(r).bits)],
+      ["Speed", (r) => (r.community.median_generation_tps ? `${r.community.median_generation_tps} tok/s median from community benchmarks` : "unknown, no community benchmarks yet")],
+      ["Downloads", (r) => fmtNum(r.model.downloads)],
+      ["Likes", (r) => fmtNum(r.model.likes)],
+      ["Updated", (r) => fmtAgo(r.model.modified)],
+      ["Community reports", (r) => (r.community.feedback_count ? `${r.community.feedback_count}${r.community.positive_share != null ? `, ${Math.round(r.community.positive_share * 100)}% positive` : ""}` : "none yet")],
+    ];
+    const table = el("table", {},
+      el("thead", {}, el("tr", {}, el("th", {}, ""), items.map((r) => el("th", {}, el("a", { href: r.model.url, target: "_blank", rel: "noopener" }, r.model.name))))),
+      el("tbody", {}, rows.map(([label, f, cls]) => el("tr", { class: cls || null }, el("th", {}, label), items.map((r) => el("td", {}, f(r)))))));
+    $("#c-body").replaceChildren(
+      el("div", { class: "table-scroll" }, table),
+      el("p", { class: "scale-note" }, "Quality is relative within the same base model: more bits usually keep more quality, by an amount that varies. Speed appears only once people have benchmarked a model."));
+    $("#compare").showModal();
+  }
+
+  // ------------------------------------------------------------------ detail sheet
+  async function openDetail(id, rank, r) {
+    const q = state.lastQuery || readQuery();
+    const dlg = $("#detail");
+    $("#d-title").textContent = id.split("/")[1];
+    $("#d-body").replaceChildren(el("p", { class: "fine" }, "Loading model details"));
+    if (!dlg.open) dlg.showModal();
+    Telemetry.track("model_view", { selected_model: id, selected_model_rank: rank ?? null, target_context: q.context, priority: q.priority, ...shown(r), ...hwFields() });
+    const params = new URLSearchParams({ context: q.context, priority: q.priority });
+    if (q.ram_gb) { params.set("ram_gb", q.ram_gb); if (q.ram_source) params.set("ram_source", q.ram_source); }
+    let d;
+    try {
+      const resp = await fetch(`/api/model/${id.split("/").map(encodeURIComponent).join("/")}?${params}`);
+      if (!resp.ok) throw new Error(String(resp.status));
+      d = await resp.json();
+    } catch (e) {
+      $("#d-body").replaceChildren(el("p", { class: "note" }, "Some model information isn't available right now. The Hugging Face page has the full details."),
+        el("p", {}, el("a", { href: `https://huggingface.co/${id}`, target: "_blank", rel: "noopener" }, "View on Hugging Face")));
+      return;
+    }
+    renderDetail(d, q, rank);
+  }
+
+  function renderDetail(d, q, rank) {
+    const m = d.model;
+    const quant = d.quant || m.quant;
+    const weights = d.files.filter((f) => /\.(safetensors|npz|gguf)$/.test(f.path));
+    const ctxRows = d.memory_by_context;
+    const scale = scaleFor(q.ram_gb, ctxRows.map((x) => x.total_gb));
+    const ctxBars = el("div", { class: "ctx-bars" }, ctxRows.flatMap((x) => [
+      el("span", { class: x.context === q.context ? "ctx cur" : "ctx" }, fmtCtx(x.context)),
+      miniBar(x, scale, q.ram_gb),
+      el("span", { class: "gb" }, fmtGB(x.total_gb)),
+      el("span", { class: `fitc fit-label ${x.exceeds_model_context || !x.fit ? "fit-none" : `fit-${x.fit}`}` },
+        x.exceeds_model_context ? "beyond max context" : x.fit || (q.ram_gb ? "unknown" : "set memory")),
+    ]));
+    const sibs = d.siblings.length ? [
+      el("h3", {}, "Other quantizations of this base model"),
+      el("div", { class: "table-scroll" }, el("table", {},
+        el("thead", {}, el("tr", {}, ["Model", "Quantization", `Memory at ${fmtCtx(q.context)}`, "Fit", "Downloads"].map((h, i) => el("th", { class: i === 4 ? "num" : null }, h)))),
+        el("tbody", {}, d.siblings.map((s) => el("tr", {},
+          el("td", {}, el("button", { type: "button", class: "linkish", onclick: () => openDetail(s.model.id, null, s) }, s.model.name)),
+          el("td", {}, (s.quant || s.model.quant).label),
+          el("td", {}, fmtGB(s.memory.total_gb)),
+          el("td", { class: s.memory.fit ? `fit-${s.memory.fit}` : null }, s.memory.fit || "unknown"),
+          el("td", { class: "num" }, fmtNum(s.model.downloads)))))))] : [];
+    const comm = d.community;
+    const moe = m.moe ? (m.active_params ? `, MoE with ${fmtParams(m.active_params)} active` : ", MoE") : "";
+    const body = [
+      el("p", { class: "sheet-lede" },
+        el("span", {}, quant.label + (quant.mode && !["affine", "float"].includes(quant.mode) ? ` (${quant.mode})` : "")),
+        el("span", {}, fmtParams(m.params) + moe),
+        d.memory.fit ? el("span", { class: `fit-label fit-${d.memory.fit}` }, `${d.memory.fit} at ${fmtCtx(q.context)}`) : null),
+      el("p", {}, el("a", { href: m.url, target: "_blank", rel: "noopener", onclick: () => trackClick(m.id, rank, null) }, `View ${m.id} on Hugging Face`)),
+      d.detail_error ? el("p", { class: "note" }, "Some model information isn't available: the config or file list couldn't be read, so estimates use parameter counts.") : null,
+      el("h3", {}, "Memory by context length"),
+      ctxBars,
+      el("p", { class: "scale-note" }, `Estimates, not measurements: weights + fp16 KV cache + about 1 GB overhead.${q.ram_gb ? ` The line marks about ${Math.round(usableGB(q.ram_gb))} GB usable by the GPU on a ${q.ram_gb} GB Mac.` : ""}`),
+      el("h3", {}, "Why it scores this way"),
+      el("ul", { class: "why-list" }, d.reasons.map((t) => el("li", {}, t))),
+      el("h3", {}, "About this repo"),
+      el("dl", { class: "kv" },
+        el("dt", {}, "Family"), el("dd", {}, m.family),
+        el("dt", {}, "Base model"), el("dd", {}, m.base_model || "unknown"),
+        el("dt", {}, "Pipeline"), el("dd", {}, m.pipeline || "unknown"),
+        el("dt", {}, "Downloads"), el("dd", {}, `${fmtNum(m.downloads)} in the last 30 days`),
+        el("dt", {}, "Likes"), el("dd", {}, fmtNum(m.likes)),
+        el("dt", {}, "Updated"), el("dd", {}, m.modified ? `${m.modified.slice(0, 10)}, ${fmtAgo(m.modified)}` : "unknown"),
+        el("dt", {}, "Files"), el("dd", {}, `${d.file_count} files, ${weights.length} weight ${weights.length === 1 ? "shard" : "shards"}`),
+        el("dt", {}, "Sources"), el("dd", {}, `quantization from ${quant.source}, size from ${m.params_source}, weights from ${d.memory.weights_source === "files" ? "exact file sizes" : "parameter count"}`)),
+      ...sibs,
+      el("h3", {}, "Community data"),
+      el("p", {}, comm.benchmark_count || comm.feedback_count
+        ? `${comm.benchmark_count} MLX benchmark${comm.benchmark_count === 1 ? "" : "s"}${comm.median_generation_tps ? `, median ${comm.median_generation_tps} tok/s generation` : ""}. ${comm.feedback_count} report${comm.feedback_count === 1 ? "" : "s"}${comm.positive_share != null ? `, ${Math.round(comm.positive_share * 100)}% positive` : ""}.`
+        : "No benchmarks or reports yet. Run this on your Mac to add the first:"),
+      el("pre", { class: "cmd" }, el("code", {}, benchCommand(m.id))),
+      feedbackForm(m, q),
+    ];
+    $("#d-body").replaceChildren(...body.filter(Boolean));
+  }
+
+  function feedbackForm(m, q) {
+    const f = $("#feedback-tpl").content.firstElementChild.cloneNode(true);
+    const ram = $("select[name=ram]", f);
+    (state.meta ? state.meta.ram_classes : []).forEach((g) => ram.append(el("option", { value: g }, `${g} GB`)));
+    if (currentRam() && state.ramSource === "confirmed") ram.value = String(currentRam());
+    const chipSel = $("select[name=chip]", f);
+    CHIPS.forEach((c) => chipSel.append(el("option", { value: c }, c.replace("Apple ", ""))));
+    chipSel.append(el("option", { value: "other" }, "Other"));
+    const ctx = $("select[name=ctx]", f);
+    (state.meta ? state.meta.contexts : []).forEach((c) => ctx.append(el("option", { value: c }, fmtCtx(c))));
+    $$("input[name=tried]", f).forEach((r) => r.addEventListener("change", () => { $(".fb-yes", f).hidden = !(r.checked && r.value === "yes"); }));
+    f.addEventListener("submit", async (e) => {
+      e.preventDefault();
+      const out = $(".fb-out", f);
+      const tried = ($("input[name=tried]:checked", f) || {}).value;
+      if (!tried) { out.textContent = "Choose Yes, No or Planning to."; return; }
+      const fields = { selected_model: m.id, tried, target_context: q.context, priority: q.priority, ...hwFields() };
+      if (tried === "yes") {
+        const oc = ($("input[name=outcome]:checked", f) || {}).value;
+        if (oc && oc.startsWith("q:")) fields.quality_rating = oc.slice(2);
+        if (oc && oc.startsWith("f:")) fields.failure_reason = oc.slice(2);
+        fields.reported_ram_gb = parseInt(ram.value, 10) || null;
+        fields.reported_mac_model = chipSel.value || null;
+        const tps = parseFloat($("input[name=tps]", f).value);
+        fields.reported_tokens_per_second = Number.isFinite(tps) && tps > 0 ? tps : null;
+        fields.reported_context = parseInt(ctx.value, 10) || null;
+        fields.notes = $("textarea[name=notes]", f).value.trim() || null;
+      }
+      const btn = $("button[type=submit]", f);
+      btn.disabled = true;
+      const res = await Telemetry.submit("feedback", fields);
+      btn.disabled = false;
+      out.textContent = res.ok ? "Report sent anonymously. Thank you." : res.message;
+      if (res.ok) $$("input, select, textarea, button", f).forEach((x) => (x.disabled = true));
+    });
+    return f;
+  }
+
+  // ------------------------------------------------------------------ hardware
+  async function detectHardware() {
+    const btn = $("#detect");
+    btn.disabled = true;
+    btn.textContent = "Detecting";
+    $("#hw-error").hidden = true;
+    let hw;
+    try {
+      hw = await window.HW.detect();
+    } catch (e) {
+      hw = { webgpu_available: false, error: "failed", capability: "unknown", memory_prior: null, browser_family: "other", os_family: "other" };
+    }
+    state.hw = hw;
+    btn.disabled = false;
+    btn.textContent = "Detect again";
+    const row = (k, v) => [el("dt", {}, k), el("dd", {}, v)];
+    $("#hw-facts").replaceChildren(
+      ...row("GPU", hw.gpu_vendor ? `${hw.gpu_vendor}${hw.gpu_arch ? `, ${hw.gpu_arch}` : ""}` : hw.webgpu_available ? "not exposed" : "WebGPU unavailable"),
+      ...row("Compute", hw.quick_score != null ? `${hw.quick_score.toLocaleString()}, ${hw.capability_label.toLowerCase()}` : "not measured"),
+      ...row("CPU threads", hw.cpu_cores || "unknown"));
+    $("#hw-out").hidden = false;
+    const msgs = [];
+    if (!hw.webgpu_available) msgs.push("WebGPU isn't available in this browser. You can enter your memory manually.");
+    if (hw.os_family && !["macos", "other"].includes(hw.os_family)) msgs.push("This doesn't look like a Mac. MLX runs on Apple Silicon, so pick the memory of the Mac you'll use.");
+    const prior = hw.memory_prior;
+    if (prior) {
+      $("#hw-estimate").textContent = `Estimated capability: ${prior.label}. Is that right? Pick your exact memory above.`;
+      if (!currentRam() || state.ramSource !== "confirmed") {
+        setRadio("ram", prior.ram);
+        state.ramSource = "estimated";
+        $("#ram-hint").textContent = `Estimated: ${prior.note}.`;
+      }
+    } else {
+      $("#hw-estimate").textContent = "We couldn't reliably detect your memory configuration. Pick it above.";
+    }
+    if (msgs.length) { $("#hw-error").textContent = msgs.join(" "); $("#hw-error").hidden = false; }
+    $("#full-bench").disabled = !hw.webgpu_available;
+    Telemetry.track("hardware_test", {
+      ...hwFields(), hardware_source: "detected", webgpu_score: hw.quick_score,
+      benchmark_type: hw.quick_score != null ? "webgpu_quick" : null,
+      benchmark_version: hw.quick_score != null ? window.HW.BENCH_VERSION : null,
+      benchmark_duration_ms: hw.duration_ms,
+    });
+    explore({ reason: "filter" });
+  }
+
+  async function runFullBench() {
+    const btn = $("#full-bench");
+    const prog = $("#bench-progress");
+    btn.disabled = true;
+    prog.hidden = false;
+    prog.value = 0;
+    $("#bench-out").textContent = "Running. Keep this tab in front for 20 seconds.";
+    try {
+      const res = await window.HW.fullBenchmark((p) => { prog.value = p; });
+      $("#bench-out").textContent = `WebGPU compute score: ${res.score.toLocaleString()}. A relative browser GPU score for grouping hardware, not MLX speed or tokens per second.`;
+      Telemetry.track("browser_benchmark", {
+        ...hwFields(), webgpu_score: res.score, benchmark_type: "webgpu_full", benchmark_version: res.version,
+        benchmark_duration_ms: res.duration_ms, gpu_capability_class: window.HW.capabilityClass(state.hw && state.hw.quick_score),
+      });
+    } catch (e) {
+      $("#bench-out").textContent = "The GPU test couldn't run in this browser.";
+    } finally {
+      btn.disabled = false;
+      prog.hidden = true;
+    }
+  }
+
+  // ------------------------------------------------------------------ MLX benchmark section
+  function benchCommand(model) {
+    const origin = location.origin;
+    return [
+      "pip install -U mlx-lm",
+      `curl -fsSLO ${origin}/bench/mlx_explorer_bench.py`,
+      `python mlx_explorer_bench.py --model ${model}`,
+      `# to contribute the result, add: --submit ${origin}`,
+    ].join("\n");
+  }
+
+  function updateBenchCmd() {
+    const v = $("#bench-model").value.trim();
+    const model = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/.test(v) ? v : "mlx-community/MODEL";
+    $("#bench-cmd").textContent = benchCommand(model);
+  }
+
+  const BENCH_KEYS = ["selected_model", "benchmark_type", "benchmark_version", "prompt_tokens", "generation_tokens", "prompt_tps",
+    "generation_tps", "ttft_ms", "peak_memory_gb", "chip", "reported_ram_gb", "mlx_version", "mlx_lm_version", "macos_major", "target_context"];
+
+  async function submitBenchJson() {
+    const out = $("#bench-submit-out");
+    let obj;
+    try {
+      obj = JSON.parse($("#bench-json").value);
+    } catch (e) {
+      out.textContent = "That isn't valid JSON. Paste the block the script printed.";
+      return;
+    }
+    if (!obj || typeof obj !== "object" || Array.isArray(obj)) { out.textContent = "Paste a single JSON object, the block the script printed."; return; }
+    const fields = {};
+    for (const k of BENCH_KEYS) if (k in obj) fields[k] = obj[k];
+    const res = await Telemetry.submit("mlx_benchmark_submission", fields);
+    out.textContent = res.ok
+      ? res.flags.length ? `Result recorded and flagged for review: ${res.flags.join(", ")}.` : "Result recorded anonymously. Thank you."
+      : res.message;
+  }
+
+  // ------------------------------------------------------------------ wiring
+  function init() {
+    const form = $("#query");
+    form.addEventListener("submit", (e) => e.preventDefault());
+    form.addEventListener("change", (e) => {
+      const t = e.target;
+      if (t.id === "search") return;
+      if (t.name === "ram") {
+        state.ramSource = t.value ? "confirmed" : null;
+        updateRamHint();
+        scheduleExplore("filter");
+        return;
+      }
+      if (t.name === "family") $("#family-more").value = "";
+      if (t.id === "family-more") { if (t.value) uncheck("family"); else setRadio("family", ""); }
+      scheduleExplore("search");
+    });
+    let typing = null;
+    $("#search").addEventListener("input", () => { clearTimeout(typing); typing = setTimeout(() => explore({ reason: "search" }), 350); });
+    $$("#sort button").forEach((b) => b.addEventListener("click", () => {
+      state.sort = b.dataset.sort;
+      $$("#sort button").forEach((x) => x.setAttribute("aria-selected", String(x === b)));
+      explore({ reason: "filter" });
+    }));
+    $("#list").addEventListener("mouseleave", () => {
+      $$(".row.active").forEach((x) => x.classList.remove("active"));
+      renderBudget(state.pinned);
+    });
+    $("#more").addEventListener("click", () => explore({ append: true }));
+    $("#detect").addEventListener("click", detectHardware);
+    $("#full-bench").addEventListener("click", runFullBench);
+    $("#compare-open").addEventListener("click", openCompare);
+    $("#compare-clear").addEventListener("click", () => {
+      state.compare.clear();
+      $$("#list .row-actions input[type=checkbox]").forEach((x) => (x.checked = false));
+      renderTray();
+    });
+    $$("dialog [data-close]").forEach((b) => b.addEventListener("click", () => b.closest("dialog").close()));
+    $$("dialog").forEach((d) => d.addEventListener("click", (e) => { if (e.target === d) d.close(); }));
+    $("#bench-model").addEventListener("input", updateBenchCmd);
+    $("#copy-cmd").addEventListener("click", async () => {
+      const b = $("#copy-cmd");
+      try { await navigator.clipboard.writeText($("#bench-cmd").textContent); b.textContent = "Copied"; }
+      catch (e) { b.textContent = "Select the text to copy"; }
+      setTimeout(() => (b.textContent = "Copy command"), 1600);
+    });
+    $("#bench-submit").addEventListener("click", submitBenchJson);
+    const opt = $("#optout");
+    opt.checked = Telemetry.optedOut;
+    if (Telemetry.gpc) $("#gpc-note").hidden = false;
+    opt.addEventListener("change", () => Telemetry.setOptOut(opt.checked));
+    // On phones the rail sits above the results: keep only memory and context open.
+    const hasFilters = /[?&](family|size|quant|priority)=/.test(location.search);
+    if (window.matchMedia("(max-width: 900px)").matches && !hasFilters) $("#more-filters").open = false;
+    updateBenchCmd();
+    loadMeta()
+      .then(() => explore())
+      .catch(() => {
+        $("#notices").replaceChildren(el("p", { class: "note" }, "The model catalogue couldn't be loaded. Refresh the page in a moment."));
+        $("#budget-model").textContent = "The model catalogue couldn't be loaded.";
+      });
+  }
+
+  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", init);
+  else init();
+})();

static/index.html

@@ -0,0 +1,272 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>MLX Model Explorer</title>
+<meta name="description" content="Find an MLX model that fits your Mac. Compare mlx-community models by memory, quantization, popularity and community experience.">
+<meta name="color-scheme" content="light dark">
+<link rel="stylesheet" href="/static/styles.css">
+<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='7' fill='%2317212B'/%3E%3Crect x='6' y='13' width='11' height='6' rx='1.5' fill='%234F86C6'/%3E%3Crect x='17' y='13' width='5' height='6' rx='1.5' fill='%239C7FD6'/%3E%3Crect x='24.5' y='9' width='1.5' height='14' rx='.75' fill='%23fff'/%3E%3C/svg%3E">
+</head>
+<body>
+<a class="skip" href="#results">Skip to results</a>
+
+<header class="top">
+  <div class="shell top-row">
+    <a class="brand" href="/" aria-label="MLX Model Explorer home">
+      <svg class="brand-mark" viewBox="0 0 32 32" aria-hidden="true"><rect x="3" y="12" width="14" height="8" rx="2" class="fill-w"/><rect x="17" y="12" width="6" height="8" rx="2" class="fill-kv"/><rect x="26" y="7" width="2" height="18" rx="1" class="fill-limit"/></svg>
+      <span>MLX Model Explorer</span>
+    </a>
+    <nav aria-label="Sections">
+      <a href="#benchmark">Benchmark</a>
+      <a href="#methodology">How it works</a>
+      <a href="#privacy">Privacy</a>
+      <a href="/stats">Community stats</a>
+    </nav>
+  </div>
+</header>
+
+<main>
+  <section class="hero shell" aria-labelledby="hero-title">
+    <div class="hero-copy">
+      <h1 id="hero-title">Find an MLX model that fits your Mac.</h1>
+      <p class="lede">Every model in <a href="https://huggingface.co/mlx-community" target="_blank" rel="noopener">mlx-community</a>, sized against the memory your GPU can actually use: weights, KV cache for your context, and runtime overhead.</p>
+    </div>
+
+    <figure class="budget" id="budget" aria-live="polite">
+      <figcaption class="budget-head">
+        <span class="budget-mac" id="budget-mac">Pick your Mac's memory to see what fits</span>
+        <span class="budget-usable" id="budget-usable"></span>
+      </figcaption>
+      <div class="budget-track" id="budget-track" role="img" aria-label="Memory budget">
+        <span class="seg seg-w" id="seg-w"></span><span class="seg seg-kv" id="seg-kv"></span><span class="seg seg-oh" id="seg-oh"></span>
+        <span class="limit" id="budget-limit" hidden></span>
+      </div>
+      <div class="budget-foot">
+        <p class="budget-model" id="budget-model">Loading models</p>
+        <ul class="legend" aria-label="Legend">
+          <li><i class="sw seg-w"></i>Weights</li>
+          <li><i class="sw seg-kv"></i>KV cache</li>
+          <li><i class="sw seg-oh"></i>Overhead</li>
+          <li><i class="sw sw-limit"></i>GPU limit</li>
+        </ul>
+      </div>
+    </figure>
+  </section>
+
+  <div class="shell workspace">
+    <aside class="rail" aria-label="Filters">
+      <form id="query" autocomplete="off">
+        <fieldset class="group">
+          <legend>Your Mac's memory</legend>
+          <div class="chips" id="ram-chips" role="radiogroup" aria-label="Mac memory"></div>
+          <div class="detect-row">
+            <button type="button" id="detect" class="ghost">Detect my machine</button>
+            <span class="hint" id="ram-hint">Or pick it above.</span>
+          </div>
+          <div id="hw-out" class="hw" hidden>
+            <p class="hw-estimate" id="hw-estimate"></p>
+            <dl class="hw-facts" id="hw-facts"></dl>
+            <p class="fine">A browser estimate, not an MLX benchmark. Browsers can't read unified memory size.</p>
+            <button type="button" id="full-bench" class="ghost small" disabled>Run 20-second GPU test</button>
+            <progress id="bench-progress" max="100" value="0" hidden></progress>
+            <p id="bench-out" class="fine" aria-live="polite"></p>
+          </div>
+          <p id="hw-error" class="note" hidden></p>
+        </fieldset>
+
+        <fieldset class="group">
+          <legend>Context length</legend>
+          <div class="chips tight" id="context-chips" role="radiogroup" aria-label="Context length"></div>
+        </fieldset>
+
+        <details class="more-filters" id="more-filters" open>
+        <summary>Family, size, quantization and priority</summary>
+        <fieldset class="group">
+          <legend>Model family</legend>
+          <div class="chips" id="family-chips" role="radiogroup" aria-label="Model family"></div>
+          <label class="more-family">
+            <span class="sr-only">More families</span>
+            <select id="family-more"><option value="">More families</option></select>
+          </label>
+        </fieldset>
+
+        <fieldset class="group">
+          <legend>Size</legend>
+          <div class="chips tight" id="size-chips" role="radiogroup" aria-label="Size"></div>
+        </fieldset>
+
+        <fieldset class="group">
+          <legend>Quantization</legend>
+          <div class="chips tight" id="quant-chips" role="radiogroup" aria-label="Quantization"></div>
+        </fieldset>
+
+        <fieldset class="group">
+          <legend>What matters most</legend>
+          <div class="chips" id="priority-chips" role="radiogroup" aria-label="Priority"></div>
+        </fieldset>
+
+        <fieldset class="group">
+          <label class="field">Name contains
+            <input type="search" id="search" maxlength="80" placeholder="coder, instruct, vl">
+          </label>
+          <label class="check"><input type="checkbox" id="non-llm"> Include speech, image and embedding models</label>
+        </fieldset>
+        </details>
+      </form>
+    </aside>
+
+    <section class="results" id="results" aria-labelledby="res-title">
+      <div class="results-head">
+        <div>
+          <h2 id="res-title">Models</h2>
+          <p id="summary" class="summary"></p>
+        </div>
+        <div class="tabs" role="tablist" aria-label="Sort" id="sort">
+          <button role="tab" data-sort="recommended" aria-selected="true">Best fit</button>
+          <button role="tab" data-sort="popular" aria-selected="false">Popular</button>
+          <button role="tab" data-sort="recent" aria-selected="false">Recent</button>
+          <button role="tab" data-sort="community" aria-selected="false">Community tested</button>
+          <button role="tab" data-sort="all" aria-selected="false">A–Z</button>
+        </div>
+      </div>
+      <div id="notices"></div>
+      <ol id="list" class="rows"></ol>
+      <button type="button" id="more" class="ghost wide" hidden>Show more models</button>
+    </section>
+  </div>
+
+  <div class="shell prose-grid">
+    <section id="benchmark" class="prose" aria-labelledby="bench-h">
+      <h2 id="bench-h">Measure a model on your Mac</h2>
+      <p>The GPU test above runs in your browser. This one runs MLX. The script loads a model with <code>mlx-lm</code>, measures prompt speed, generation speed, time to first token and peak memory, and prints the result. It sends nothing unless you add <code>--submit</code>, and it shows you the exact payload first.</p>
+      <label class="field">Model
+        <input id="bench-model" type="text" maxlength="200" value="mlx-community/Qwen3-0.6B-4bit" spellcheck="false">
+      </label>
+      <pre class="cmd"><code id="bench-cmd"></code></pre>
+      <div class="actions-row">
+        <button type="button" id="copy-cmd" class="ghost">Copy command</button>
+        <a href="/bench/mlx_explorer_bench.py" download>Download mlx_explorer_bench.py</a>
+      </div>
+      <details>
+        <summary>Paste a result you already ran</summary>
+        <textarea id="bench-json" rows="6" maxlength="4000" spellcheck="false" placeholder='{"event_type": "mlx_benchmark_submission", ...}'></textarea>
+        <button type="button" id="bench-submit" class="solid">Submit result</button>
+        <p id="bench-submit-out" class="fine" aria-live="polite"></p>
+      </details>
+    </section>
+
+    <section id="methodology" class="prose" aria-labelledby="meth-h">
+      <h2 id="meth-h">How it works</h2>
+      <details><summary>What does 4-bit mean?</summary>
+        <p>Quantization stores each weight with fewer bits. A 16-bit model uses about 2 bytes per parameter. A 4-bit model uses about half a byte, plus a scale and offset per group of 64 weights (roughly 4.5 bits in total). Fewer bits mean a smaller download and less memory, usually with some loss in quality that varies by model and method. <em>Mixed</em> models keep sensitive layers at higher precision and are labelled by their base width, e.g. "4-bit mixed".</p>
+      </details>
+      <details><summary>Why memory decides what runs</summary>
+        <p>On Apple Silicon the whole model must fit in the unified memory the GPU may use. By default macOS allows roughly two-thirds of RAM on Macs with 36 GB or less and about three-quarters on larger ones (adjustable with <code>sudo sysctl iogpu.wired_limit_mb=…</code>). A model that doesn't fit fails to load or crawls while swapping.</p>
+      </details>
+      <details><summary>Why context length matters</summary>
+        <p>Every token in context stores a key and a value for each attention layer: the KV cache, <code>2 × layers × kv_heads × head_dim × tokens × 2 bytes</code>. For an 8B model at 32k tokens that's about 4.5 GB, as much as its 4-bit weights. Sliding-window and linear-attention layers need far less. Weight quantization doesn't shrink the KV cache, and a model's maximum context comes from its architecture and training, not its quantization.</p>
+      </details>
+      <details><summary>What the browser GPU test measures</summary>
+        <p>A short WebGPU compute workload (matrix multiplications and a large buffer copy) that gives a relative score for grouping hardware. It is not MLX, not LLM inference and not tokens per second, and it varies with browser, power mode and background load.</p>
+      </details>
+      <details><summary>Where community numbers come from</summary>
+        <p>From people running the benchmark script on their own Macs, plus optional "how did it work" reports. Submissions are validated. Implausible values, such as generation faster than a Mac's memory bandwidth allows, are flagged and excluded from rankings.</p>
+      </details>
+      <details><summary>How "Best fit" is scored</summary>
+        <p>Each matching model gets a 0 to 100 score from these components, weighted by what matters most to you:</p>
+        <ul>
+          <li><strong>Fit:</strong> estimated weights (exact file sizes when available) + KV cache at your context + about 1 GB overhead, against GPU-usable memory. Comfortable under 70%, Likely under 85%, Borderline under 100%, Unlikely above.</li>
+          <li><strong>Quantization:</strong> quality prefers more bits, minimum memory prefers fewer, balanced prefers 4 to 6.</li>
+          <li><strong>Context:</strong> headroom left at your context, and whether the model's config supports that length.</li>
+          <li><strong>Capacity:</strong> among models that fit, more parameters usually means a more capable model. Ignored when you prioritize speed or least memory.</li>
+          <li><strong>Popularity</strong> (downloads and likes, log scale), <strong>recency</strong>, and <strong>community data</strong> once people contribute.</li>
+        </ul>
+        <p>The score never considers who uploaded a model or what it's called. Speed is never predicted without real measurements. Scoring version <code id="engine-version">heuristic-v1</code>. For knowledge-quality evaluations of models on MLX, see the <a href="https://huggingface.co/spaces/mlx-community/mlx-benchmark-leaderboard" target="_blank" rel="noopener">MLX Benchmark Leaderboard</a>.</p>
+      </details>
+    </section>
+
+    <section id="privacy" class="prose" aria-labelledby="priv-h">
+      <h2 id="priv-h">Privacy and data</h2>
+      <p>We collect anonymous model-selection and optional benchmark data to improve MLX Model Explorer and community recommendations. It's published as the <a id="dataset-link" href="https://huggingface.co/datasets/mlx-community/mlx-model-explorer-data" target="_blank" rel="noopener">mlx-model-explorer-data</a> dataset.</p>
+      <ul>
+        <li><strong>Collected:</strong> the filters you choose, models you open or compare, coarse hardware class (GPU vendor and architecture, core count, browser and OS family), test scores, and feedback you send.</li>
+        <li><strong>Never collected:</strong> name, email, IP address, location, cookies, user-agent strings or device fingerprints. Links, emails and phone numbers are stripped from notes.</li>
+        <li><strong>Session ID:</strong> random, lives only in this tab, and is gone when you close it.</li>
+        <li>The <a href="/stats">stats page</a> only shows groups of five or more.</li>
+      </ul>
+      <label class="check"><input type="checkbox" id="optout"> Don't send any data from this browser</label>
+      <p id="gpc-note" class="fine" hidden>Your browser sends a Global Privacy Control or Do Not Track signal, so nothing is sent unless you untick the box above.</p>
+    </section>
+  </div>
+</main>
+
+<footer class="shell foot">
+  <span>A community tool for <a href="https://github.com/ml-explore/mlx" target="_blank" rel="noopener">MLX</a> on Apple Silicon.</span>
+  <span id="cat-status"></span>
+  <span>Version <span id="app-version"></span></span>
+</footer>
+
+<div id="compare-tray" class="tray" hidden>
+  <span id="compare-count"></span>
+  <button type="button" id="compare-open" class="solid">Compare</button>
+  <button type="button" id="compare-clear" class="ghost">Clear</button>
+</div>
+
+<dialog id="detail" class="sheet" aria-labelledby="d-title">
+  <div class="sheet-head">
+    <h2 id="d-title"></h2>
+    <button type="button" class="close" data-close aria-label="Close">×</button>
+  </div>
+  <div id="d-body" class="sheet-body"></div>
+</dialog>
+
+<dialog id="compare" class="modal" aria-labelledby="c-title">
+  <div class="sheet-head">
+    <h2 id="c-title">Compare models</h2>
+    <button type="button" class="close" data-close aria-label="Close">×</button>
+  </div>
+  <div id="c-body" class="sheet-body"></div>
+</dialog>
+
+<template id="feedback-tpl">
+  <form class="feedback">
+    <h3>Have you tried this model?</h3>
+    <div class="chips">
+      <label class="chip"><input type="radio" name="tried" value="yes"><span>Yes</span></label>
+      <label class="chip"><input type="radio" name="tried" value="no"><span>No</span></label>
+      <label class="chip"><input type="radio" name="tried" value="planning"><span>Planning to</span></label>
+    </div>
+    <div class="fb-yes" hidden>
+      <h4>How did it work?</h4>
+      <div class="chips">
+        <label class="chip"><input type="radio" name="outcome" value="q:excellent"><span>Excellent</span></label>
+        <label class="chip"><input type="radio" name="outcome" value="q:good"><span>Good</span></label>
+        <label class="chip"><input type="radio" name="outcome" value="q:acceptable"><span>Acceptable</span></label>
+        <label class="chip"><input type="radio" name="outcome" value="f:too_slow"><span>Too slow</span></label>
+        <label class="chip"><input type="radio" name="outcome" value="f:too_much_memory"><span>Too much memory</span></label>
+        <label class="chip"><input type="radio" name="outcome" value="f:low_quality"><span>Quality wasn't good enough</span></label>
+        <label class="chip"><input type="radio" name="outcome" value="f:didnt_run"><span>Didn't run</span></label>
+      </div>
+      <div class="fb-grid">
+        <label class="field">Mac memory<select name="ram"><option value="">Optional</option></select></label>
+        <label class="field">Chip<select name="chip"><option value="">Optional</option></select></label>
+        <label class="field">Tokens per second<input name="tps" type="number" min="0.1" max="2000" step="0.1" inputmode="decimal" placeholder="Optional"></label>
+        <label class="field">Context used<select name="ctx"><option value="">Optional</option></select></label>
+      </div>
+      <label class="field">Notes, up to 280 characters, no personal info
+        <textarea name="notes" rows="2" maxlength="280"></textarea>
+      </label>
+    </div>
+    <div class="actions-row">
+      <button type="submit" class="solid">Send report</button>
+      <span class="fb-out fine" aria-live="polite"></span>
+    </div>
+  </form>
+</template>
+
+<script src="/static/webgpu.js"></script>
+<script src="/static/app.js"></script>
+</body>
+</html>

static/stats.html

@@ -0,0 +1,42 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Community stats · MLX Model Explorer</title>
+<meta name="color-scheme" content="light dark">
+<link rel="stylesheet" href="/static/styles.css">
+<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='7' fill='%2317212B'/%3E%3Crect x='6' y='13' width='11' height='6' rx='1.5' fill='%234F86C6'/%3E%3Crect x='17' y='13' width='5' height='6' rx='1.5' fill='%239C7FD6'/%3E%3Crect x='24.5' y='9' width='1.5' height='14' rx='.75' fill='%23fff'/%3E%3C/svg%3E">
+</head>
+<body>
+<header class="top">
+  <div class="shell top-row">
+    <a class="brand" href="/">
+      <svg class="brand-mark" viewBox="0 0 32 32" aria-hidden="true"><rect x="3" y="12" width="14" height="8" rx="2" class="fill-w"/><rect x="17" y="12" width="6" height="8" rx="2" class="fill-kv"/><rect x="26" y="7" width="2" height="18" rx="1" class="fill-limit"/></svg>
+      <span>MLX Model Explorer</span>
+    </a>
+    <nav aria-label="Sections">
+      <a href="/">Explorer</a>
+      <a id="ds" href="https://huggingface.co/datasets/mlx-community/mlx-model-explorer-data" target="_blank" rel="noopener">Dataset</a>
+    </nav>
+  </div>
+</header>
+<main class="shell">
+  <section class="stats-hero">
+    <h1>What the MLX community is trying to run</h1>
+    <p class="lede">Anonymous totals from MLX Model Explorer. Groups smaller than <span id="kmin">5</span> are combined into "other", flagged submissions are left out, and no individual record is shown.</p>
+  </section>
+  <div class="totals" id="totals"></div>
+  <section class="chart" aria-labelledby="q-h">
+    <h2 id="q-h">Quantization people search for</h2>
+    <div class="qshare" id="qshare" role="img" aria-label="Quantization share"></div>
+    <p class="scale-note" id="qshare-note"></p>
+    <p class="scale-note" id="avgctx"></p>
+  </section>
+  <div class="charts" id="charts"></div>
+  <p class="scale-note" id="updated"></p>
+</main>
+<footer class="shell foot"><span>MLX Model Explorer</span></footer>
+<script src="/static/stats.js"></script>
+</body>
+</html>

static/stats.js

@@ -0,0 +1,81 @@
+"use strict";
+
+(function () {
+  const $ = (s) => document.querySelector(s);
+  function el(tag, cls, text) {
+    const n = document.createElement(tag);
+    if (cls) n.className = cls;
+    if (text != null) n.textContent = text;
+    return n;
+  }
+  const LABELS = {
+    events: "Events", sessions: "Sessions", searches: "Searches", distinct_queries: "Distinct queries", model_views: "Models opened",
+    model_clicks: "Hugging Face visits", hardware_tests: "Hardware checks", browser_benchmarks: "GPU tests",
+    feedback: "Reports", mlx_benchmarks: "MLX benchmarks",
+  };
+  const CHARTS = [
+    ["families", "Model families"], ["sizes", "Model sizes"], ["ram_classes", "Mac memory (GB)"],
+    ["contexts", "Target context"], ["priorities", "What matters most"], ["selected_models", "Most compared and visited models"],
+    ["gpu_capability", "Browser GPU class"], ["webgpu_available", "WebGPU available"],
+  ];
+  const QCOLORS = { "2-bit": "#8a4f9e", "3-bit": "#7a5ab8", "4-bit": "#2f5d8c", "5-bit": "#3f7f86", "6-bit": "#2e7d4f", "8-bit": "#62802a" };
+  const fmtKey = (k) => (k === true ? "yes" : k === false ? "no" : typeof k === "number" && k >= 4096 ? `${Math.round(k / 1024)}k` : String(k));
+
+  function bars(items) {
+    const box = el("div", "bars");
+    if (!items.length) {
+      box.append(el("p", "scale-note", "Not enough data yet."));
+      return box;
+    }
+    const max = Math.max(...items.map((x) => x.count));
+    for (const it of items) {
+      const row = el("div", "bar");
+      const track = el("div", "track");
+      const fill = el("div", "fill");
+      fill.style.width = `${(it.count / max) * 100}%`;
+      track.append(fill);
+      const key = fmtKey(it.key);
+      const k = el("span", "k", key);
+      k.title = key;
+      row.append(k, track, el("span", "n", `${it.count.toLocaleString()} (${Math.round(it.share * 100)}%)`));
+      box.append(row);
+    }
+    return box;
+  }
+
+  async function load() {
+    let s;
+    try {
+      const r = await fetch("/api/stats");
+      if (!r.ok) throw new Error(String(r.status));
+      s = await r.json();
+    } catch (e) {
+      $("#updated").textContent = "Statistics couldn't be loaded. Refresh in a moment.";
+      return;
+    }
+    $("#kmin").textContent = s.k_min;
+    $("#totals").replaceChildren(...Object.entries(s.totals).map(([k, v]) => {
+      const d = el("div", "total");
+      d.append(el("b", null, v.toLocaleString()), el("span", null, LABELS[k] || k));
+      return d;
+    }));
+    const q = Object.entries(s.quant_share).filter(([, v]) => v);
+    const qs = $("#qshare");
+    qs.replaceChildren(...q.map(([k, v]) => {
+      const seg = el("span", null, v >= 0.08 ? `${k} ${Math.round(v * 100)}%` : "");
+      seg.style.width = `${v * 100}%`;
+      seg.style.background = QCOLORS[k] || "#7b8895";
+      seg.title = `${k}: ${Math.round(v * 100)}%`;
+      return seg;
+    }));
+    $("#qshare-note").textContent = q.length ? q.map(([k, v]) => `${k} ${Math.round(v * 100)}%`).join(", ") : "Not enough searches with a quantization filter yet.";
+    $("#avgctx").textContent = s.average_target_context ? `Average target context: ${Math.round(s.average_target_context / 1024)}k tokens.` : "";
+    $("#charts").replaceChildren(...CHARTS.map(([key, title]) => {
+      const c = el("section", "chart");
+      c.append(el("h2", null, title), bars(s[key] || []));
+      return c;
+    }));
+    $("#updated").textContent = `Updated ${new Date().toLocaleString()}.`;
+  }
+  load();
+})();

static/styles.css

@@ -0,0 +1,326 @@
+/* MLX Model Explorer
+   One idea carries the page: the memory budget. Everything else stays quiet. */
+
+:root {
+  --ground: #f2f4f6;
+  --surface: #ffffff;
+  --sunk: #e8ecf0;
+  --ink: #17212b;
+  --ink-2: #4a5866;
+  --ink-3: #7b8895;
+  --line: #d9dfe5;
+  --focus: #2f5d8c;
+
+  --weights: #2f5d8c;
+  --kv: #7a5ab8;
+  --overhead: #a3adb7;
+  --limit: #17212b;
+
+  --fit-comfortable: #2e7d4f;
+  --fit-likely: #62802a;
+  --fit-borderline: #b7791f;
+  --fit-unlikely: #b23a2e;
+
+  --display: ui-rounded, "SF Pro Rounded", "Nunito", system-ui, -apple-system, "Segoe UI", sans-serif;
+  --text: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", sans-serif;
+  --mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+
+  --r-lg: 18px;
+  --r-md: 10px;
+  --r-sm: 6px;
+  color-scheme: light;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --ground: #10161c;
+    --surface: #17202a;
+    --sunk: #1f2a35;
+    --ink: #e8edf2;
+    --ink-2: #b2bdc8;
+    --ink-3: #82909d;
+    --line: #2a3643;
+    --focus: #8fb6e6;
+    --weights: #4f86c6;
+    --kv: #9c7fd6;
+    --overhead: #5d6b78;
+    --limit: #e8edf2;
+    --fit-comfortable: #5fbf85;
+    --fit-likely: #a3c45a;
+    --fit-borderline: #e0a84a;
+    --fit-unlikely: #ec7a6c;
+    color-scheme: dark;
+  }
+}
+
+*, *::before, *::after { box-sizing: border-box; }
+html { -webkit-text-size-adjust: 100%; scroll-behavior: smooth; }
+@media (prefers-reduced-motion: reduce) { html { scroll-behavior: auto; } *, *::before, *::after { transition: none !important; animation: none !important; } }
+body { margin: 0; background: var(--ground); color: var(--ink); font: 15px/1.55 var(--text); font-variant-numeric: tabular-nums; }
+a { color: inherit; text-decoration-color: color-mix(in srgb, currentColor 40%, transparent); text-underline-offset: 3px; }
+a:hover { text-decoration-color: currentColor; }
+code, pre { font-family: var(--mono); font-size: 0.86em; }
+:not(pre) > code { background: var(--sunk); padding: 1px 5px; border-radius: 4px; }
+[hidden] { display: none !important; }
+.sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+.skip { position: absolute; left: -9999px; }
+.skip:focus { left: 12px; top: 12px; z-index: 50; background: var(--surface); padding: 8px 12px; border-radius: var(--r-sm); }
+:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; }
+
+.shell { width: 100%; max-width: 1240px; margin-inline: auto; padding-inline: 20px; }
+
+/* ---------------------------------------------------------------- header */
+.top { border-bottom: 1px solid var(--line); background: color-mix(in srgb, var(--ground) 85%, transparent);
+  position: sticky; top: 0; z-index: 20; backdrop-filter: saturate(1.4) blur(10px); -webkit-backdrop-filter: saturate(1.4) blur(10px); }
+.top-row { display: flex; align-items: center; justify-content: space-between; gap: 16px; min-height: 56px; flex-wrap: wrap; }
+.brand { display: inline-flex; align-items: center; gap: 10px; font: 600 16px/1 var(--display); text-decoration: none; letter-spacing: -0.01em; }
+.brand-mark { width: 26px; height: 26px; }
+.fill-w { fill: var(--weights); } .fill-kv { fill: var(--kv); } .fill-limit { fill: var(--limit); }
+.top nav { display: flex; gap: 18px; flex-wrap: wrap; font-size: 14px; }
+.top nav a { text-decoration: none; color: var(--ink-2); }
+.top nav a:hover { color: var(--ink); }
+
+/* ---------------------------------------------------------------- hero: the memory budget */
+.hero { display: grid; grid-template-columns: minmax(0, 5fr) minmax(0, 7fr); gap: 40px; align-items: end; padding-block: 44px 28px; }
+h1 { font: 600 clamp(30px, 4.2vw, 46px)/1.08 var(--display); letter-spacing: -0.025em; margin: 0 0 14px; max-width: 14ch; }
+.lede { color: var(--ink-2); margin: 0; max-width: 46ch; font-size: 16px; }
+.lede a { color: var(--ink); }
+
+.budget { margin: 0; background: var(--surface); border: 1px solid var(--line); border-radius: var(--r-lg); padding: 20px 22px 18px; }
+.budget-head { display: flex; justify-content: space-between; align-items: baseline; gap: 12px; flex-wrap: wrap; margin-bottom: 14px; }
+.budget-mac { font: 600 20px/1.2 var(--display); letter-spacing: -0.01em; }
+.budget-usable { color: var(--ink-3); font-size: 14px; }
+.budget-track { position: relative; height: 46px; border-radius: 12px; background:
+  repeating-linear-gradient(90deg, transparent 0 calc(12.5% - 1px), color-mix(in srgb, var(--line) 70%, transparent) calc(12.5% - 1px) 12.5%),
+  var(--sunk);
+  display: flex; overflow: hidden; }
+.seg { display: block; height: 100%; width: 0; transition: width 420ms cubic-bezier(.2, .8, .2, 1); }
+.seg-w { background: var(--weights); }
+.seg-kv { background: var(--kv); }
+.seg-oh { background: var(--overhead); }
+.budget-track.over .seg-oh { background: repeating-linear-gradient(135deg, var(--fit-unlikely) 0 6px, color-mix(in srgb, var(--fit-unlikely) 70%, transparent) 6px 12px); }
+.limit { position: absolute; top: -6px; bottom: -6px; width: 3px; margin-left: -1.5px; background: var(--limit); border-radius: 2px;
+  transition: left 420ms cubic-bezier(.2, .8, .2, 1); }
+.budget-foot { display: flex; justify-content: space-between; align-items: flex-start; gap: 10px 20px; flex-wrap: wrap; margin-top: 14px; }
+.budget-model { margin: 0; font-size: 14px; color: var(--ink-2); max-width: 58ch; }
+.budget-model strong { color: var(--ink); font-weight: 600; }
+.legend { list-style: none; margin: 0; padding: 0; display: flex; gap: 14px; flex-wrap: wrap; font-size: 12.5px; color: var(--ink-3); }
+.legend li { display: inline-flex; align-items: center; gap: 6px; }
+.sw { display: inline-block; width: 10px; height: 10px; border-radius: 3px; }
+.sw-limit { width: 3px; height: 13px; border-radius: 2px; background: var(--limit); }
+
+/* ---------------------------------------------------------------- workspace */
+.workspace { display: grid; grid-template-columns: 300px minmax(0, 1fr); gap: 32px; align-items: start; padding-bottom: 56px; }
+.rail { position: sticky; top: 72px; max-height: calc(100vh - 88px); overflow-y: auto; padding-right: 6px; scrollbar-width: thin; }
+.group { border: 0; margin: 0 0 22px; padding: 0; min-width: 0; }
+.group legend { font: 600 14px/1.3 var(--display); padding: 0; margin-bottom: 9px; }
+
+.chips { display: flex; flex-wrap: wrap; gap: 6px; }
+.chip, .chips > button { position: relative; display: inline-flex; }
+.chip input { position: absolute; opacity: 0; inset: 0; margin: 0; cursor: pointer; }
+.chip span, .chips > button {
+  display: inline-flex; align-items: center; gap: 6px; min-height: 32px; padding: 5px 11px; border-radius: 999px;
+  border: 1px solid var(--line); background: var(--surface); color: var(--ink-2); font: 500 13px/1.2 var(--text);
+  cursor: pointer; user-select: none; white-space: nowrap;
+}
+.chips.tight .chip span { padding-inline: 9px; }
+.chip span small { color: var(--ink-3); font-size: 11.5px; font-weight: 400; }
+.chip:hover span, .chips > button:hover { border-color: var(--ink-3); color: var(--ink); }
+.chip input:checked + span, .chips > button[aria-pressed="true"] { background: var(--ink); border-color: var(--ink); color: var(--surface); }
+.chip input:checked + span small { color: color-mix(in srgb, var(--surface) 70%, transparent); }
+.chip input:focus-visible + span { outline: 2px solid var(--focus); outline-offset: 2px; }
+
+.more-family { display: block; margin-top: 8px; }
+.more-filters > summary { display: none; }
+details.more-filters { border: 0; padding: 0; }
+.more-filters > *:not(summary) { margin-top: 0; }
+select, input[type="search"], input[type="text"], input[type="number"], textarea {
+  width: 100%; font: 400 14px/1.3 var(--text); color: var(--ink); background: var(--surface);
+  border: 1px solid var(--line); border-radius: var(--r-sm); padding: 8px 10px; min-height: 36px;
+}
+textarea { resize: vertical; font-family: var(--mono); font-size: 13px; }
+.field { display: flex; flex-direction: column; gap: 5px; font-size: 13px; font-weight: 500; color: var(--ink-2); margin-bottom: 10px; }
+.check { display: flex; align-items: flex-start; gap: 8px; font-size: 13.5px; color: var(--ink-2); cursor: pointer; }
+.check input { margin-top: 3px; accent-color: var(--ink); }
+
+button { font: inherit; color: inherit; }
+.ghost, .solid { display: inline-flex; align-items: center; justify-content: center; gap: 6px; min-height: 34px; padding: 6px 13px;
+  border-radius: var(--r-sm); font: 500 13.5px/1.2 var(--text); cursor: pointer; }
+.ghost { background: transparent; border: 1px solid var(--line); color: var(--ink); }
+.ghost:hover:not(:disabled) { border-color: var(--ink-3); background: var(--surface); }
+.solid { background: var(--ink); border: 1px solid var(--ink); color: var(--surface); }
+.solid:hover:not(:disabled) { background: color-mix(in srgb, var(--ink) 85%, var(--weights)); }
+button:disabled { opacity: .45; cursor: default; }
+.small { min-height: 30px; font-size: 12.5px; padding: 4px 10px; }
+.wide { width: 100%; margin-top: 14px; }
+
+.detect-row { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; margin-top: 10px; }
+.hint, .fine { font-size: 12.5px; color: var(--ink-3); margin: 0; }
+.hw { margin-top: 12px; padding: 12px; border-radius: var(--r-md); background: var(--sunk); }
+.hw-estimate { margin: 0 0 8px; font: 600 14px/1.35 var(--display); }
+.hw-facts { display: grid; grid-template-columns: auto 1fr; gap: 2px 12px; margin: 0 0 8px; font-size: 12.5px; }
+.hw-facts dt { color: var(--ink-3); }
+.hw-facts dd { margin: 0; }
+.hw .fine { margin-bottom: 8px; }
+progress { display: block; width: 100%; height: 6px; margin-top: 8px; accent-color: var(--weights); }
+.note { font-size: 13px; color: var(--ink); background: color-mix(in srgb, var(--fit-borderline) 14%, var(--surface));
+  border-radius: var(--r-sm); padding: 8px 10px; margin: 10px 0 0; }
+
+/* ---------------------------------------------------------------- results */
+.results-head { display: flex; justify-content: space-between; align-items: flex-end; gap: 12px 20px; flex-wrap: wrap; margin-bottom: 10px; }
+.results-head h2 { font: 600 22px/1.2 var(--display); margin: 0; letter-spacing: -0.01em; }
+.summary { margin: 2px 0 0; color: var(--ink-3); font-size: 13.5px; }
+.tabs { display: inline-flex; flex-wrap: wrap; gap: 2px; padding: 3px; border-radius: 10px; background: var(--sunk); }
+.tabs button { border: 0; background: transparent; color: var(--ink-2); padding: 6px 11px; border-radius: 7px; font-size: 13px; cursor: pointer; min-height: 30px; }
+.tabs button[aria-selected="true"] { background: var(--surface); color: var(--ink); box-shadow: 0 1px 2px rgba(23, 33, 43, .12); font-weight: 600; }
+#notices .note { margin: 0 0 8px; }
+
+.rows { list-style: none; margin: 8px 0 0; padding: 0; background: var(--surface); border: 1px solid var(--line); border-radius: var(--r-md); overflow: hidden; }
+.rows:empty { display: none; }
+.row { display: grid; grid-template-columns: minmax(0, 1fr) 190px; gap: 6px 22px; padding: 14px 18px; border-top: 1px solid var(--line); }
+.row:first-child { border-top: 0; }
+.row.active { background: color-mix(in srgb, var(--weights) 5%, var(--surface)); }
+.row-main { min-width: 0; }
+.row-title { display: flex; align-items: baseline; gap: 10px; flex-wrap: wrap; }
+.row-name { background: none; border: 0; padding: 0; margin: 0; cursor: pointer; text-align: left; font: 600 15.5px/1.3 var(--text);
+  color: var(--ink); word-break: break-word; }
+.row-name:hover { text-decoration: underline; text-underline-offset: 3px; }
+.row-org { color: var(--ink-3); font-weight: 400; }
+.facts { display: flex; flex-wrap: wrap; gap: 4px 14px; margin: 5px 0 0; font-size: 13px; color: var(--ink-2); }
+.facts .tag { color: var(--ink); font-weight: 500; }
+.facts .warn { color: var(--fit-borderline); }
+.why { margin: 7px 0 0; font-size: 13px; color: var(--ink-3); max-width: 72ch; }
+.row-actions { display: flex; gap: 14px; align-items: center; flex-wrap: wrap; margin-top: 8px; font-size: 13px; }
+.row-actions .check { font-size: 13px; align-items: center; }
+.row-actions .check input { margin-top: 0; }
+.row-actions a, .linkish { color: var(--ink-2); }
+.linkish { background: none; border: 0; padding: 0; cursor: pointer; text-decoration: underline; text-decoration-color: color-mix(in srgb, currentColor 40%, transparent); text-underline-offset: 3px; font-size: 13px; }
+
+.row-fit { display: flex; flex-direction: column; justify-content: center; gap: 6px; }
+.fit-line { display: flex; justify-content: space-between; align-items: baseline; gap: 8px; font-size: 13px; }
+.fit-gb { font: 600 17px/1 var(--display); color: var(--ink); }
+.fit-label { font-weight: 600; font-size: 12.5px; }
+.fit-Comfortable { color: var(--fit-comfortable); }
+.fit-Likely { color: var(--fit-likely); }
+.fit-Borderline { color: var(--fit-borderline); }
+.fit-Unlikely { color: var(--fit-unlikely); }
+.fit-none { color: var(--ink-3); font-weight: 400; }
+.score { font-size: 12px; color: var(--ink-3); }
+
+.mini { position: relative; display: flex; height: 10px; border-radius: 5px; background: var(--sunk); overflow: visible; }
+.mini .seg:first-child { border-radius: 5px 0 0 5px; }
+.mini .seg { transition: none; }
+.mini .limit { top: -3px; bottom: -3px; width: 2px; margin-left: -1px; transition: none; }
+.mini.over .seg-oh { background: var(--fit-unlikely); }
+
+/* ---------------------------------------------------------------- prose sections */
+.prose-grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 40px; padding-block: 44px 20px; border-top: 1px solid var(--line); }
+.prose h2 { font: 600 20px/1.25 var(--display); margin: 0 0 10px; letter-spacing: -0.01em; }
+.prose p, .prose li { font-size: 14px; color: var(--ink-2); max-width: 70ch; }
+.prose ul { padding-left: 18px; }
+.prose strong { color: var(--ink); }
+details { border-top: 1px solid var(--line); padding: 10px 0; }
+details:last-of-type { border-bottom: 1px solid var(--line); }
+summary { cursor: pointer; font-weight: 600; font-size: 14px; list-style: none; display: flex; justify-content: space-between; gap: 10px; }
+summary::-webkit-details-marker { display: none; }
+summary::after { content: "+"; color: var(--ink-3); font-weight: 400; }
+details[open] summary::after { content: "–"; }
+details > *:not(summary) { margin-top: 8px; }
+pre.cmd { background: var(--ink); color: var(--ground); padding: 14px 16px; border-radius: var(--r-md); overflow-x: auto; line-height: 1.6; margin: 10px 0; }
+@media (prefers-color-scheme: dark) { pre.cmd { background: #0a0f14; color: var(--ink); border: 1px solid var(--line); } }
+.actions-row { display: flex; align-items: center; gap: 14px; flex-wrap: wrap; margin-top: 8px; font-size: 13.5px; }
+
+.foot { display: flex; flex-wrap: wrap; gap: 6px 22px; padding-block: 18px 90px; font-size: 13px; color: var(--ink-3); border-top: 1px solid var(--line); }
+
+/* ---------------------------------------------------------------- compare tray */
+.tray { position: fixed; left: 50%; bottom: 18px; transform: translateX(-50%); z-index: 30; display: flex; align-items: center; gap: 10px;
+  padding: 8px 8px 8px 16px; border-radius: 12px; background: var(--ink); color: var(--surface); box-shadow: 0 8px 28px rgba(10, 20, 30, .28);
+  max-width: calc(100% - 32px); font-size: 14px; }
+.tray .ghost { color: var(--surface); border-color: color-mix(in srgb, var(--surface) 30%, transparent); }
+.tray .ghost:hover { background: transparent; border-color: var(--surface); }
+.tray .solid { background: var(--surface); color: var(--ink); border-color: var(--surface); }
+
+/* ---------------------------------------------------------------- dialogs */
+dialog { border: 0; padding: 0; color: var(--ink); background: var(--surface); }
+dialog::backdrop { background: rgba(12, 18, 24, .45); }
+dialog.sheet { margin: 0 0 0 auto; width: min(640px, 100vw); height: 100vh; max-height: 100vh; border-left: 1px solid var(--line); }
+dialog.sheet[open] { animation: sheet-in 260ms cubic-bezier(.2, .8, .2, 1); }
+@keyframes sheet-in { from { transform: translateX(24px); opacity: .6; } to { transform: none; opacity: 1; } }
+dialog.modal { width: min(980px, calc(100vw - 24px)); max-height: calc(100vh - 48px); border-radius: var(--r-lg); border: 1px solid var(--line); }
+.sheet-head { position: sticky; top: 0; z-index: 2; display: flex; justify-content: space-between; align-items: center; gap: 12px;
+  padding: 14px 20px; background: var(--surface); border-bottom: 1px solid var(--line); }
+.sheet-head h2 { margin: 0; font: 600 17px/1.3 var(--display); word-break: break-word; }
+.close { border: 1px solid var(--line); background: transparent; width: 34px; height: 34px; border-radius: 8px; font-size: 20px; line-height: 1; cursor: pointer; flex: none; }
+.sheet-body { padding: 18px 20px 28px; }
+.sheet-body h3 { font: 600 15px/1.3 var(--display); margin: 24px 0 10px; }
+.sheet-body h4 { font-size: 13.5px; margin: 14px 0 8px; }
+.sheet-lede { display: flex; flex-wrap: wrap; gap: 6px 16px; font-size: 13.5px; color: var(--ink-2); margin: 0 0 12px; }
+.kv { display: grid; grid-template-columns: max-content 1fr; gap: 4px 16px; font-size: 13.5px; margin: 0; }
+.kv dt { color: var(--ink-3); }
+.kv dd { margin: 0; word-break: break-word; }
+.why-list { margin: 0; padding-left: 18px; font-size: 13.5px; color: var(--ink-2); }
+.why-list li + li { margin-top: 4px; }
+
+.ctx-bars { display: grid; grid-template-columns: 44px minmax(0, 1fr) 64px 92px; gap: 9px 12px; align-items: center; font-size: 13px; }
+.ctx-bars .ctx { color: var(--ink-3); }
+.ctx-bars .cur { color: var(--ink); font-weight: 600; }
+.ctx-bars .gb { text-align: right; font-weight: 500; }
+.ctx-bars .mini { height: 12px; }
+.scale-note { font-size: 12.5px; color: var(--ink-3); margin: 10px 0 0; }
+
+.table-scroll { overflow-x: auto; border: 1px solid var(--line); border-radius: var(--r-md); }
+table { width: 100%; border-collapse: collapse; font-size: 13px; }
+th, td { text-align: left; padding: 8px 12px; border-top: 1px solid var(--line); vertical-align: top; }
+thead th { border-top: 0; color: var(--ink-3); font-weight: 500; white-space: nowrap; background: var(--sunk); }
+tbody th { color: var(--ink-3); font-weight: 500; white-space: nowrap; }
+td.num { text-align: right; }
+.compare-bar td .mini { min-width: 140px; }
+
+.feedback { margin-top: 26px; padding-top: 4px; border-top: 1px solid var(--line); }
+.fb-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 12px; margin-top: 12px; }
+.feedback .chips { margin-bottom: 4px; }
+
+/* ---------------------------------------------------------------- stats page */
+.stats-hero { padding-block: 40px 24px; }
+.stats-hero h1 { max-width: 20ch; }
+.totals { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 0; background: var(--surface); border: 1px solid var(--line); border-radius: var(--r-md); overflow: hidden; margin-bottom: 28px; }
+.total { padding: 14px 16px; border-right: 1px solid var(--line); border-bottom: 1px solid var(--line); margin-right: -1px; margin-bottom: -1px; }
+.total b { display: block; font: 600 26px/1.1 var(--display); }
+.total span { font-size: 12.5px; color: var(--ink-3); }
+.charts { display: grid; grid-template-columns: repeat(auto-fit, minmax(320px, 1fr)); gap: 28px 40px; padding-bottom: 40px; }
+.chart h2 { font: 600 16px/1.3 var(--display); margin: 0 0 10px; }
+.bars { display: grid; gap: 6px; }
+.bar { display: grid; grid-template-columns: minmax(80px, 38%) minmax(0, 1fr) 78px; gap: 10px; align-items: center; font-size: 13px; }
+.bar .k { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.bar .track { height: 10px; border-radius: 5px; background: var(--sunk); overflow: hidden; }
+.bar .fill { height: 100%; background: var(--weights); border-radius: 5px; }
+.bar .n { text-align: right; color: var(--ink-3); }
+.qshare { display: flex; height: 36px; border-radius: 10px; overflow: hidden; background: var(--sunk); margin: 6px 0 8px; }
+.qshare span { display: flex; align-items: center; justify-content: center; font-size: 12px; color: #fff; min-width: 0; overflow: hidden; white-space: nowrap; }
+
+/* ---------------------------------------------------------------- responsive */
+@media (max-width: 1080px) {
+  .prose-grid { grid-template-columns: minmax(0, 1fr); gap: 28px; }
+}
+@media (max-width: 900px) {
+  .hero { grid-template-columns: 1fr; gap: 24px; padding-top: 28px; }
+  h1 { max-width: none; }
+  .workspace { grid-template-columns: minmax(0, 1fr); gap: 20px; }
+  .rail { position: static; max-height: none; overflow: visible; padding: 16px; background: var(--surface); border: 1px solid var(--line); border-radius: var(--r-md); }
+  .group { margin-bottom: 16px; }
+  .more-filters { border-top: 1px solid var(--line); padding-top: 10px; }
+  .more-filters > summary { display: flex; margin-bottom: 4px; }
+  .more-filters[open] > summary { margin-bottom: 14px; }
+}
+@media (max-width: 600px) {
+  .shell { padding-inline: 16px; }
+  .top nav { gap: 12px; font-size: 13px; }
+  .budget { padding: 16px; }
+  .budget-track { height: 38px; }
+  .row { grid-template-columns: 1fr; padding: 14px; }
+  .row-fit { order: -1; }
+  .ctx-bars { grid-template-columns: 40px minmax(0, 1fr) 58px; }
+  .ctx-bars .fitc { grid-column: 2 / -1; margin-top: -6px; }
+  .fb-grid { grid-template-columns: 1fr; }
+  .tabs { width: 100%; }
+}

static/webgpu.js

@@ -0,0 +1,251 @@
+// Browser hardware estimate via WebGPU. This is NOT MLX and NOT LLM inference:
+// it measures relative GPU compute in this browser, for coarse hardware grouping.
+"use strict";
+
+(function () {
+  const BENCH_VERSION = "webgpu-1";
+
+  // Reference throughputs that map to a score of 1000 in each phase. They are
+  // fixed constants so scores stay comparable across versions of this file.
+  const REF = { mm256: 30, mm512: 30, mm1024: 30, copy: 20 }; // GFLOPS, GFLOPS, GFLOPS, GB/s
+
+  const MATMUL_WGSL = `
+    struct Dims { n : u32 }
+    @group(0) @binding(0) var<storage, read> a : array<f32>;
+    @group(0) @binding(1) var<storage, read> b : array<f32>;
+    @group(0) @binding(2) var<storage, read_write> c : array<f32>;
+    @group(0) @binding(3) var<uniform> dims : Dims;
+    @compute @workgroup_size(16, 16)
+    fn main(@builtin(global_invocation_id) id : vec3<u32>) {
+      let n = dims.n;
+      if (id.x >= n || id.y >= n) { return; }
+      var s = 0.0;
+      for (var k = 0u; k < n; k = k + 1u) {
+        s = s + a[id.y * n + k] * b[k * n + id.x];
+      }
+      c[id.y * n + id.x] = s;
+    }`;
+
+  function browserFamily() {
+    const ua = navigator.userAgent;
+    if (/Edg\//.test(ua)) return "edge";
+    if (/Firefox\//.test(ua)) return "firefox";
+    if (/Chrome\//.test(ua)) return "chrome";
+    if (/Safari\//.test(ua)) return "safari";
+    return "other";
+  }
+
+  function osFamily() {
+    const p = (navigator.userAgentData && navigator.userAgentData.platform) || navigator.platform || "";
+    const ua = navigator.userAgent;
+    if (/iPhone|iPad|iPod/.test(ua)) return "ios";
+    if (/Mac/i.test(p)) return navigator.maxTouchPoints > 1 ? "ios" : "macos";
+    if (/Win/i.test(p)) return "windows";
+    if (/Android/i.test(ua)) return "android";
+    if (/Linux/i.test(p)) return "linux";
+    return "other";
+  }
+
+  // Keep only short, generic identifiers ("apple", "metal-3"), never full descriptions.
+  function token(s) {
+    return (typeof s === "string" && /^[A-Za-z0-9 ._+-]{1,24}$/.test(s)) ? s.toLowerCase() : null;
+  }
+
+  function memoryPrior(deviceMemory) {
+    // Chrome reports RAM rounded DOWN to a power of two and capped (currently 32).
+    // So 16 means "16 to 31 GB" and 32 means "32 GB or more".
+    if (!deviceMemory) return null;
+    if (deviceMemory >= 32) return { ram: 32, label: "32 GB+ class", note: "your browser reports at least 32 GB" };
+    if (deviceMemory >= 16) return { ram: 16, label: "16 GB-class (16 to 31 GB)", note: "your browser reports 16 GB or more" };
+    if (deviceMemory >= 8) return { ram: 8, label: "8 GB-class (8 to 15 GB)", note: "your browser reports 8 GB or more" };
+    return { ram: 8, label: "8 GB-class or less", note: "your browser reports under 8 GB" };
+  }
+
+  function capabilityClass(quickScore) {
+    if (quickScore == null) return "unknown";
+    if (quickScore >= 4000) return "high";
+    if (quickScore >= 1500) return "mid";
+    return "entry";
+  }
+
+  const CLASS_LABEL = {
+    high: "Higher-tier GPU compute",
+    mid: "Mid-tier GPU compute",
+    entry: "Entry-level GPU compute",
+    unknown: "GPU compute unknown",
+  };
+
+  async function getDevice() {
+    if (!("gpu" in navigator) || !navigator.gpu) return { error: "unavailable" };
+    let adapter;
+    try {
+      adapter = await navigator.gpu.requestAdapter({ powerPreference: "high-performance" });
+    } catch (e) {
+      return { error: "unavailable" };
+    }
+    if (!adapter) return { error: "unavailable" };
+    try {
+      const device = await adapter.requestDevice();
+      device.lost.then(() => {});
+      return { adapter, device };
+    } catch (e) {
+      return { error: "device", adapter };
+    }
+  }
+
+  function makeMatmul(device, n) {
+    const size = n * n * 4;
+    const mk = (usage) => device.createBuffer({ size, usage });
+    const a = mk(GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const b = mk(GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const c = mk(GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC);
+    const u = device.createBuffer({ size: 4, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+    const data = new Float32Array(n * n);
+    for (let i = 0; i < data.length; i++) data[i] = ((i * 2654435761) % 1000) / 1000;
+    device.queue.writeBuffer(a, 0, data);
+    device.queue.writeBuffer(b, 0, data);
+    device.queue.writeBuffer(u, 0, new Uint32Array([n]));
+    const module = device.createShaderModule({ code: MATMUL_WGSL });
+    const pipeline = device.createComputePipeline({ layout: "auto", compute: { module, entryPoint: "main" } });
+    const bind = device.createBindGroup({
+      layout: pipeline.getBindGroupLayout(0),
+      entries: [a, b, c, u].map((buffer, i) => ({ binding: i, resource: { buffer } })),
+    });
+    const groups = Math.ceil(n / 16);
+    return {
+      async run(passes) {
+        const enc = device.createCommandEncoder();
+        for (let p = 0; p < passes; p++) {
+          const pass = enc.beginComputePass();
+          pass.setPipeline(pipeline);
+          pass.setBindGroup(0, bind);
+          pass.dispatchWorkgroups(groups, groups);
+          pass.end();
+        }
+        device.queue.submit([enc.finish()]);
+        await device.queue.onSubmittedWorkDone();
+      },
+      destroy() { [a, b, c, u].forEach((x) => x.destroy()); },
+    };
+  }
+
+  // Run matmul for ~ms milliseconds; returns GFLOPS (billions of multiply-adds per second).
+  async function timeMatmul(device, n, ms, onTick) {
+    const mm = makeMatmul(device, n);
+    try {
+      await mm.run(1); // warm-up + pipeline compile
+      let passes = 1, done = 0;
+      const t0 = performance.now();
+      while (performance.now() - t0 < ms) {
+        const s = performance.now();
+        await mm.run(passes);
+        done += passes;
+        if (performance.now() - s < 50) passes = Math.min(passes * 2, 4096);
+        if (onTick) onTick((performance.now() - t0) / ms);
+      }
+      const secs = (performance.now() - t0) / 1000;
+      return (done * n * n * n) / secs / 1e9;
+    } finally {
+      mm.destroy();
+    }
+  }
+
+  async function timeCopy(device, ms, onTick) {
+    const bytes = 256 * 1024 * 1024;
+    let src, dst;
+    try {
+      src = device.createBuffer({ size: bytes, usage: GPUBufferUsage.COPY_SRC | GPUBufferUsage.STORAGE });
+      dst = device.createBuffer({ size: bytes, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.STORAGE });
+    } catch (e) {
+      return null;
+    }
+    try {
+      let copies = 0;
+      const t0 = performance.now();
+      while (performance.now() - t0 < ms) {
+        const enc = device.createCommandEncoder();
+        for (let i = 0; i < 4; i++) enc.copyBufferToBuffer(src, 0, dst, 0, bytes);
+        device.queue.submit([enc.finish()]);
+        await device.queue.onSubmittedWorkDone();
+        copies += 4;
+        if (onTick) onTick((performance.now() - t0) / ms);
+      }
+      const secs = (performance.now() - t0) / 1000;
+      return (copies * bytes) / secs / 1e9;
+    } finally {
+      src.destroy();
+      dst.destroy();
+    }
+  }
+
+  let cached = null;
+
+  async function detect() {
+    const facts = {
+      browser_family: browserFamily(),
+      os_family: osFamily(),
+      cpu_cores: Number.isInteger(navigator.hardwareConcurrency) ? navigator.hardwareConcurrency : null,
+      device_memory: typeof navigator.deviceMemory === "number" ? navigator.deviceMemory : null,
+      webgpu_available: false,
+      gpu_vendor: null,
+      gpu_arch: null,
+      quick_score: null,
+      capability: "unknown",
+      duration_ms: 0,
+      error: null,
+    };
+    const t0 = performance.now();
+    const got = await getDevice();
+    if (got.adapter && got.adapter.info) {
+      facts.gpu_vendor = token(got.adapter.info.vendor);
+      facts.gpu_arch = token(got.adapter.info.architecture);
+    }
+    if (!got.device) {
+      facts.error = got.error || "unavailable";
+    } else {
+      facts.webgpu_available = true;
+      try {
+        const gflops = await timeMatmul(got.device, 256, 1200);
+        facts.quick_score = Math.round((gflops / REF.mm256) * 1000);
+        facts.capability = capabilityClass(facts.quick_score);
+      } catch (e) {
+        facts.error = "test_failed";
+      }
+      cached = got.device;
+    }
+    facts.duration_ms = Math.round(performance.now() - t0);
+    facts.memory_prior = memoryPrior(facts.device_memory);
+    facts.capability_label = CLASS_LABEL[facts.capability];
+    return facts;
+  }
+
+  async function fullBenchmark(onProgress) {
+    const device = cached || (await getDevice()).device;
+    if (!device) throw new Error("WebGPU isn't available in this browser.");
+    const phases = [
+      ["mm256", 4000, (t) => timeMatmul(device, 256, 4000, t)],
+      ["mm512", 6000, (t) => timeMatmul(device, 512, 6000, t)],
+      ["mm1024", 7000, (t) => timeMatmul(device, 1024, 7000, t)],
+      ["copy", 3000, (t) => timeCopy(device, 3000, t)],
+    ];
+    const total = phases.reduce((s, p) => s + p[1], 0);
+    let before = 0;
+    const raw = {};
+    const t0 = performance.now();
+    for (const [name, ms, fn] of phases) {
+      raw[name] = await fn((f) => onProgress && onProgress(Math.min(99, ((before + f * ms) / total) * 100), name));
+      before += ms;
+    }
+    const parts = Object.entries(raw).filter(([, v]) => v).map(([k, v]) => v / REF[k]);
+    const score = Math.round(Math.exp(parts.reduce((s, x) => s + Math.log(x), 0) / parts.length) * 1000);
+    if (onProgress) onProgress(100, "done");
+    return {
+      score,
+      raw: Object.fromEntries(Object.entries(raw).map(([k, v]) => [k, v && Math.round(v * 10) / 10])),
+      duration_ms: Math.round(performance.now() - t0),
+      version: BENCH_VERSION,
+    };
+  }
+
+  window.HW = { detect, fullBenchmark, BENCH_VERSION, capabilityClass };
+})();

tests/conftest.py

@@ -0,0 +1,6 @@
+import os
+import sys
+from pathlib import Path
+
+os.environ["EXPLORER_NO_AUTOAPP"] = "1"
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))

tests/test_api.py

@@ -0,0 +1,184 @@
+import time
+
+import httpx
+import pytest
+from fastapi.testclient import TestClient
+
+from app.catalogue import Catalogue
+from app.main import State, create_app
+from app.model_detail import DetailCache, ModelDetail
+from app.sink import LocalParquetSink
+
+from .test_parsing import QWEN3_8B_CONFIG
+
+LISTING = [
+    {"id": "mlx-community/Qwen3-8B-4bit", "downloads": 90000, "likes": 50, "lastModified": "2026-08-01T00:00:00Z",
+     "pipeline_tag": "text-generation", "safetensors": {"total": 8.19e9}, "tags": ["4-bit", "base_model:Qwen/Qwen3-8B"]},
+    {"id": "mlx-community/Qwen3-8B-8bit", "downloads": 30000, "likes": 10, "lastModified": "2026-07-01T00:00:00Z",
+     "pipeline_tag": "text-generation", "safetensors": {"total": 8.19e9}, "tags": ["8-bit", "base_model:Qwen/Qwen3-8B"]},
+    {"id": "mlx-community/Qwen3-14B-4bit", "downloads": 50000, "likes": 20, "lastModified": "2026-06-01T00:00:00Z",
+     "pipeline_tag": "text-generation", "safetensors": {"total": 14.8e9}, "tags": ["4-bit"]},
+    {"id": "mlx-community/Qwen3-mystery", "pipeline_tag": "text-generation", "tags": []},
+    {"id": "mlx-community/gemma-3-12b-it-4bit", "downloads": 70000, "pipeline_tag": "image-text-to-text",
+     "safetensors": {"total": 12e9}, "tags": ["4-bit"]},
+    {"id": "mlx-community/whisper-large-v3", "downloads": 99999, "pipeline_tag": "automatic-speech-recognition", "tags": []},
+    {"broken": True},
+    {"id": "mlx-community/secret-private-model", "private": True, "pipeline_tag": "text-generation", "tags": ["4-bit"]},
+]
+
+
+def fake_detail(mid):
+    if mid == "mlx-community/Qwen3-mystery":
+        return ModelDetail(mid, None, [], None, time.time(), error="config: HTTPStatusError")
+    return ModelDetail(mid, QWEN3_8B_CONFIG, [{"path": "model.safetensors", "size": 4_600_000_000}],
+                       4_600_000_000, time.time())
+
+
+@pytest.fixture
+def client(tmp_path):
+    cat = Catalogue(fetcher=lambda: LISTING, cache_dir=tmp_path)
+    cat.refresh()
+    st = State(catalogue=cat, details=DetailCache(fetch=fake_detail, cache_dir=tmp_path),
+               sink=LocalParquetSink(tmp_path / "ds", flush_seconds=999), fetch_live=False)
+    with TestClient(create_app(st)) as c:
+        c.st = st
+        yield c
+
+
+def test_healthz_and_meta(client):
+    h = client.get("/healthz").json()
+    assert h["ok"] and h["catalogue"]["models"] == 6 and h["catalogue"]["skipped_malformed"] == 2
+    m = client.get("/api/meta").json()
+    assert "Qwen" in [f["family"] for f in m["families"] + [{"family": "Qwen"}]]
+    assert 32768 in m["contexts"] and 36 in m["ram_classes"]
+
+
+def test_index_served_with_csp(client):
+    r = client.get("/")
+    assert r.status_code == 200 and "MLX Model Explorer" in r.text
+    assert "default-src 'self'" in r.headers["content-security-policy"]
+
+
+def test_recommend_flow(client):
+    r = client.post("/api/recommend", json={"family": "Qwen", "size": "8-15B", "quant": "4-bit",
+                                            "context": 32768, "ram_gb": 36, "ram_source": "confirmed",
+                                            "priority": "balanced"})
+    body = r.json()
+    ids = [x["model"]["id"] for x in body["results"]]
+    assert set(ids) == {"mlx-community/Qwen3-8B-4bit", "mlx-community/Qwen3-14B-4bit"}
+    top = body["results"][0]
+    assert top["memory"]["fit"] in ("Comfortable", "Likely") and top["reasons"]
+    assert top["model"]["url"].startswith("https://huggingface.co/mlx-community/")
+
+
+def test_llm_filter_and_unknowns(client):
+    body = client.post("/api/recommend", json={"family": "Qwen", "context": 8192}).json()
+    ids = {x["model"]["id"] for x in body["results"]}
+    assert "mlx-community/Qwen3-mystery" in ids and "mlx-community/whisper-large-v3" not in ids
+    mystery = next(x for x in body["results"] if x["model"]["id"] == "mlx-community/Qwen3-mystery")
+    assert mystery["model"]["quant_bucket"] == "unknown" and mystery["memory"]["total_gb"] is None
+    assert any("isn't available" in n for n in body["notices"])
+    allm = client.post("/api/recommend", json={"llm_only": False, "context": 8192}).json()
+    assert allm["total"] == 6
+
+
+def test_sorts(client):
+    pop = client.post("/api/recommend", json={"family": "Qwen", "sort": "popular"}).json()
+    dls = [x["model"]["downloads"] for x in pop["results"]]
+    assert dls == sorted(dls, reverse=True)
+    rec = client.post("/api/recommend", json={"family": "Qwen", "sort": "recent"}).json()
+    assert rec["results"][0]["model"]["id"] == "mlx-community/Qwen3-8B-4bit"
+
+
+def test_bad_recommend_inputs(client):
+    assert client.post("/api/recommend", json={"context": 12345}).status_code == 422
+    assert client.post("/api/recommend", json={"priority": "evil"}).status_code == 422
+    assert client.post("/api/recommend", json={"ram_gb": -3}).status_code == 422
+    assert client.post("/api/recommend", json={"family": "NoSuchFamily"}).json()["total"] == 0
+
+
+def test_model_detail(client):
+    d = client.get("/api/model/mlx-community/Qwen3-8B-4bit", params={"ram_gb": 16, "context": 32768}).json()
+    assert len(d["memory_by_context"]) == 7
+    assert [s["model"]["id"] for s in d["siblings"]] == ["mlx-community/Qwen3-8B-8bit"]
+    assert d["memory"]["weights_source"] == "files"
+    assert client.get("/api/model/mlx-community/nope").status_code == 404
+    junk = client.get("/api/model/mlx-community/Qwen3-8B-4bit", params={"context": 3, "priority": "x"})
+    assert junk.status_code == 200
+
+
+def test_events_ingest_to_parquet(client, tmp_path):
+    sid = "abcdef0123456789"
+    batch = {"events": [
+        {"event_type": "search", "session_id": sid, "model_family": "Qwen", "quantization": "4-bit",
+         "target_context": 32768, "priority": "balanced", "hardware_source": "confirmed", "hardware_memory_class": 36},
+        {"event_type": "model_select", "session_id": sid, "selected_model": "mlx-community/Qwen3-8B-4bit",
+         "selected_model_rank": 0, "target_context": 32768, "hardware_memory_class": 36},
+        {"event_type": "feedback", "session_id": sid, "selected_model": "mlx-community/Qwen3-8B-4bit",
+         "tried": "yes", "quality_rating": "good", "notes": "worked fine, email me x@y.com"},
+    ]}
+    r = client.post("/api/events", json=batch)
+    assert r.status_code == 202 and r.json()["accepted"] == 3
+    assert client.st.sink.flush()
+    rows = client.st.sink.read_existing()
+    assert [x["event_type"] for x in rows] == ["search", "model_select", "feedback"]
+    assert rows[1]["hf_downloads_at_selection"] == 90000
+    assert "x@y.com" not in rows[2]["notes"]
+    stats = client.get("/api/stats").json()
+    assert stats["totals"]["events"] == 3 and stats["totals"]["sessions"] == 1
+    assert stats["families"] == [{"key": "other", "count": 1, "share": 1.0}]  # k-anonymity folds tiny buckets
+
+
+def test_events_reject_malformed(client):
+    assert client.post("/api/events", content=b"not json", headers={"content-type": "application/json"}).status_code == 400
+    assert client.post("/api/events", json={"events": [{"event_type": "hack"}]}).status_code == 422
+    assert client.post("/api/events", json={"events": [{"event_type": "search", "extra": 1}]}).status_code == 422
+    big = b'{"events": [' + b'{"event_type":"search"},' * 5000 + b'{"event_type":"search"}]}'
+    assert client.post("/api/events", content=big, headers={"content-type": "application/json"}).status_code == 413
+    assert client.st.sink.pending == 0
+
+
+def test_rate_limit(client):
+    client.st.limiter.burst = 3
+    client.st.limiter._buckets.clear()
+    codes = [client.post("/api/events", json={"events": [{"event_type": "search"}]}).status_code for _ in range(8)]
+    assert 429 in codes
+
+
+def test_hub_failure_falls_back_to_snapshot(tmp_path):
+    def boom():
+        raise httpx.ConnectError("hub unreachable")
+
+    cat = Catalogue(fetcher=boom, cache_dir=tmp_path)
+    cat.refresh()
+    assert cat.source == "snapshot" and len(cat.records) > 1000 and cat.last_error
+    st = State(catalogue=cat, details=DetailCache(fetch=fake_detail, cache_dir=tmp_path),
+               sink=LocalParquetSink(tmp_path / "ds", flush_seconds=999), fetch_live=False)
+    with TestClient(create_app(st)) as c:
+        body = c.post("/api/recommend", json={"family": "Qwen", "quant": "4-bit"}).json()
+        assert body["total"] > 0 and any("cached copy" in n for n in body["notices"])
+        assert c.get("/healthz").json()["catalogue"]["degraded"]
+
+
+def test_collection_disabled(client):
+    client.st.collection_enabled = False
+    r = client.post("/api/events", json={"events": [{"event_type": "search"}]})
+    assert r.json() == {"accepted": 0} and client.st.sink.pending == 0
+
+
+def test_stats_dedupe_and_suppression():
+    from app.stats import compute
+    rows = []
+    for i in range(6):
+        sid = f"{i:016x}"
+        for _ in range(3):  # the same query re-rendered three times counts once
+            rows.append({"event_type": "filter", "session_id": sid, "model_family": "Qwen", "quantization": "4-bit",
+                         "target_context": 8192, "hardware_memory_class": 36, "suspicious_flags": []})
+    rows.append({"event_type": "search", "session_id": "ffffffffffffffff", "model_family": "Rare",
+                 "quantization": "3-bit", "suspicious_flags": []})
+    rows.append({"event_type": "search", "model_family": "Flagged", "suspicious_flags": ["unknown_model"]})
+    s = compute(rows)
+    assert s["totals"]["distinct_queries"] == 7
+    assert s["families"] == [{"key": "Qwen", "count": 6, "share": 0.8571}, {"key": "other", "count": 1, "share": 0.1429}]
+    assert s["ram_classes"][0] == {"key": 36, "count": 6, "share": 1.0}
+    assert all(f["key"] != "Flagged" for f in s["families"])

tests/test_events.py

@@ -0,0 +1,101 @@
+import pytest
+from pydantic import ValidationError
+
+from app.catalogue import Catalogue, build_record
+from app.events import COLUMNS, ClientEvent, EventBatch, clean_notes, to_row
+
+SID = "0123456789abcdef"
+
+
+class FakeCatalogue:
+    def __init__(self, recs):
+        self.by_id = {r.id: r for r in recs}
+
+
+CAT = FakeCatalogue([
+    build_record({"id": "mlx-community/Qwen3-8B-4bit", "downloads": 42, "likes": 3,
+                  "safetensors": {"total": 8.19e9}, "tags": ["4-bit"], "pipeline_tag": "text-generation"}),
+    build_record({"id": "mlx-community/Llama-3.3-70B-Instruct-4bit", "safetensors": {"total": 70e9},
+                  "tags": ["4-bit"], "pipeline_tag": "text-generation"}),
+])
+
+
+def ev(**kw):
+    return ClientEvent(**{"event_type": "search", "session_id": SID, **kw})
+
+
+def test_valid_search_row_has_all_columns_and_no_pii():
+    row = to_row(ev(model_family="Qwen", parameter_bucket="8-15B", quantization="4-bit",
+                    target_context=32768, priority="balanced", hardware_source="confirmed",
+                    hardware_memory_class=36), CAT)
+    assert set(row) == set(COLUMNS)
+    assert row["hardware_confirmed"] is True and row["suspicious_flags"] == []
+    assert row["timestamp"].endswith("Z") and "." not in row["timestamp"]
+    for forbidden in ("ip", "user_agent", "email", "name", "cookie"):
+        assert forbidden not in row
+
+
+def test_server_fills_catalogue_facts():
+    row = to_row(ev(event_type="model_select", selected_model="mlx-community/Qwen3-8B-4bit",
+                    selected_model_rank=0), CAT)
+    assert row["hf_downloads_at_selection"] == 42 and row["quant_bits"] == 4
+    assert row["model_family"] == "Qwen" and row["parameter_bucket"] == "8-15B"
+
+
+@pytest.mark.parametrize("bad", [
+    {"event_type": "delete_everything"},
+    {"event_type": "search", "session_id": "NOT-HEX"},
+    {"event_type": "search", "target_context": 12345},
+    {"event_type": "search", "hardware_memory_class": 17},
+    {"event_type": "search", "quantization": "7-bit"},
+    {"event_type": "feedback", "reported_tokens_per_second": -1},
+    {"event_type": "feedback", "reported_tokens_per_second": 99999},
+    {"event_type": "search", "selected_model": "../../etc/passwd"},
+    {"event_type": "search", "selected_model": "<script>/x"},
+    {"event_type": "mlx_benchmark_submission", "chip": "Intel i9"},
+    {"event_type": "search", "ip": "1.2.3.4"},
+    {"event_type": "search", "model_family": "<img src=x>"},
+    {"event_type": "search", "benchmark_version": "1.0; rm -rf"},
+    {"event_type": "search", "compare_models": ["a/b"] * 6},
+])
+def test_rejects_malformed(bad):
+    with pytest.raises(ValidationError):
+        ClientEvent(**bad)
+
+
+def test_batch_limits():
+    with pytest.raises(ValidationError):
+        EventBatch(events=[])
+    with pytest.raises(ValidationError):
+        EventBatch(events=[{"event_type": "search"}] * 51)
+
+
+def test_notes_are_scrubbed_and_capped():
+    n = clean_notes("mail me a@b.com\x00 see https://evil.example/x or call +1 (555) 123-4567 " + "z" * 500)
+    assert "a@b.com" not in n and "https" not in n and "555" not in n and "\x00" not in n
+    assert len(n) <= 280
+    assert clean_notes("   ") is None
+    e = ev(event_type="feedback", notes="<script>alert(1)</script>")
+    assert e.notes == "<script>alert(1)</script>"  # stored as inert text; UI renders textContent only
+
+
+def test_flags_unknown_model_and_implausible_tps():
+    row = to_row(ev(event_type="mlx_benchmark_submission", selected_model="mlx-community/Nope-1B",
+                    generation_tps=10, benchmark_version="1", benchmark_type="mlx_lm"), CAT)
+    assert "unknown_model" in row["suspicious_flags"]
+    row = to_row(ev(event_type="mlx_benchmark_submission", selected_model="mlx-community/Llama-3.3-70B-Instruct-4bit",
+                    generation_tps=1500, benchmark_version="1", benchmark_type="mlx_lm"), CAT)
+    assert "implausible_tps" in row["suspicious_flags"]
+    row = to_row(ev(event_type="mlx_benchmark_submission", selected_model="mlx-community/Qwen3-8B-4bit",
+                    generation_tps=45, benchmark_version="1", benchmark_type="mlx_lm", peak_memory_gb=5.1,
+                    reported_ram_gb=36), CAT)
+    assert row["suspicious_flags"] == []
+
+
+def test_flags_other_inconsistencies():
+    row = to_row(ev(event_type="mlx_benchmark_submission", peak_memory_gb=40, reported_ram_gb=16), CAT)
+    assert {"peak_memory_exceeds_ram", "incomplete_benchmark"} <= set(row["suspicious_flags"])
+    row = to_row(ev(event_type="feedback", tried="yes", quality_rating="good", failure_reason="too_slow"), CAT)
+    assert "conflicting_feedback" in row["suspicious_flags"]
+    row = to_row(ev(event_type="browser_benchmark", benchmark_type="mlx_lm"), CAT)
+    assert "benchmark_type_mismatch" in row["suspicious_flags"]

tests/test_memory.py

@@ -0,0 +1,50 @@
+from app.memory import GB, estimate, fit_class, kv_cache_bytes, usable_gpu_bytes, weights_bytes
+from app.parsing import detect_arch
+
+from .test_parsing import QWEN3_8B_CONFIG
+
+
+def test_kv_cache_qwen3_8b_32k_by_hand():
+    # 2 (K,V) * 36 layers * 8 kv heads * 128 head_dim * 32768 tokens * 2 bytes
+    expected = 2 * 36 * 8 * 128 * 32768 * 2
+    kv, upper = kv_cache_bytes(detect_arch(QWEN3_8B_CONFIG), 32768)
+    assert kv == expected and not upper
+    assert round(kv / GB, 2) == 4.5
+
+
+def test_sliding_window_caps_kv():
+    cfg = {"num_hidden_layers": 4, "num_attention_heads": 8, "num_key_value_heads": 8, "head_dim": 64,
+           "sliding_window": 128, "layer_types": ["sliding_attention", "full_attention"] * 2}
+    arch = detect_arch(cfg)
+    per = 2 * 8 * 64 * 2
+    kv, _ = kv_cache_bytes(arch, 32768)
+    assert kv == 2 * 32768 * per + 2 * 128 * per
+
+
+def test_missing_config_is_flagged_rough():
+    est = estimate(params=8e9, bits=4, mode="affine", file_bytes=None, arch=detect_arch(None),
+                   context=32768, ram_gb=16)
+    assert est.kv_rough and est.kv_gb and est.weights_source == "params"
+
+
+def test_weights_prefer_files():
+    assert weights_bytes(4_619_257_828, 8e9, 4) == (4_619_257_828, "files")
+    b, src = weights_bytes(None, 8e9, 4)
+    assert src == "params" and abs(b / 1e9 - 4.5) < 0.01
+    assert weights_bytes(None, None, 4) == (None, "unknown")
+
+
+def test_usable_memory_and_fit():
+    assert usable_gpu_bytes(16) < usable_gpu_bytes(24) < usable_gpu_bytes(64)
+    assert fit_class(int(5 * GB), 36) == "Comfortable"
+    assert fit_class(int(12 * GB), 16) == "Unlikely"
+    assert fit_class(None, 16) is None and fit_class(int(GB), None) is None
+
+
+def test_context_changes_estimate_and_model_limit():
+    arch = detect_arch(QWEN3_8B_CONFIG)
+    small = estimate(params=8e9, bits=4, mode=None, file_bytes=None, arch=arch, context=4096, ram_gb=16)
+    big = estimate(params=8e9, bits=4, mode=None, file_bytes=None, arch=arch, context=131072, ram_gb=16)
+    assert big.total_gb > small.total_gb
+    assert small.fit in ("Comfortable", "Likely") and big.fit == "Unlikely"
+    assert big.exceeds_model_context and not small.exceeds_model_context

tests/test_parsing.py

@@ -0,0 +1,186 @@
+import gzip
+import json
+from pathlib import Path
+
+import pytest
+
+from app.catalogue import build_record
+from app.parsing import (
+    detect_arch, detect_family, detect_params, detect_quant, param_bucket, quant_bucket,
+)
+
+QWEN3_8B_CONFIG = {
+    "architectures": ["Qwen3ForCausalLM"], "model_type": "qwen3", "head_dim": 128, "hidden_size": 4096,
+    "max_position_embeddings": 40960, "num_attention_heads": 32, "num_hidden_layers": 36,
+    "num_key_value_heads": 8, "quantization": {"group_size": 64, "bits": 4}, "sliding_window": None,
+    "use_sliding_window": False,
+}
+
+
+@pytest.mark.parametrize("mid,tags,family", [
+    ("mlx-community/Qwen3.8-27B-4bit", ["base_model:Qwen/Qwen3.8-27B"], "Qwen"),
+    ("mlx-community/Josiefied-Qwen3-8B-abliterated-v1-4bit", [], "Qwen"),
+    ("mlx-community/Meta-Llama-3.1-8B-Instruct-4bit", [], "Llama"),
+    ("mlx-community/gemma-4-31B-it-qat-4bit", [], "Gemma"),
+    ("mlx-community/Devstral-Small-2507-4bit", [], "Mistral"),
+    ("mlx-community/DeepSeek-V4-Flash-2bit", [], "DeepSeek"),
+    ("mlx-community/Kimi-K2-Instruct-4bit", [], "Kimi"),
+    ("mlx-community/NVIDIA-Nemotron-3-Nano-4bit", [], "Nemotron"),
+    ("mlx-community/Zorblax-7B-4bit", [], "Zorblax"),  # never seen before -> still a family
+    ("mlx-community/7B", [], "Other"),
+    ("mlx-community/functiongemma-270m-it-4bit", [], "Gemma"),
+    ("mlx-community/OLMoE-1B-7B-0924-Instruct-4bit", [], "OLMo"),
+    ("mlx-community/Instruct-Zorblax-7B", [], "Zorblax"),
+    ("mlx-community/Starling-LM-7B-beta", [], "Starling"),
+])
+def test_family(mid, tags, family):
+    assert detect_family(mid, tags) == family
+
+
+def test_family_ignores_junk_tags():
+    assert detect_family("mlx-community/Qwen3-8B-4bit", [None, 5, "base_model:"]) == "Qwen"
+
+
+def test_params_prefers_safetensors_then_name():
+    p = detect_params("mlx-community/Qwen3-8B-4bit", {"total": 8_190_735_360})
+    assert p.source == "safetensors" and param_bucket(p.total) == "8-15B"
+    p = detect_params("mlx-community/Qwen3-8B-4bit", None)
+    assert p.source == "name" and p.total == 8e9 and param_bucket(p.total) == "8-15B"
+
+
+def test_params_moe():
+    p = detect_params("mlx-community/Qwen3-30B-A3B-4bit", {"total": 30.5e9})
+    assert p.moe and p.active == 3e9 and param_bucket(p.total) == "15-35B"
+    p = detect_params("mlx-community/Mixtral-8x7B-Instruct-v0.1", None)
+    assert p.moe and p.total == 56e9
+    p = detect_params("mlx-community/whatever-4bit", None, {"num_local_experts": 8})
+    assert p.moe
+
+
+@pytest.mark.parametrize("st", [None, {}, {"total": "big"}, {"total": -1}, "junk"])
+def test_params_unknown(st):
+    p = detect_params("mlx-community/mystery-model-4bit", st)
+    assert p.total is None and p.source == "unknown" and param_bucket(p.total) is None
+
+
+def test_quant_tags():
+    q = detect_quant("mlx-community/Qwen3-8B", ["4-bit"])
+    assert (q.bits, q.source, q.mixed, quant_bucket(q)) == (4, "tags", False, "4-bit")
+
+
+def test_quant_mixed_from_tags_and_config():
+    q = detect_quant("mlx-community/Qwen3.5-9B-OptiQ-4bit", ["4bit", "8bit", "4-bit"])
+    assert q.bits == 4 and q.mixed and q.label == "4-bit mixed" and quant_bucket(q) == "4-bit"
+    cfg = {"model_type": "x", "quantization": {"bits": 4, "group_size": 64,
+                                               "model.layers.0.mlp": {"bits": 8, "group_size": 64}}}
+    q = detect_quant("mlx-community/foo", [], cfg)
+    assert q.bits == 4 and q.mixed and q.source == "config"
+
+
+def test_quant_config_beats_name():
+    q = detect_quant("mlx-community/foo-8bit", ["8-bit"], QWEN3_8B_CONFIG)
+    assert q.bits == 4 and q.source == "config"
+
+
+@pytest.mark.parametrize("name,bits,mode", [
+    ("gpt-oss-20b-MXFP4-Q8", 4, "mxfp4"),
+    ("Qwen3-30B-A3B-nvfp4", 4, "nvfp4"),
+    ("Qwen3-14B-4bit-DWQ", 4, "dwq"),
+    ("Llama-3.2-3B-Instruct-bf16", 16, "float"),
+    ("Mistral-7B-Instruct-v0.2-8-bit-mlx", 8, "affine"),
+    ("llama2-13b-qnt4bit", 4, "affine"),
+    ("Yi-9B-q", None, None),
+])
+def test_quant_names(name, bits, mode):
+    q = detect_quant(f"mlx-community/{name}", [])
+    assert q.bits == bits and q.mode == mode
+
+
+def test_quant_unquantized_config():
+    q = detect_quant("mlx-community/phi-2", [], {"model_type": "phi", "torch_dtype": "float16"})
+    assert q.bits == 16 and q.label == "16-bit"
+
+
+@pytest.mark.parametrize("cfg", [None, "junk", {}, {"quantization": "4"}, {"quantization": {"bits": "x"}}])
+def test_quant_junk_config(cfg):
+    q = detect_quant("mlx-community/mystery", [], cfg)
+    assert q.bits is None and q.label == "unknown"
+
+
+def test_arch_standard():
+    a = detect_arch(QWEN3_8B_CONFIG)
+    assert a.known and (a.layers, a.full_attention_layers, a.kv_heads, a.head_dim) == (36, 36, 8, 128)
+    assert a.sliding_layers == 0 and a.max_context == 40960
+
+
+def test_arch_hybrid_linear_attention():
+    cfg = {"text_config": {"num_hidden_layers": 8, "num_attention_heads": 16, "num_key_value_heads": 4,
+                           "head_dim": 256, "layer_types": ["linear_attention"] * 3 + ["full_attention"]
+                           + ["linear_attention"] * 3 + ["full_attention"]}}
+    a = detect_arch(cfg)
+    assert a.full_attention_layers == 2 and a.sliding_layers == 0
+
+
+def test_arch_sliding():
+    cfg = {"num_hidden_layers": 4, "num_attention_heads": 8, "num_key_value_heads": 8, "head_dim": 64,
+           "sliding_window": 128, "layer_types": ["sliding_attention", "full_attention"] * 2}
+    a = detect_arch(cfg)
+    assert (a.full_attention_layers, a.sliding_layers, a.sliding_window) == (2, 2, 128)
+
+
+@pytest.mark.parametrize("cfg", [None, {}, {"num_hidden_layers": "x"}, {"num_hidden_layers": True}])
+def test_arch_unknown(cfg):
+    assert not detect_arch(cfg).known
+
+
+@pytest.mark.parametrize("raw", [{}, {"id": 5}, {"id": "noslash"}, {"id": "a/b", "tags": "notalist"},
+                                 {"id": "a/b", "downloads": "many", "safetensors": [1]}])
+def test_build_record_never_raises(raw):
+    rec = build_record(raw)
+    assert rec is None or rec.id == "a/b"
+
+
+def test_snapshot_parses_fully():
+    path = Path(__file__).resolve().parent.parent / "data" / "catalogue_snapshot.json.gz"
+    raw = json.load(gzip.open(path, "rt"))
+    recs = [r for r in map(build_record, raw) if r]
+    assert len(recs) == len(raw) > 1000
+    llm = [r for r in recs if r.is_llm]
+    known_quant = sum(r.quant_bucket != "unknown" for r in llm) / len(llm)
+    known_size = sum(r.size_bucket is not None for r in llm) / len(llm)
+    assert known_quant > 0.9 and known_size > 0.95
+
+
+def test_partial_repo_detected():
+    p = detect_params("mlx-community/Qwen3.8-27B-MTP-4bit", {"total": 424_699_392})
+    assert p.partial and p.total == 424_699_392 and p.name_total == 27e9
+    assert not detect_params("mlx-community/Qwen3-8B-4bit", {"total": 8.19e9}).partial
+    assert not detect_params("mlx-community/Qwen3-30B-A3B-4bit", {"total": 30.5e9}).partial
+
+
+def test_packed_param_counts_are_unpacked():
+    st = {"parameters": {"F16": 244_584_448, "U32": 977_272_832}, "total": 1_221_857_280}
+    p = detect_params("mlx-community/EXAONE-3.5-7.8B-Instruct-4bit", st, bits=4)
+    assert abs(p.total / 1e9 - 7.82) < 0.05 and not p.partial and param_bucket(p.total) == "3-8B"
+    st6 = {"parameters": {"F16": 244_584_448, "U32": 1_465_909_248}, "total": 1_710_493_696}
+    assert abs(detect_params("mlx-community/x-6bit", st6, bits=6).total / 1e9 - 7.82) < 0.05
+    big = {"parameters": {"F16": 3_468_959_744, "U32": 8_879_865_856}, "total": 12_348_825_600}
+    assert 71e9 < detect_params("mlx-community/Liberated-Qwen1.5-72B-4bit", big, bits=4).total < 74e9
+    new_style = {"parameters": {"U32": 8_190_427_136, "BF16": 308_224}, "total": 8_190_735_360}
+    assert detect_params("mlx-community/Qwen3-8B-4bit", new_style, bits=4).total == 8_190_735_360
+    # packed counts but no bit width: keep the Hub total, the partial check flags the mismatch
+    p = detect_params("mlx-community/EXAONE-3.5-7.8B-Instruct", st, bits=None)
+    assert p.total == st["total"] and p.partial
+    # vision-language models have lots of unquantized float weights but are unpacked
+    vl = {"parameters": {"U32": 7_615_283_200, "F16": 676_883_456}, "total": 8_292_166_656}
+    assert detect_params("mlx-community/Qwen2.5-VL-7B-Instruct-4bit", vl, bits=4).total == vl["total"]
+    vl2 = {"parameters": {"U32": 4_022_272_000, "BF16": 415_543_808}, "total": 4_437_815_808}
+    assert detect_params("mlx-community/some-vlm-4bit", vl2, bits=4).total == vl2["total"]
+    assert detect_params("mlx-community/some-vlm-8bit", vl2, bits=8).total == vl2["total"]
+    assert abs(detect_params("mlx-community/unnamed-4bit", st, bits=4).total / 1e9 - 7.82) < 0.05
+
+
+def test_unknown_quantization_format_does_not_mean_unquantized():
+    cfg = {"model_type": "gemma4", "quantization_config": {"quant_method": "gemma", "module_quant_configs": {"x": {"num_bits": 2}}}}
+    q = detect_quant("mlx-community/gemma-4-E4B-it-qat-mobile", ["8-bit"], cfg)
+    assert q.bits == 8 and q.source == "tags"

tests/test_recommend.py

@@ -0,0 +1,152 @@
+import re
+from dataclasses import replace
+from datetime import datetime, timezone
+from pathlib import Path
+
+from app.catalogue import build_record
+from app.model_detail import ModelDetail
+from app.recommend import CommunitySignal, HeuristicEngine, Query, sort_results
+
+from .test_parsing import QWEN3_8B_CONFIG
+
+NOW = datetime(2026, 9, 1, tzinfo=timezone.utc)
+ENGINE = HeuristicEngine(now=NOW)
+
+
+def rec(name, total, bits, downloads=1000, modified="2026-08-01T00:00:00Z", tags=None):
+    return build_record({
+        "id": f"mlx-community/{name}", "downloads": downloads, "likes": 1, "lastModified": modified,
+        "pipeline_tag": "text-generation", "safetensors": {"total": total},
+        "tags": (tags or []) + [f"{bits}-bit"],
+    })
+
+
+def family():
+    return [
+        rec("Fam-8B-2bit", 8e9, 2), rec("Fam-8B-3bit", 8e9, 3), rec("Fam-8B-4bit", 8e9, 4),
+        rec("Fam-8B-6bit", 8e9, 6), rec("Fam-8B-8bit", 8e9, 8),
+    ]
+
+
+def ranked(models, q, details=None, community=None):
+    return [s.model.name for s in sort_results(ENGINE.score(models, q, details or {}, community or {}), "recommended")]
+
+
+def test_priority_changes_order():
+    ms = family()
+    quality = ranked(ms, Query(ram_gb=64, priority="quality"))
+    memory = ranked(ms, Query(ram_gb=64, priority="memory"))
+    assert quality[0] == "Fam-8B-8bit"
+    assert memory[0] == "Fam-8B-2bit"
+    assert ranked(ms, Query(ram_gb=64, priority="balanced"))[0] == "Fam-8B-4bit"
+
+
+def test_ram_changes_order():
+    ms = family()
+    big = ranked(ms, Query(ram_gb=64, priority="quality"))
+    small = ranked(ms, Query(ram_gb=8, priority="quality"))
+    assert big[0] == "Fam-8B-8bit"
+    assert small[0] != "Fam-8B-8bit"  # 8-bit 8B (~8.5 GB) can't load on an 8 GB Mac
+    scored = {s.model.name: s for s in ENGINE.score(ms, Query(ram_gb=8, priority="quality"))}
+    assert scored["Fam-8B-8bit"].memory.fit == "Unlikely"
+
+
+def test_context_changes_score():
+    m = rec("Fam-8B-4bit", 8e9, 4)
+    d = {m.id: ModelDetail(m.id, QWEN3_8B_CONFIG, [], None, 0)}
+    short = ENGINE.score([m], Query(ram_gb=16, context=4096), d)[0]
+    long = ENGINE.score([m], Query(ram_gb=16, context=131072), d)[0]
+    assert long.memory.total_gb > short.memory.total_gb
+    assert long.score < short.score
+    assert any("shorter maximum context" in r for r in long.reasons)
+
+
+def test_quant_changes_score_for_same_model():
+    a, b = rec("Fam-8B-4bit", 8e9, 4), rec("Fam-8B-3bit", 8e9, 3)
+    q = Query(ram_gb=64, priority="balanced")
+    s = {x.model.name: x.score for x in ENGINE.score([a, b], q)}
+    assert s["Fam-8B-4bit"] > s["Fam-8B-3bit"]
+
+
+def test_reasons_present_and_no_perf_claims():
+    for s in ENGINE.score(family(), Query(ram_gb=16, priority="speed")):
+        assert s.reasons
+        text = " ".join(s.reasons).lower()
+        assert "tok/s" not in text  # no invented throughput without community data
+        assert "depends" in text
+
+
+def test_unknown_ram_and_unknown_memory_degrade_gracefully():
+    m = build_record({"id": "mlx-community/mystery", "tags": []})
+    s = ENGINE.score([m], Query())[0]
+    assert s.memory.total_gb is None and s.memory.fit is None
+    assert any("isn't available" in r for r in s.reasons)
+
+
+def test_neutral_to_names_and_brands():
+    base = rec("Qwen3-8B-4bit", 8e9, 4, downloads=5000)
+    renamed = replace(base, id="mlx-community/Qwen3-8B-OptiQ-4bit", name="Qwen3-8B-OptiQ-4bit")
+    other_org = replace(base, id="someone/Qwen3-8B-4bit", name="Qwen3-8B-4bit")
+    q = Query(ram_gb=24, priority="balanced", context=32768)
+    scores = [ENGINE.score([m], q, {}, {})[0].score for m in (base, renamed, other_org)]
+    assert scores[0] == scores[1] == scores[2]
+
+
+def test_engine_source_mentions_no_product_names():
+    src = (Path(__file__).resolve().parent.parent / "app" / "recommend.py").read_text().lower()
+    code = re.sub(r'"""[\s\S]*?"""', "", src)  # the module docstring may explain the rule
+    for word in ("optiq", "unsloth", "lmstudio", "bartowski", "dwq"):
+        assert word not in code
+
+
+def test_popularity_and_community_break_ties():
+    a = rec("A-8B-4bit", 8e9, 4, downloads=100)
+    b = rec("B-8B-4bit", 8e9, 4, downloads=100_000)
+    assert ranked([a, b], Query(ram_gb=32))[0] == "B-8B-4bit"
+    comm = {a.id: CommunitySignal(feedback_count=30, positive_share=1.0, benchmark_count=20,
+                                  median_generation_tps=40)}
+    s = {x.model.name: x for x in ENGINE.score([a, b], Query(ram_gb=32), {}, comm)}
+    assert s["A-8B-4bit"].components["community"] > 0
+    assert any("MLX benchmark" in r for r in s["A-8B-4bit"].reasons)
+
+
+def test_sorts():
+    old = rec("Old-8B-4bit", 8e9, 4, downloads=10**6, modified="2024-01-01T00:00:00Z")
+    new = rec("New-8B-4bit", 8e9, 4, downloads=10, modified="2026-08-30T00:00:00Z")
+    scored = ENGINE.score([old, new], Query(ram_gb=32))
+    assert sort_results(scored, "popular")[0].model.name == "Old-8B-4bit"
+    assert sort_results(scored, "recent")[0].model.name == "New-8B-4bit"
+    assert [s.model.name for s in sort_results(scored, "all")] == ["New-8B-4bit", "Old-8B-4bit"]
+
+
+def test_config_quant_overrides_misleading_name():
+    m = rec("Fam-9B-4bit", 9e9, 4)
+    cfg = {"model_type": "x", "num_hidden_layers": 4, "num_attention_heads": 8, "head_dim": 64}
+    d = {m.id: ModelDetail(m.id, cfg, [], 18_000_000_000, 0)}
+    s = ENGINE.score([m], Query(ram_gb=36), d)[0]
+    assert s.quant["bits"] == 16 and s.to_dict()["quant"]["label"] == "16-bit"
+    assert any("config.json says 16-bit" in r for r in s.reasons)
+
+
+def test_likes_count_toward_popularity():
+    a = rec("A-8B-4bit", 8e9, 4, downloads=20_000)
+    b = replace(rec("B-8B-4bit", 8e9, 4, downloads=20_000), likes=150)
+    assert ranked([a, b], Query(ram_gb=32))[0] == "B-8B-4bit"
+
+
+def test_capacity_prefers_larger_models_that_fit():
+    small = rec("Fam-1B-4bit", 1e9, 4, downloads=5000)
+    mid = rec("Fam-8B-4bit", 8e9, 4, downloads=5000)
+    huge = rec("Fam-70B-4bit", 70e9, 4, downloads=5000)
+    order = ranked([small, mid, huge], Query(ram_gb=36, priority="balanced"))
+    assert order[0] == "Fam-8B-4bit" and order[-1] == "Fam-70B-4bit"  # 70B doesn't fit 36 GB
+    assert ranked([small, mid, huge], Query(ram_gb=128, priority="quality"))[0] == "Fam-70B-4bit"
+
+
+def test_norms_make_scores_page_independent():
+    ms = [rec(f"M{i}-8B-4bit", 8e9, 4, downloads=10 ** i) for i in range(1, 6)]
+    q = Query(ram_gb=32)
+    norms = ENGINE.norms(ms, q)
+    full = {s.model.id: s.score for s in ENGINE.score(ms, q, {}, {}, norms)}
+    page = {s.model.id: s.score for s in ENGINE.score(ms[:2], q, {}, {}, norms)}
+    assert all(abs(full[k] - v) < 1e-9 for k, v in page.items())

tests/test_sink.py

@@ -0,0 +1,63 @@
+import pyarrow.parquet as pq
+import pytest
+
+from app.events import COLUMNS, ClientEvent, to_row
+from app.sink import HubParquetSink, LocalParquetSink, rows_to_parquet_bytes
+
+
+def rows(n):
+    return [to_row(ClientEvent(event_type="search", model_family="Qwen", quantization="4-bit")) for _ in range(n)]
+
+
+def test_batch_becomes_one_shard(tmp_path):
+    s = LocalParquetSink(tmp_path, flush_seconds=999)
+    s.add(rows(7))
+    s.add(rows(5))
+    assert s.flush()
+    shards = list((tmp_path / "data/events").rglob("*.parquet"))
+    assert len(shards) == 1
+    t = pq.read_table(shards[0])
+    assert t.num_rows == 12 and t.column_names == list(COLUMNS)
+    assert s.flush() and len(list((tmp_path / "data/events").rglob("*.parquet"))) == 1  # empty flush = no shard
+    s.add(rows(1))
+    s.flush()
+    assert len(list((tmp_path / "data/events").rglob("*.parquet"))) == 2  # appends, never rewrites
+    assert len(s.read_existing()) == 13
+
+
+class FlakyApi:
+    def __init__(self, fail_times):
+        self.fail_times = fail_times
+        self.commits = []
+        self.token = None
+
+    def create_commit(self, repo_id, repo_type, operations, commit_message):
+        if self.fail_times > 0:
+            self.fail_times -= 1
+            raise ConnectionError("hub down")
+        assert repo_type == "dataset"
+        self.commits.append([op.path_in_repo for op in operations])
+
+
+def test_hub_failure_keeps_spool_and_retries(tmp_path):
+    api = FlakyApi(fail_times=2)
+    s = HubParquetSink("org/data", None, spool_dir=tmp_path, api=api, flush_seconds=999)
+    s.add(rows(3))
+    assert not s.flush() and s.pending == 3 and not s.status()["healthy"]
+    # a restart in between must not lose rows
+    s2 = HubParquetSink("org/data", None, spool_dir=tmp_path, api=api, flush_seconds=999)
+    assert s2.pending == 3
+    assert not s2.flush()
+    assert s2.flush() and s2.pending == 0 and s2.status()["healthy"]
+    assert len(api.commits) == 1 and len(api.commits[0]) == 1
+    assert api.commits[0][0].startswith("data/events/") and api.commits[0][0].endswith(".parquet")
+    s3 = HubParquetSink("org/data", None, spool_dir=tmp_path, api=api, flush_seconds=999)
+    assert s3.pending == 0
+
+
+def test_local_refuses_overwrite(tmp_path):
+    s = LocalParquetSink(tmp_path, flush_seconds=999)
+    data = rows_to_parquet_bytes(rows(1))
+    s._write_shard("data/events/x.parquet", data)
+    with pytest.raises(FileExistsError):
+        s._write_shard("data/events/x.parquet", data)