# 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

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)

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

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

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

# 2.5 Embeddings (MLX format)

# 2.6 Speech

# 2.7 Image generation

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).

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.