<!--
  MODELS.md
  Zyquo MLX

  Author: Simon-Pierre Boucher
  Mail: contact@spboucher.ai
-->

# Zyquo MLX — Hub Integration & Curated Model Catalog

> Phase 0.C research document. Every catalog row was **live-verified against the
> Hugging Face Hub API on 2026-07-30** (HTTP 200, sizes summed from real tree
> listings). Anything computed rather than measured is marked *estimated*.

---

## 1. Hugging Face Hub HTTP API

### 1.1 Search — `GET https://huggingface.co/api/models`

Verified working parameter set:

```
?author=mlx-community&pipeline_tag=text-generation&filter=mlx
&search=Qwen3&sort=downloads&direction=-1&limit=100&full=true&config=true
```

| Param | Behavior (verified) |
|---|---|
| `search` | substring match on repo name |
| `author` | org/user scope (`mlx-community`, `lmstudio-community`, …) |
| `filter` | tag filter; `filter=mlx` matches the MLX library tag across all orgs |
| `pipeline_tag` | `text-generation`, `image-text-to-text` (VLM), `feature-extraction` (embeddings), `automatic-speech-recognition`, `image-to-image` |
| `sort` + `direction=-1` | `downloads`, `likes`, `lastModified`, `trendingScore` (default) |
| `limit` | up to **1000** per page; pagination via `Link: <…cursor=…>; rel="next"` response header (cursor-based) |
| `full=true` | adds `siblings` (filenames only — **no sizes**) + `sha` |
| `config=true` | adds `config` incl. `quantization_config` (bits/group_size), `architectures`, `model_type` |

List-item fields: `id, author, downloads (30-day rolling), likes, tags, gated,
lastModified, createdAt, pipeline_tag, library_name, private`.
`safetensors` parameter counts are **not** in search results — only on the
per-model endpoint.

**Rate limits (anonymous, from live response headers):**
`ratelimit-policy: "fixed window";"api";q=500;w=300` → **500 API requests per
5 minutes**; `ratelimit: "api";r=…;t=…` gives remaining/reset. Design
`HubService` to batch (one 1000-item search call) and cache.

### 1.2 Model info & file listing

- `GET /api/models/{repo_id}` → `sha` (commit, for revision pinning),
  `siblings`, `usedStorage`, `safetensors: {parameters: {BF16: n, U32: n}, total}`,
  `gated` (`false` | `"manual"`), `cardData`.
- ⚠️ **Quantized-parameter quirk (verified):** MLX packs 4-bit weights as U32,
  so `safetensors.total` undercounts ~8×. Real params ≈ `BF16 + U32 × 8`
  (Qwen3-4B-4bit: 125.9M BF16 + 502.8M U32 → ≈ 4.1B ✓). `ModelStore` must use
  this formula or parse the repo name.
- `GET /api/models/{repo_id}/tree/main?recursive=true` → per-file
  `{type, path, size, lfs: {oid, size, pointerSize}}`.
  - **Not recursive by default** — always pass `recursive=true` (FLUX repos
    keep components in subdirectories).
  - `size` is always the true byte size; `lfs.oid` is the file's SHA-256 —
    use it as the integrity check after download.
  - Revision pinning: `/tree/{commit_sha}?recursive=true`. 1000 entries per
    page, `Link rel="next"` beyond.

### 1.3 Download / resolve (drives `DownloadManager`)

- `GET https://huggingface.co/{repo}/resolve/{revision}/{filename}` → **302**
  to a signed, expiring CDN URL (Xet bridge, `us.aws.cdn.hf.co/xet-bridge-us/…`).
  Small files (e.g. `config.json`) → **307** to `/api/resolve-cache/…`.
- `HEAD` on the resolve URL (before redirect) yields: `x-linked-size` (exact
  size), `x-linked-etag` (content SHA-256), `x-repo-commit` (resolved commit —
  **pin all subsequent files of a download to it** for a consistent snapshot),
  `accept-ranges: bytes`.
- **Resume (verified):** `Range: bytes={downloaded}-` on a *fresh* resolve
  request (CDN URLs expire — never persist them) → HTTP 206 with
  `content-range`. This is the resumable-download contract.
- **Auth / gated repos:** `Authorization: Bearer hf_…` works on both `/api/*`
  and `/resolve/*`. Gated repos report `gated: "manual"` and return 401
  anonymously (verified with `meta-llama/Llama-3.1-8B-Instruct`). All
  `mlx-community` catalog repos verified `gated: false`.

### 1.4 MLX ecosystem conventions (census of top-1000 mlx-community repos)

- Tags: library tag `mlx`, region tags `4-bit`/`8-bit`,
  `base_model:quantized:{original-repo}`.
- Name-suffix census (top-1000 by downloads): `-4bit` ×400, `-8bit` ×176,
  `-bf16` ×104, `-mlx`/`-MLX` ×99, `-6bit` ×70, `-qat` ×50, `mxfp4` ×33,
  `-5bit` ×24, `-3bit` ×22, `-DWQ` ×18, `-fp16` ×16, whisper-style `-q4/-q8` ×17.
- `config.json` `"quantization"`: `{bits, group_size, mode}` — 2026 repos say
  `"affine"`; `"mxfp4"` (gpt-oss, group_size 32) and mixed recipes
  (`MXFP4-Q8`, `DQ4plus-q8`) also occur. `-DWQ` = distilled-weight quantization
  (same size, better quality).
- Ecosystem state mid-2026 (from live download charts): current generations
  are **Qwen3.5 / Qwen3.6, gemma-4, GLM-4.7/5.2, Kimi-K2.5/K2.6, DeepSeek-V4,
  Mistral-Small-4, FLUX.2-Klein, Qwen3-TTS/ASR, parakeet v3**. No Llama-4 in
  mlx-community. Many new text models carry `pipeline_tag: image-text-to-text`
  (natively multimodal).

---

## 2. Featured Catalog (live-verified 2026-07-30)

Disk = exact sum of weight files from the live tree listing.
Min RAM = weights + ~20% overhead + OS headroom, rounded to a Mac tier
(*estimated — calibrate in Phase 7*). Downloads = 30-day count at verification.

### 2.1 Text LLMs — small (0.5–3B)

| Repo | Params | Quant | Disk | Min RAM | DLs |
|---|---|---|---|---|---|
| `mlx-community/Qwen3-0.6B-4bit` | 0.6B | 4-bit gs64 | 0.34 GB | 8 GB | 49.9k |
| `mlx-community/Llama-3.2-1B-Instruct-4bit` | 1B | 4-bit gs64 | 0.70 GB | 8 GB | 48.3k |
| `mlx-community/gemma-3-1b-it-qat-4bit` | 1B | 4-bit gs64 QAT | 0.73 GB | 8 GB | 33.2k |
| `mlx-community/Qwen3-1.7B-4bit` | 1.7B | 4-bit gs64 | 0.97 GB | 8 GB | 14.1k |
| `mlx-community/SmolLM3-3B-4bit` | 3B | 4-bit gs64 | 1.73 GB | 8 GB | 2.0k |
| `mlx-community/Llama-3.2-3B-Instruct-4bit` | 3B | 4-bit gs64 | 1.81 GB | 8 GB | 21.1k |

### 2.2 Text LLMs — mid (4–9B)

| Repo | Params | Quant | Disk | Min RAM | DLs |
|---|---|---|---|---|---|
| `mlx-community/Qwen3-4B-Instruct-2507-4bit` | 4B | 4-bit gs64 | 2.26 GB | 8 GB | 41.6k |
| `mlx-community/Mistral-7B-Instruct-v0.3-4bit` | 7B | 4-bit gs64 | 4.08 GB | 16 GB | 12.1k |
| `mlx-community/Qwen2.5-Coder-7B-Instruct-4bit` | 7B | 4-bit gs64 | 4.28 GB | 16 GB | 30.7k |
| `mlx-community/Llama-3.1-8B-Instruct-4bit` | 8B | 4-bit gs64 | 4.52 GB | 16 GB | 27.1k |
| `mlx-community/Qwen3-8B-4bit` | 8B | 4-bit gs64 | 4.61 GB | 16 GB | 32.3k |
| `mlx-community/gemma-4-e4b-it-4bit` | ~8B (eff. 4B) | 4-bit gs64 affine | 5.15 GB | 16 GB | 61.6k |
| `mlx-community/Qwen3.5-9B-4bit` | 9B | 4-bit gs64 affine | 5.95 GB | 16 GB | 22.8k |

### 2.3 Text LLMs — large (14–35B, incl. MoE)

| Repo | Params | Quant | Disk | Min RAM | DLs |
|---|---|---|---|---|---|
| `mlx-community/Qwen3-14B-4bit` | 14B | 4-bit gs64 | 8.31 GB | 16 GB | 40.3k |
| `mlx-community/DeepSeek-R1-Distill-Qwen-14B-4bit` | 14B | 4-bit gs64 | 8.31 GB | 16 GB | 41.8k |
| `mlx-community/gpt-oss-20b-MXFP4-Q8` | 20.9B MoE | MXFP4 gs32 + Q8 | 12.08 GB | 24 GB | 355.3k |
| `mlx-community/Mistral-Small-3.1-24B-Instruct-2503-4bit` | 24B | 4-bit gs64 | 14.09 GB | 24 GB | 27.5k |
| `mlx-community/Devstral-Small-2-24B-Instruct-2512-4bit` | 24B | 4-bit gs64 affine | 15.10 GB | 24 GB | 114.0k |
| `mlx-community/Qwen3.6-27B-4bit` | 27B | 4-bit gs64 affine | 16.05 GB | 32 GB | 50.7k |
| `mlx-community/Qwen3-30B-A3B-Instruct-2507-4bit` | 30B-A3B MoE | 4-bit gs64 | 17.18 GB | 32 GB | 83.8k |
| `mlx-community/Qwen3-Coder-30B-A3B-Instruct-4bit` | 30B-A3B MoE | 4-bit gs64 | 17.18 GB | 32 GB | 7.4k |
| `mlx-community/gemma-4-31b-it-4bit` | 31B | 4-bit gs64 affine | 18.41 GB | 32 GB | 47.5k |
| `mlx-community/Qwen3-32B-4bit` | 32B | 4-bit gs64 | 18.43 GB | 32 GB | 2.1k |
| `mlx-community/DeepSeek-R1-Distill-Qwen-32B-4bit` | 32B | 4-bit gs64 | 18.43 GB | 32 GB | 8.2k |
| `mlx-community/Qwen3.6-35B-A3B-4bit` | 35B-A3B MoE | 4-bit gs64 affine | 20.40 GB | 32 GB | 62.0k |

MoE note: RAM is set by **total** params (all experts resident); speed by
active params. `Qwen3-30B-A3B` needs a 32 GB Mac but generates at ~3B speed —
the ideal recommendation for 32 GB machines.

### 2.4 Vision-language models

| Repo | Params | Quant | Disk | Min RAM | DLs |
|---|---|---|---|---|---|
| `mlx-community/Qwen3-VL-4B-Instruct-4bit` | 4B | 4-bit gs64 affine | 3.09 GB | 16 GB | 17.5k |
| `mlx-community/SmolVLM2-2.2B-Instruct-mlx` | 2.2B | bf16 | 4.49 GB | 16 GB | 365 |
| `mlx-community/Qwen2.5-VL-7B-Instruct-4bit` | 7B | 4-bit gs64 | 5.64 GB | 16 GB | 3.6k |
| `mlx-community/Qwen3-VL-8B-Instruct-4bit` | 8B | 4-bit gs64 affine | 5.76 GB | 16 GB | 2.3k |
| `mlx-community/pixtral-12b-4bit` | 12B | 4-bit gs64 | 7.14 GB | 16 GB | 276 |
| `mlx-community/gemma-3-12b-it-qat-4bit` | 12B | 4-bit gs64 QAT | 8.03 GB | 24 GB | 31.8k |

### 2.5 Embeddings (MLX format)

| Repo | Params | Quant | Disk | Min RAM | DLs |
|---|---|---|---|---|---|
| `mlx-community/all-MiniLM-L6-v2-4bit` | 22M | 4-bit gs64 | 0.01 GB | 8 GB | 1.7k |
| `mlx-community/nomicai-modernbert-embed-base-bf16` | 149M | bf16 | 0.30 GB | 8 GB | 5.2k |
| `mlx-community/Qwen3-Embedding-0.6B-4bit-DWQ` | 0.6B | 4-bit DWQ | 0.34 GB | 8 GB | 15.3k |
| `mlx-community/bge-m3-mlx-fp16` | 568M | fp16 | 1.14 GB | 8 GB | 11.2k |
| `mlx-community/Qwen3-Embedding-4B-4bit-DWQ` | 4B | 4-bit DWQ | 2.26 GB | 8 GB | 2.4k |

### 2.6 Speech

| Repo | Params | Quant | Disk | Min RAM | DLs |
|---|---|---|---|---|---|
| `mlx-community/Qwen3-ASR-0.6B-8bit` | 0.6B | 8-bit gs64 affine | 1.01 GB | 8 GB | 75.3k |
| `mlx-community/whisper-large-v3-turbo` | 0.8B | fp16 | 1.61 GB | 8 GB | 77.8k |
| `mlx-community/parakeet-tdt-0.6b-v3` | 0.6B | bf16 | 2.51 GB | 8 GB | 1.33M |
| `mlx-community/whisper-large-v3-mlx` | 1.5B | fp16 | 3.08 GB | 8 GB | 26.6k |

### 2.7 Image generation

| Repo | Type | Quant | Disk | Min RAM | DLs |
|---|---|---|---|---|---|
| `mlx-community/FLUX.2-Klein-4B-4bit` | FLUX.2 Klein 4B | 4-bit (components in subdirs) | 4.61 GB | 16 GB | 575 |
| `argmaxinc/mlx-FLUX.1-schnell-4bit-quantized` | FLUX.1-schnell (DiffusionKit) | 4-bit | 7.03 GB | 16 GB | 7.3k |
| `dhairyashil/FLUX.1-schnell-mflux-4bit` | FLUX.1-schnell (mflux) | 4-bit | 9.61 GB | 24 GB | 606 |

No stable-diffusion MLX repos exist in `mlx-community` (live search returned
zero). The mflux ecosystem lives under `mflux-community/` — pick per
mflux-version compatibility at implementation time.

**Verification total: 43 repos checked, 0 failures, all `gated: false`.**

---

## 3. RAM Guidance Table (powers `MemoryAdvisor` badges)

*Estimated — arithmetic + community guidance; calibrate on real runs in Phase 7.*

Basis: 4-bit gs64 affine = 4 + 32/64 bits/weight = **4.5 bits ≈ 0.5625 B/param**
(confirmed by catalog: Qwen3-14B → 0.561 B/p, Qwen3-32B → 0.562 B/p);
bf16 = 2 B/param. macOS GPU working-set ceiling ≈ 70–75% of unified RAM; keep
model + KV cache + activations ≤ ~(RAM − 5 GB). KV cache ≈ 0.5–2 GB at 8k ctx
for 7–32B GQA models. LoRA (bf16 base) ≈ 2 B/param + activations + adapter
optimizer state. QLoRA (4-bit frozen base) ≈ 0.5625 B/param + activations
(~2–5 GB at batch 1–4, seq 1–2k, grad checkpointing on).

| Mac RAM | 4-bit inference (realistic max) | LoRA FT (bf16 base) | QLoRA FT (4-bit base) |
|---|---|---|---|
| 8 GB | ≤3B comfortable; 4B tight | ≤0.6B | ≤1.7B |
| 16 GB | 7–9B comfortable; 14B ok w/ modest ctx | ≤3B | ≤7–8B |
| 24 GB | 14B comfortable; 20B MoE & 24B ok | ≤7B (tight) | ≤14B |
| 32 GB | 27–32B dense & 30B/35B-A3B MoE | ≤8–9B | 14B comfortable; 24B tight |
| 48 GB | 32–35B comfortable + long ctx; ~50B-class | ≤14B | ≤32B |
| 64 GB | 70B 4-bit (~39.4 GB; `Llama-3.3-70B-Instruct-4bit` verified to exist) | ≤24B | 32B comfortable |
| 96 GB | 70B comfortable; ~100–120B MoE | ≤32B | ≤70B (tight) |
| 128 GB | 120B-class MoE (e.g. `Mistral-Small-4-119B-2603-4bit`, exists); 70B 8-bit | ≤35B dense | 70B comfortable; ~120B MoE possible |

**This Mac (dev machine): 48 GB** → 4-bit inference up to ~35B comfortable;
LoRA ≤14B; QLoRA ≤32B.

Caveats for `MemoryAdvisor`:
1. Min-RAM columns are computed, not measured — Phase 7 calibrates them.
2. `downloads` is a 30-day rolling count (freshness signal, not lifetime).
3. For quantized repos derive real params as `BF16 + U32 × 8` from the
   `safetensors` field, or parse the name suffix.