Repository Public
1#!/usr/bin/env python32# Author: Simon-Pierre Boucher — contact@spboucher.ai3# File: Scripts/models-by-device.py4# Description: Regenerates Documentation/MODELS_BY_DEVICE.md from the live mlx-community listing on Hugging Face, with the same rules as the app5# (DeviceModelCatalog.swift, AppleDevices.swift): loadable architecture, size = parameters x nominal bits / 8, memory budget per device class.6import datetime, json, math, os, re, sys, urllib.request78ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))9GB = 1 << 3010DEVICES = [("iPhone", 6, "iPhone 14 Pro, iPhone 15"), ("iPhone", 8, "iPhone 15 Pro, iPhone 16, iPhone 17"), ("iPhone", 12, "iPhone 17 Pro, iPhone 17 Pro Max, iPhone Air"),11 ("iPad", 8, "iPad Air (M2, M3), iPad mini (A17 Pro), iPad Pro M4 256 / 512 GB"), ("iPad", 12, "iPad Pro M5 256 / 512 GB"), ("iPad", 16, "iPad Pro M4 / M5 1 TB and 2 TB"),12 ("Mac", 8, "MacBook Air M1 – M3 base"), ("Mac", 16, "MacBook Air, Mac mini, MacBook Pro base"), ("Mac", 24, "MacBook Air / Pro, Mac mini"),13 ("Mac", 32, "MacBook Pro, Mac Studio"), ("Mac", 48, "MacBook Pro M4 / M5 Pro and Max"), ("Mac", 64, "MacBook Pro Max, Mac Studio"),14 ("Mac", 96, "Mac Studio M3 Ultra"), ("Mac", 128, "MacBook Pro M4 / M5 Max, Mac Studio"), ("Mac", 192, "Mac Studio M2 Ultra")]15TASKS = {"chat": ["text-generation"], "vision": ["image-text-to-text"], "embeddings": ["sentence-similarity", "feature-extraction"]}1617def architectures():18 src = open(os.path.join(ROOT, "Packages/LocalChatModelHub/Sources/MLXArchitectures.swift")).read()19 sets = {name: set(re.findall(r'"([^"]+)"', re.search(rf"static let {name}: Set<String> = \[(.*?)\]", src).group(1))) for name in ("text", "vision", "embedding")}20 return {"chat": sets["text"] | sets["vision"], "vision": sets["vision"], "embeddings": sets["embedding"]}, re.search(r'version = "([^"]+)"', src).group(1)2122def usable(family, gb): return gb * GB * ((0.75 if gb >= 32 else 0.65) if family == "Mac" else 0.55)2324def bits(name):25 low = name.lower()26 m = re.search(r"(?<![0-9a-z])([2-8])[-_]?bits?(?![a-z0-9])", low)27 if m: return m.group(1) + "bit", int(m.group(1)) + 0.528 m = re.search(r"(?<![a-z0-9])(bf16|fp16|f16|fp32|f32)(?![a-z0-9])", low)29 if m: return m.group(1), 32 if m.group(1).endswith("32") else 1630 return None, None3132def name_params(name):33 m = re.search(r"(?<![0-9a-z.])(\d+(?:\.\d+)?)\s?([bm])(?![a-z0-9])", name.lower())34 return int(float(m.group(1)) * (1e9 if m.group(2) == "b" else 1e6)) if m else None3536def kv_per_token(params):37 b = params / 1e938 return max(20_000, min(900_000, 55_000 * math.sqrt(b) * max(1, math.sqrt(b))))3940def fetch(tag, pages=2):41 url = f"https://huggingface.co/api/models?filter=mlx&pipeline_tag={tag}&author=mlx-community&sort=downloads&direction=-1&limit=100" + "".join(f"&expand[]={f}" for f in ("safetensors", "config", "downloads", "likes", "pipeline_tag", "tags", "lastModified", "gated"))42 out = []43 for _ in range(pages):44 with urllib.request.urlopen(urllib.request.Request(url, headers={"User-Agent": "local-chat-docs"}), timeout=60) as r:45 out += json.load(r); link = r.headers.get("Link", "")46 m = re.search(r'<([^>]+)>;\s*rel="next"', link)47 if not m: break48 url = m.group(1)49 return out5051def main():52 supported, version = architectures()53 models, seen = [], set()54 for task, tags in TASKS.items():55 for tag in tags:56 for m in fetch(tag):57 rid = m["id"]; low = rid.lower()58 if rid in seen or "lora" in low or "adapter" in low: continue59 seen.add(rid)60 arch = (m.get("config") or {}).get("model_type")61 params = (m.get("safetensors") or {}).get("total") or name_params(rid)62 q, bpw = bits(rid)63 size = params * bpw / 8 if params and bpw else None64 need = size + 4096 * kv_per_token(params) + 350 * (1 << 20) if size else None65 models.append(dict(id=rid, name=rid.split("/")[-1], task=task, arch=arch, params=params, q=q, size=size, need=need,66 downloads=m.get("downloads") or 0, ok=arch in supported[task] if arch else False))67 def picks(family, gb, task, count):68 budget = usable(family, gb); best = {}69 for m in models:70 if m["task"] != task or not m["ok"] or not m["need"] or m["need"] > budget * 0.7 or m["downloads"] < 500: continue71 key = re.sub(r"-?(\d)bit.*$|-?(bf16|fp16|dwq|qat).*$", "", m["name"].lower())72 if key not in best or best[key]["downloads"] < m["downloads"]: best[key] = m73 return sorted(best.values(), key=lambda m: (m["params"] or 0, m["downloads"]), reverse=True)[:count]74 def fitting(family, gb, task): return sum(1 for m in models if m["task"] == task and m["ok"] and m["need"] and m["need"] <= usable(family, gb))75 def cell(ms): return "<br>".join(f"[`{m['name']}`](https://huggingface.co/{m['id']}) · ≈ {m['need'] / GB:.1f} GB" for m in ms) or "—"76 today = datetime.date.today().isoformat()77 loadable = sum(1 for m in models if m["ok"]); sized = sum(1 for m in models if m["ok"] and m["size"])78 lines = ["<!--", "Local Chat", "File: Documentation/MODELS_BY_DEVICE.md", "Author: Simon-Pierre Boucher", "Contact: contact@spboucher.ai",79 "Generated file — do not edit. Regenerate with Scripts/models-by-device.py", "-->", "# MLX models by Apple device", "",80 f"Generated on {today} from the live [mlx-community](https://huggingface.co/mlx-community) listing on Hugging Face: {len(models)} repositories read "81 f"(most downloaded per task), {loadable} with an architecture MLX Swift LM {version} can load, {sized} of those with a size estimate.", "",82 "The app shows the same list live (Models → By device), for every device class, and refreshes it daily.", "",83 "**How a model is proposed** — its architecture is implemented by MLX Swift; estimated memory = weights (parameters × nominal bits per weight ÷ 8) "84 "+ KV cache for a 4,096-token context + 350 MB; it must stay under 70 % of the memory a model may use on the device (65 % of RAM on a Mac under 32 GB, "85 "75 % from 32 GB, 55 % on iPhone and iPad). Figures are estimates; nothing here was run on a physical iPhone or iPad.", "",86 "## Best picks", "", "The largest well-downloaded models (≥ 500 downloads) that fit comfortably, one quantization per model.", "",87 "| Device | Memory for a model | Chat | Vision | Chat models that fit |", "|---|---|---|---|---|"]88 for family, gb, examples in DEVICES:89 lines.append(f"| **{family} · {gb} GB**<br><sub>{examples}</sub> | {usable(family, gb) / GB:.1f} GB | {cell(picks(family, gb, 'chat', 4))} | {cell(picks(family, gb, 'vision', 2))} | {fitting(family, gb, 'chat')} |")90 lines += ["", "## Embedding models (Knowledge Studio)", "", "Small enough for every device class above.", "", "| Model | Architecture | Downloads |", "|---|---|---|"]91 for m in sorted([m for m in models if m["task"] == "embeddings" and m["ok"]], key=lambda m: -m["downloads"])[:8]:92 lines.append(f"| [`{m['name']}`](https://huggingface.co/{m['id']}) | {m['arch']} | {m['downloads']:,} |")93 open(os.path.join(ROOT, "Documentation/MODELS_BY_DEVICE.md"), "w").write("\n".join(lines) + "\n")94 print(f"{len(models)} models, {loadable} loadable, {sized} sized → Documentation/MODELS_BY_DEVICE.md")9596if __name__ == "__main__": main()97