Python
llama.cpp setup: licence per model, verified downloads, 429 waits
Rohit C Prasadf791d7a92706
diff --git a/coworker/providers/llamacpp_models.json b/coworker/providers/llamacpp_models.jsonindex 01484587..337fba5a 100644--- a/coworker/providers/llamacpp_models.json+++ b/coworker/providers/llamacpp_models.json@@ -1,6 +1,6 @@{"version": 1,- "about": "Models the llama.cpp setup suggests (UX-057). Read by coworker/providers/llamacpp_setup.py. Each names a Hugging Face repo and the GGUF files OpenWorker downloads into llama.cpp's own cache; `draft` is a second file for speculative decoding (`spec_type`). `size` is the bytes of all files, for the fit advice; a model too large for the machine is not offered. `ollama` is the same model's name in Ollama, for the download command shown next to it. Edit in git; give a source.",+ "about": "Models the llama.cpp setup suggests (UX-057). Read by coworker/providers/llamacpp_setup.py. Each names a Hugging Face repo and the GGUF files OpenWorker downloads into llama.cpp's own cache; `draft` is a second file for speculative decoding (`spec_type`). `size` is the bytes of all files, for the fit advice; a model too large for the machine is not offered. `ollama` is the same model's name in Ollama, for the download command shown next to it. `license` and `license_url` are shown before Download, read from the model card on Hugging Face (`license_source` says where; checked 2026-10-26). Edit in git; give a source.","models": [{"id": "nemotron-3.5-lightning",@@ -14,6 +14,9 @@"size": 35761208832,"context_max": 1048576,"features": ["thinking", "tools"],+ "license": "OpenMDW-1.1",+ "license_url": "https://openmdw.ai/license/1-1/",+ "license_source": "https://huggingface.co/nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16 (model card: license: other, license_name: openmdw-1.1; the GGUF repo only says other)","source": "https://huggingface.co/ggml-org/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-GGUF"},{@@ -26,6 +29,9 @@"size": 18556689568,"context_max": 262144,"features": ["tools"],+ "license": "Apache-2.0",+ "license_url": "https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct/blob/main/LICENSE",+ "license_source": "https://huggingface.co/unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF (model card: license: apache-2.0, license_link as above)","ollama": "qwen3-coder:30b","source": "https://huggingface.co/unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF"},@@ -39,6 +45,9 @@"size": 12109566624,"context_max": 131072,"features": ["reasoning", "tools"],+ "license": "Apache-2.0",+ "license_url": "https://huggingface.co/openai/gpt-oss-20b/blob/main/LICENSE",+ "license_source": "https://huggingface.co/ggml-org/gpt-oss-20b-GGUF (model card: license: apache-2.0)","ollama": "gpt-oss:20b","source": "https://huggingface.co/ggml-org/gpt-oss-20b-GGUF"}diff --git a/coworker/providers/llamacpp_setup.py b/coworker/providers/llamacpp_setup.pyindex 31db853b..517aab11 100644--- a/coworker/providers/llamacpp_setup.py+++ b/coworker/providers/llamacpp_setup.py@@ -22,7 +22,9 @@ The GUI polls `state()` while something runs, like the sandbox setup (setup_job.from __future__ import annotations+import datetimeimport functools+import hashlibimport jsonimport osimport re@@ -34,6 +36,7 @@ import sysimport threadingimport timefrom collections import deque+from email.utils import parsedate_to_datetimefrom pathlib import Pathfrom typing import Any, Callable, Optional@@ -48,6 +51,11 @@ DEFAULT_PORT = 8080LOAD_TIMEOUT_S = 900.0CHECK_TIMEOUT_S = 180.0INSTALL_LINES = 6+# Hugging Face answers 429 with how long to wait (per-IP windows of five minutes). Wait+# that long, within reason, a few times; then give up with the error.+RATE_LIMIT_RETRIES = 6+RATE_LIMIT_WAIT_MAX_S = 120+RATE_LIMIT_WAIT_DEFAULT_S = 5# Where Homebrew puts programs on Apple silicon and on Intel Macs; the desktop app's PATH# often has neither.@@ -121,6 +129,10 @@ def _free_bytes(path: Path) -> Optional[int]:return None+class _Cancelled(Exception):+ pass++# -- the models it offers --------------------------------------------------------------------@@ -221,6 +233,8 @@ def overview() -> dict[str, Any]:"size": m.get("size"),"fit": fit,"downloaded": _downloaded(m),+ "license": m.get("license"),+ "license_url": m.get("license_url"),})if m.get("ollama") and m["ollama"] not in have_ollama:@@ -248,20 +262,92 @@ def overview() -> dict[str, Any]:# -- downloads into llama.cpp's cache ---------------------------------------------------------def _hf_files(repo: str) -> tuple[str, dict[str, dict[str, Any]]]:- """(commit, {path: {size, oid}}) for a repo's main branch."""- rev = httpx.get(f"{HF}/api/models/{repo}/revision/main", timeout=30, follow_redirects=True)+def _retry_after(resp: httpx.Response) -> int:+ """Seconds to wait after a 429, from `Retry-After` (seconds or a date), `RateLimit-Reset`,+ or Hugging Face's `RateLimit: "resolvers";r=0;t=52` — bounded, at least one second."""+ h = resp.headers+ wait: Optional[float] = None+ raw = h.get("retry-after")+ if raw:+ try:+ wait = float(raw)+ except ValueError:+ try:+ wait = (parsedate_to_datetime(raw) - datetime.datetime.now(datetime.timezone.utc)).total_seconds()+ except (TypeError, ValueError):+ wait = None+ if wait is None and h.get("ratelimit-reset"):+ try:+ wait = float(h["ratelimit-reset"])+ except ValueError:+ wait = None+ if wait is None and h.get("ratelimit"):+ m = re.search(r"\bt=(\d+)", h["ratelimit"])+ wait = float(m.group(1)) if m else None+ if wait is None:+ wait = RATE_LIMIT_WAIT_DEFAULT_S+ return int(min(max(wait, 1), RATE_LIMIT_WAIT_MAX_S))+++def _hf_request(method: str, url: str, *, on_wait: Optional[Callable[[int], None]] = None, **kw: Any) -> httpx.Response:+ """One Hugging Face request; on 429 it waits as told and tries again, a few times."""+ kw.setdefault("timeout", 30)+ for attempt in range(RATE_LIMIT_RETRIES + 1):+ resp = httpx.request(method, url, **kw)+ if resp.status_code != 429 or attempt == RATE_LIMIT_RETRIES:+ return resp+ wait = _retry_after(resp)+ if on_wait:+ on_wait(wait)+ else:+ time.sleep(wait)+ return resp # pragma: no cover - the loop returns+++def _hf_files(repo: str, on_wait: Optional[Callable[[int], None]] = None) -> tuple[str, dict[str, dict[str, Any]]]:+ """(commit, {path: {size, oid, sha256}}) for a repo's main branch. `sha256` is the LFS+ object id, the checksum the download is verified against; None for a non-LFS file."""+ rev = _hf_request("GET", f"{HF}/api/models/{repo}/revision/main", on_wait=on_wait, follow_redirects=True)rev.raise_for_status()commit = rev.json()["sha"]- tree = httpx.get(f"{HF}/api/models/{repo}/tree/{commit}", timeout=30, follow_redirects=True)+ tree = _hf_request("GET", f"{HF}/api/models/{repo}/tree/{commit}", on_wait=on_wait, follow_redirects=True)tree.raise_for_status()files = {}for f in tree.json():lfs = f.get("lfs") or {}- files[f["path"]] = {"size": int(lfs.get("size") or f.get("size") or 0), "oid": lfs.get("oid") or f.get("oid")}+ oid = lfs.get("oid") or f.get("oid")+ files[f["path"]] = {"size": int(lfs.get("size") or f.get("size") or 0), "oid": oid, "sha256": lfs.get("oid")}return commit, files+def _hf_resolve_info(repo: str, filename: str, on_wait: Optional[Callable[[int], None]] = None) -> tuple[str, dict[str, Any]]:+ """What the file's own download address says about it, for when the API is not+ answering: the 302 to the CDN carries the commit, the size and the ETag. The ETag names+ the blob as huggingface_hub does; it is not trusted as a checksum."""+ resp = _hf_request("HEAD", f"{HF}/{repo}/resolve/main/{filename}", on_wait=on_wait, follow_redirects=False)+ if resp.status_code not in (200, 302, 307):+ raise RuntimeError(f"download failed: HTTP {resp.status_code}")+ h = resp.headers+ etag = (h.get("x-linked-etag") or h.get("etag") or "").strip().removeprefix("W/").strip('"')+ size = int(h.get("x-linked-size") or h.get("content-length") or 0)+ if not etag or not size:+ raise RuntimeError(f"download failed: no size for {filename}")+ return h.get("x-repo-commit") or "main", {"size": size, "oid": etag, "sha256": None}+++def _sha256(path: Path, cancel: Optional[threading.Event] = None) -> str:+ h = hashlib.sha256()+ with open(path, "rb") as fh:+ while True:+ if cancel is not None and cancel.is_set():+ raise _Cancelled()+ chunk = fh.read(8 << 20)+ if not chunk:+ break+ h.update(chunk)+ return h.hexdigest()++def _place(repo: str, commit: str, filename: str, blob: Path) -> Path:"""Link a downloaded blob into the snapshot folder, as huggingface_hub does."""snap = _repo_dir(repo) / "snapshots" / commit@@ -359,10 +445,6 @@ def _end(proc: subprocess.Popen) -> None:proc.wait(5)-class _Cancelled(Exception):- pass--class LlamaCppRunner:"""Installs llama.cpp and runs one llama-server. `phase` is one of idle, installing,downloading, loading, checking, running, failed. One thing at a time."""@@ -380,6 +462,10 @@ class LlamaCppRunner:self.error: Optional[str] = Noneself.check: Optional[dict[str, bool]] = Noneself.port: Optional[int] = None+ # "unverified" when a download could not be checked against its checksum.+ self.note: Optional[str] = None+ # Seconds until the next try while Hugging Face rate-limits us.+ self.retry_in: Optional[int] = None# Set by the manager: point the provider at the server and tick its model.self.on_running: Optional[Callable[[str, str], None]] = None@@ -398,6 +484,8 @@ class LlamaCppRunner:"model": dict(self.model) if self.model else None,"error": self.error,"check": dict(self.check) if self.check else None,+ "note": self.note,+ "retry_in": self.retry_in,"address": f"127.0.0.1:{self.port}" if self.port and self.phase == "running" else None,"autostart": bool(settings.get("autostart")),"last_choice": settings.get("choice"),@@ -543,8 +631,20 @@ class LlamaCppRunner:have = {f: _cached_file(entry["repo"], f) for f in wanted}if all(have.values()):return {"file": str(have[entry["file"]]), "draft": str(have[entry["draft"]]) if entry.get("draft") else None}- commit, files = _hf_files(entry["repo"])missing = [f for f in wanted if not have[f]]+ try:+ # Once, at the start: the commit, each file's size and its sha256 (the LFS id).+ commit, files = _hf_files(entry["repo"], self._rate_wait)+ except (httpx.HTTPError, KeyError, ValueError):+ # The API is not answering (down, or its own rate limit); the files come from+ # another address with its own limit, so download anyway, unverified.+ commit, files = "", {}+ for f in missing:+ c, info = _hf_resolve_info(entry["repo"], f, self._rate_wait)+ commit = commit or c+ files[f] = info+ with self._lock:+ self.note = "unverified"for f in missing:if f not in files:raise RuntimeError(f"{f} is no longer in {entry['repo']}")@@ -561,34 +661,70 @@ class LlamaCppRunner:part = blob.with_name(blob.name + ".incomplete")size = files[f]["size"]if not (blob.is_file() and blob.stat().st_size == size):- have_bytes = part.stat().st_size if part.is_file() else 0- headers = {"Range": f"bytes={have_bytes}-"} if have_bytes else {}url = f"{HF}/{entry['repo']}/resolve/{commit}/{f}"- with httpx.stream("GET", url, headers=headers, follow_redirects=True, timeout=60) as resp:- if resp.status_code == 200:- have_bytes = 0- elif resp.status_code != 206:- raise RuntimeError(f"download failed: HTTP {resp.status_code}")- with open(part, "ab" if have_bytes else "wb") as out:- got = have_bytes- last = 0.0- for chunk in resp.iter_bytes(1 << 20):- if self._cancel.is_set():- raise _Cancelled()- out.write(chunk)- got += len(chunk)- now = time.monotonic()- if now - last > 0.5:- last = now- self._set_progress(done_before + got, total, started)+ for attempt in range(RATE_LIMIT_RETRIES + 1):+ wait = self._fetch(url, part, size, done_before, total, started)+ if wait is None:+ break+ if attempt == RATE_LIMIT_RETRIES:+ raise RuntimeError("download failed: HTTP 429 (Hugging Face is rate-limiting downloads)")+ self._rate_wait(wait)if part.stat().st_size != size:raise RuntimeError("download incomplete; start again to resume")+ if files[f].get("sha256"):+ with self._lock:+ self.progress = {**(self.progress or {}), "done": done_before + size, "total": total, "verifying": True}+ if _sha256(part, self._cancel) != files[f]["sha256"]:+ part.unlink(missing_ok=True)+ raise RuntimeError(f"{f} did not match its checksum and was removed; start again to download it afresh")part.rename(blob)done_before += sizeself._set_progress(done_before, total, started)have[f] = _place(entry["repo"], commit, f, blob)return {"file": str(have[entry["file"]]), "draft": str(have[entry["draft"]]) if entry.get("draft") else None}+ def _fetch(self, url: str, part: Path, size: int, done_before: int, total: int, started: float) -> Optional[int]:+ """Download `url` into `part`, resuming what is there. None when done; on a 429,+ the seconds Hugging Face asks us to wait."""+ have_bytes = part.stat().st_size if part.is_file() else 0+ headers = {"Range": f"bytes={have_bytes}-"} if have_bytes else {}+ with httpx.stream("GET", url, headers=headers, follow_redirects=True, timeout=60) as resp:+ if resp.status_code == 429:+ return _retry_after(resp)+ if resp.status_code == 200:+ have_bytes = 0+ elif resp.status_code != 206:+ raise RuntimeError(f"download failed: HTTP {resp.status_code}")+ with open(part, "ab" if have_bytes else "wb") as out:+ got = have_bytes+ last = 0.0+ for chunk in resp.iter_bytes(1 << 20):+ if self._cancel.is_set():+ raise _Cancelled()+ out.write(chunk)+ got += len(chunk)+ now = time.monotonic()+ if now - last > 0.5:+ last = now+ self._set_progress(done_before + got, total, started)+ return None++ def _rate_wait(self, seconds: int) -> None:+ """Wait out a 429, a second at a time so the card can count down and Cancel works."""+ end = time.monotonic() + seconds+ while True:+ left = int(end - time.monotonic() + 0.999)+ if left <= 0:+ break+ with self._lock:+ self.retry_in = left+ if self._cancel.wait(min(1.0, left)):+ with self._lock:+ self.retry_in = None+ raise _Cancelled()+ with self._lock:+ self.retry_in = None+def _set_progress(self, done: int, total: int, started: float) -> None:elapsed = max(time.monotonic() - started, 0.001)rate = done / elapsed if done else 0@@ -715,6 +851,7 @@ class LlamaCppRunner:return {"ok": False, "error": "busy"}self._cancel.clear()self.phase, self.error, self.progress = phase, None, None+ self.note = self.retry_in = Noneself.lines.clear()def body() -> None:diff --git a/surfaces/gui/e2e/llamacpp-setup.spec.ts b/surfaces/gui/e2e/llamacpp-setup.spec.tsindex 25034d67..a3ed1f1c 100644--- a/surfaces/gui/e2e/llamacpp-setup.spec.ts+++ b/surfaces/gui/e2e/llamacpp-setup.spec.ts@@ -20,12 +20,14 @@ function base(over: Record<string, unknown> = {}) {supported: true, brew: "/opt/homebrew/bin/brew", installed: null, install_command: "brew install llama.cpp",cache_dir: "~/.cache/huggingface/hub", cache_free_bytes: 56 * GB,suggested: [- { id: "nemotron-3.5-lightning", name: "Nemotron 3.5 Lightning", vendor: "NVIDIA", quant: "Q8 + MTP", features: ["thinking", "tools"], size: 36e9, fit: "runs_well", downloaded: false },- { id: "gpt-oss-20b", name: "gpt-oss 20B", vendor: "OpenAI", quant: "MXFP4", features: ["reasoning", "tools"], size: 12e9, fit: "runs_well", downloaded: false },+ { id: "nemotron-3.5-lightning", name: "Nemotron 3.5 Lightning", vendor: "NVIDIA", quant: "Q8 + MTP", features: ["thinking", "tools"], size: 36e9, fit: "runs_well", downloaded: false,+ license: "OpenMDW-1.1", license_url: "https://openmdw.ai/license/1-1/" },+ { id: "gpt-oss-20b", name: "gpt-oss 20B", vendor: "OpenAI", quant: "MXFP4", features: ["reasoning", "tools"], size: 12e9, fit: "runs_well", downloaded: false,+ license: "Apache-2.0", license_url: "https://huggingface.co/openai/gpt-oss-20b/blob/main/LICENSE" },],ollama: [{ name: "qwen3-coder:30b", path: "/Users/me/.ollama/models/blobs/sha256-1194", size: 18e9, fit: "runs_well" }],ollama_pull: [{ name: "gpt-oss:20b", size: 12e9, fit: "runs_well", command: "ollama pull gpt-oss:20b" }],- phase: "idle", lines: [], progress: null, model: null, error: null, check: null, address: null,+ phase: "idle", lines: [], progress: null, model: null, error: null, check: null, note: null, retry_in: null, address: null,autostart: false, last_choice: null,...over,};@@ -90,6 +92,9 @@ test("llama.cpp: install, pick a model Ollama has, start it, and it runs", asyncawait expect(pick).toContainText("Nemotron 3.5 Lightning");await expect(page.getByTestId("llamacpp-pull")).toContainText("ollama pull gpt-oss:20b");await expect(page.getByTestId("llamacpp-cache")).toContainText("~/.cache/huggingface/hub");+ // Each model that downloads names its licence, linked, before Download.+ await expect(page.getByTestId("llamacpp-license-nemotron-3.5-lightning")).toContainText("Licence: OpenMDW-1.1");+ await expect(page.getByTestId("llamacpp-license-gpt-oss-20b")).toContainText("Licence: Apache-2.0");await expect(page.getByTestId("llamacpp-start")).toHaveText("Download and start");await page.getByTestId("llamacpp-model-o:qwen3-coder:30b").click();await expect(page.getByTestId("llamacpp-start")).toHaveText("Start");@@ -142,3 +147,84 @@ test("llama.cpp: Connect to it instead shows the address form, and back", asyncawait page.getByTestId("llamacpp-setup-here").click();await expect(page.getByTestId("llamacpp-setup")).toBeVisible();});++const INSTALLED = { installed: { path: "/opt/homebrew/bin/llama-server", version: "0.6.0" } };+const DOWNLOADING = {+ ...INSTALLED,+ phase: "downloading",+ model: { name: "Nemotron 3.5 Lightning", detail: "Q8 + MTP", alias: "nemotron-3.5-lightning", download: true },+ progress: { done: 12.4e9, total: 35.8e9, seconds_left: 840 },+};++test("llama.cpp: a download waits out a rate limit, verifies the file, and says when it could not", async ({ page }) => {+ // Each poll moves the download along: rate-limited, then verifying with the API gone.+ const states = [+ base({ ...DOWNLOADING, retry_in: 42 }),+ base({ ...DOWNLOADING, retry_in: 42 }),+ base({ ...DOWNLOADING, progress: { done: 35.8e9, total: 35.8e9, seconds_left: 0, verifying: true }, note: "unverified" }),+ ];+ let poll = 0;+ await page.route("**/v1/providers", (route) => route.fulfill({ json: [provider({ phase: "downloading", model: "Nemotron 3.5 Lightning" })] }));+ await page.route("**/v1/providers/llamacpp/models", (route) => route.fulfill({ json: { provider: "llamacpp", alive: false, models: [] } }));+ await page.route("**/v1/llamacpp/**", (route) => route.fulfill({ json: states[Math.min(poll++, states.length - 1)] }));+ await openPage(page);+ await expect(page.getByTestId("set-provider-llamacpp")).toContainText("Starting…");+ await page.getByTestId("set-provider-llamacpp").click();+ await expect(page.getByTestId("llamacpp-step-start")).toHaveAttribute("data-state", "now");+ const progress = page.getByTestId("llamacpp-progress");+ await expect(progress).toHaveText("Hugging Face is rate-limiting downloads, retrying in 42s");+ await expect(progress).toHaveText("Verifying the download…");+ await expect(page.getByTestId("llamacpp-note")).toContainText("checksum was not checked");+ await expect(page.getByTestId("llamacpp-cancel")).toBeVisible();+});++// The screenshots in docs/assets (light and dark): the three-step card before anything is+// installed, the model picker, and the running card.+for (const theme of ["light", "dark"] as const) {+ test(`llama.cpp: screenshots (${theme})`, async ({ page }) => {+ let state = base();+ await page.addInitScript((value) => localStorage.setItem("openwork-theme", value), theme);+ await page.setViewportSize({ width: 1280, height: 900 });+ await page.route("**/v1/providers", (route) =>+ route.fulfill({ json: [provider({ phase: state.phase, model: (state.model as { name: string } | null)?.name ?? null })] }),+ );+ await page.route("**/v1/providers/llamacpp/models", (route) =>+ route.fulfill({+ json: {+ provider: "llamacpp", alive: state.phase === "running",+ models: state.phase === "running"+ ? [{ model: "llamacpp:qwen3-coder:30b", name: "qwen3-coder:30b", size_bytes: 18e9, tools: true, thinking: false, vision: null, remote: false,+ parameter_size: null, quantization: null, context_max: 262144, context: 131072, context_from: "server", fit: "runs_well", recommendation: null }]+ : [],+ },+ }),+ );+ await page.route("**/v1/llamacpp/**", (route) => route.fulfill({ json: state }));+ // "Your system", as a 96 GB Mac reports it.+ await page.route("**/v1/system", (route) =>+ route.fulfill({+ json: { processor: "Apple M4 Max", graphics: "Apple M4 Max (40-core GPU)", kind: "apple_silicon", memory_bytes: 96 * GB, gpu_memory_bytes: null,+ storage_free_bytes: 420 * GB, storage_total_bytes: 926 * GB, model_memory_bytes: 72 * GB, runs_well_up_to_bytes: 64 * GB },+ }),+ );+ const suffix = theme === "dark" ? "-dark" : "";++ await openPage(page);+ await page.getByTestId("set-provider-llamacpp").click();+ await expect(page.getByTestId("llamacpp-step-get")).toHaveAttribute("data-state", "now");+ await page.screenshot({ path: `test-results/models-llamacpp-setup${suffix}.png` });++ state = base(INSTALLED);+ await page.getByTestId("set-back").click();+ await page.getByTestId("set-provider-llamacpp").click();+ await expect(page.getByTestId("llamacpp-step-pick")).toHaveAttribute("data-state", "now");+ await expect(page.getByTestId("llamacpp-license-nemotron-3.5-lightning")).toBeVisible();+ await page.screenshot({ path: `test-results/models-llamacpp-pick${suffix}.png` });++ state = base({ ...INSTALLED, ...RUNNING });+ await page.getByTestId("set-back").click();+ await page.getByTestId("set-provider-llamacpp").click();+ await expect(page.getByTestId("llamacpp-running")).toContainText("qwen3-coder:30b");+ await page.screenshot({ path: `test-results/models-llamacpp-running${suffix}.png` });+ });+}diff --git a/surfaces/gui/src/api.ts b/surfaces/gui/src/api.tsindex 223d5896..14f67379 100644--- a/surfaces/gui/src/api.ts+++ b/surfaces/gui/src/api.ts@@ -2743,15 +2743,23 @@ export interface LlamaCppSetup {size: number | null;fit: ModelFit;downloaded: boolean;+ // The model's licence, named and linked before Download (from its Hugging Face card).+ license: string | null;+ license_url: string | null;}[];ollama: { name: string; path: string; size: number; fit: ModelFit }[];ollama_pull: { name: string; size: number | null; fit: ModelFit; command: string }[];phase: LlamaCppPhase;lines: string[];- progress: { done: number; total: number; seconds_left: number | null } | null;+ // `verifying`: the file is down and its sha256 is being checked against Hugging Face's.+ progress: { done: number; total: number; seconds_left: number | null; verifying?: boolean } | null;model: { name: string; detail: string | null; alias: string; download?: boolean; context?: number; file?: string } | null;error: string | null;check: { answers: boolean; tools: boolean } | null;+ // "unverified": the Hugging Face API was unreachable, so the download's checksum was not checked.+ note: "unverified" | null;+ // Seconds until the next try while Hugging Face rate-limits the download.+ retry_in: number | null;address: string | null;autostart: boolean;last_choice: LlamaCppChoice | null;diff --git a/surfaces/gui/src/components/models/LlamaCppSetup.tsx b/surfaces/gui/src/components/models/LlamaCppSetup.tsxindex 4f2c9645..d8b475a4 100644--- a/surfaces/gui/src/components/models/LlamaCppSetup.tsx+++ b/surfaces/gui/src/components/models/LlamaCppSetup.tsx@@ -231,6 +231,7 @@ function SetupCard({{t("llamacpp.no_tools")}</p>)}+ {setup.note === "unverified" && <p className="text-meta text-faint mt-2.5" data-testid="llamacpp-note">{t("llamacpp.note_unverified")}</p>}<div className="grid grid-cols-[120px_1fr] gap-x-3 gap-y-1 text-ui mt-3"><span className="text-muted">{t("llamacpp.context")}</span><span>{fmtContext(m.context)}</span>@@ -320,6 +321,17 @@ function SetupCard({size={s.size}fit={s.fit}extra={s.downloaded ? t("llamacpp.downloaded") : undefined}+ line={+ s.license ? (+ <button+ className="text-label text-faint underline decoration-line underline-offset-2 hover:text-ink"+ onClick={(e) => { e.stopPropagation(); if (s.license_url) openExternal(s.license_url); }}+ data-testid={`llamacpp-license-${s.id}`}+ >+ {t("llamacpp.license", { name: s.license })} ↗+ </button>+ ) : undefined+ }/>))}{setup.suggested.length === 0 && <p className="px-3 py-2.5 text-meta text-faint">{t("llamacpp.none_fit")}</p>}@@ -382,10 +394,14 @@ function SetupCard({{phase === "downloading" && (<><p className="text-meta text-muted" data-testid="llamacpp-progress">- {p- ? t("llamacpp.downloading", { done: fmtBytes(p.done), total: fmtBytes(p.total) }) +- (minutes(p.seconds_left) != null ? " · " + t("llamacpp.minutes_left", { count: minutes(p.seconds_left) ?? 0 }) : "")- : t("llamacpp.download_starting")}+ {setup.retry_in != null+ ? t("llamacpp.rate_limited", { seconds: setup.retry_in })+ : p?.verifying+ ? t("llamacpp.verifying")+ : p+ ? t("llamacpp.downloading", { done: fmtBytes(p.done), total: fmtBytes(p.total) }) ++ (minutes(p.seconds_left) != null ? " · " + t("llamacpp.minutes_left", { count: minutes(p.seconds_left) ?? 0 }) : "")+ : t("llamacpp.download_starting")}</p><div className="h-1.5 rounded bg-paper overflow-hidden my-2"><i className="block h-full bg-muted rounded" style={{ width: `${p && p.total ? Math.round((100 * p.done) / p.total) : 0}%` }} />@@ -398,6 +414,7 @@ function SetupCard({<Check done={false} now={phase === "checking"} text={t("llamacpp.check_answers")} /><Check done={false} now={false} text={t("llamacpp.check_tools")} /></ul>+ {setup.note === "unverified" && <p className="text-meta text-faint mt-2" data-testid="llamacpp-note">{t("llamacpp.note_unverified")}</p>}<div className="flex items-center gap-2.5 mt-2.5"><button className={BTN} onClick={() => void act(cancelLlamaCpp)} data-testid="llamacpp-cancel">{t("llamacpp.cancel")}@@ -457,6 +474,7 @@ function ModelRow({fit,extra,action,+ line,}: {id: string;picked: string;@@ -467,6 +485,8 @@ function ModelRow({fit?: ModelFit;extra?: string;action?: ReactNode;+ // A third line under the name: the licence, for a model that downloads.+ line?: ReactNode;}) {const { t } = useTranslation();const on = picked === id && id !== "f:";@@ -484,6 +504,7 @@ function ModelRow({<span className="min-w-0"><span className="block text-ui font-medium truncate">{name}</span>{sub && <span className="block text-label text-faint truncate">{sub}</span>}+ {line && <span className="block truncate">{line}</span>}</span><span className="text-meta text-muted text-right">{action ?? (size ? fmtBytes(size) : "")}</span><span className={"text-meta text-right min-w-[72px] " + (fit === "runs_well" ? "text-ok" : "text-warnInk")}>diff --git a/surfaces/gui/src/locales/en.json b/surfaces/gui/src/locales/en.jsonindex 4e0b6a90..9e655759 100644--- a/surfaces/gui/src/locales/en.json+++ b/surfaces/gui/src/locales/en.json@@ -2874,6 +2874,7 @@"none_fit": "None of the suggested models fits this Mac's memory.","from_ollama": "From Ollama · nothing to download","downloaded": "Downloaded",+ "license": "Licence: {{name}}","choose_file": "Choose a GGUF file…","choose_file_sub": "A model file you downloaded yourself","change": "Change",@@ -2886,6 +2887,9 @@"start": "Start","download_starting": "Starting the download…","downloading": "Downloading · {{done}} of {{total}}",+ "verifying": "Verifying the download…",+ "rate_limited": "Hugging Face is rate-limiting downloads, retrying in {{seconds}}s",+ "note_unverified": "Hugging Face's API couldn't be reached, so this download's checksum was not checked.","minutes_left_one": "about {{count}} min left","minutes_left_other": "about {{count}} min left","check_download": "Download the model",@@ -2905,8 +2909,7 @@"own_server": "Already run llama-server yourself?","connect_instead": "Connect to it instead","setup_here": "Set up llama.cpp on this Mac instead"- }-,+ },"customization": {"title": "Customization","lead": "Pick the services OpenWorker uses behind its tools. Each choice applies to new sessions on this machine.",diff --git a/surfaces/gui/src/locales/zh.json b/surfaces/gui/src/locales/zh.jsonindex 04a6f7c5..0cb9f845 100644--- a/surfaces/gui/src/locales/zh.json+++ b/surfaces/gui/src/locales/zh.json@@ -2834,6 +2834,7 @@"none_fit": "推荐的模型都超出这台 Mac 的内存。","from_ollama": "来自 Ollama · 无需下载","downloaded": "已下载",+ "license": "许可证:{{name}}","choose_file": "选择 GGUF 文件…","choose_file_sub": "你自己下载的模型文件","change": "更改",@@ -2846,6 +2847,9 @@"start": "启动","download_starting": "正在开始下载…","downloading": "正在下载 · {{done}} / {{total}}",+ "verifying": "正在校验下载…",+ "rate_limited": "Hugging Face 正在限制下载,{{seconds}} 秒后重试",+ "note_unverified": "无法连接 Hugging Face API,未校验此次下载的校验和。","minutes_left_one": "约剩 {{count}} 分钟","minutes_left_other": "约剩 {{count}} 分钟","check_download": "下载模型",@@ -2865,8 +2869,7 @@"own_server": "已经自己运行 llama-server?","connect_instead": "改为连接到它","setup_here": "改为在这台 Mac 上设置 llama.cpp"- }-,+ },"customization": {"title": "自定义","lead": "选择 OpenWorker 各工具背后使用的服务。所做选择对本机的新会话生效。",diff --git a/tests/test_llamacpp_setup.py b/tests/test_llamacpp_setup.pyindex 46d9ff00..9d9b3923 100644--- a/tests/test_llamacpp_setup.py+++ b/tests/test_llamacpp_setup.py@@ -4,9 +4,11 @@ start, check, switch, stop and clean-up — against a stand-in llama-server."""from __future__ import annotations+import hashlibimport jsonimport osimport signal+import threadingimport sysimport textwrapimport time@@ -104,7 +106,7 @@ def test_download_lands_in_the_hugging_face_layout_and_resumes(tmp_path, monkeypentry = {"id": "t", "name": "T", "repo": "org/t-GGUF", "file": "t.gguf", "draft": "mtp-t.gguf"}blobs = {"t.gguf": b"M" * 5000, "mtp-t.gguf": b"D" * 300}monkeypatch.setattr(- setup, "_hf_files", lambda repo: ("c0ffee", {f: {"size": len(b), "oid": f"oid-{f}"} for f, b in blobs.items()})+ setup, "_hf_files", lambda repo, *a: ("c0ffee", {f: {"size": len(b), "oid": f"oid-{f}"} for f, b in blobs.items()}))# Half of the main file is already there from an interrupted run.part = setup._repo_dir("org/t-GGUF") / "blobs" / "oid-t.gguf.incomplete"@@ -136,6 +138,137 @@ def test_download_lands_in_the_hugging_face_layout_and_resumes(tmp_path, monkeypassert setup.runner().progress["done"] == setup.runner().progress["total"] == 5300+def test_the_catalog_names_each_model_licence_and_the_card_shows_it(monkeypatch):+ for m in setup.catalog():+ assert m["license"] and m["license_url"].startswith("https://"), m["id"]+ assert m["license_source"].startswith("https://huggingface.co/"), m["id"]+ monkeypatch.setattr(local_machine, "model_memory_bytes", lambda: 96 * GB)+ monkeypatch.setattr(setup, "find_llama_server", lambda: None)+ rows = {m["id"]: m for m in setup.overview()["suggested"]}+ assert rows["nemotron-3.5-lightning"]["license"] == "OpenMDW-1.1"+ assert rows["qwen3-coder-30b"]["license"] == "Apache-2.0" and rows["gpt-oss-20b"]["license"] == "Apache-2.0"+ assert all(r["license_url"].startswith("https://") for r in rows.values())+++def test_retry_after_is_read_from_the_headers_and_bounded():+ r = lambda **h: httpx.Response(429, headers=h) # noqa: E731+ assert setup._retry_after(r(**{"Retry-After": "7"})) == 7+ assert setup._retry_after(r(**{"RateLimit-Reset": "12"})) == 12+ # Hugging Face's own header: remaining and seconds to the window's end.+ assert setup._retry_after(r(**{"RateLimit": '"resolvers";r=0;t=52'})) == 52+ assert setup._retry_after(r(**{"Retry-After": "0"})) == 1+ assert setup._retry_after(r(**{"Retry-After": "9000"})) == setup.RATE_LIMIT_WAIT_MAX_S+ assert setup._retry_after(r()) == setup.RATE_LIMIT_WAIT_DEFAULT_S+ from email.utils import format_datetime+ import datetime as dt++ soon = format_datetime(dt.datetime.now(dt.timezone.utc) + dt.timedelta(seconds=30), usegmt=True)+ assert 27 <= setup._retry_after(r(**{"Retry-After": soon})) <= 30+++def _serve(monkeypatch, handler, *, api=True, files=True):+ """Route the module's Hugging Face calls (API and file downloads) to `handler`."""+ client = httpx.Client(transport=httpx.MockTransport(handler))+ if api:+ monkeypatch.setattr(httpx, "request", lambda method, url, **kw: client.request(method, url, headers=kw.get("headers")))+ if files:+ monkeypatch.setattr(httpx, "stream", lambda method, url, headers=None, **kw: client.stream(method, url, headers=headers))+++def test_download_verifies_the_checksum_and_removes_a_bad_file(tmp_path, monkeypatch):+ good = b"G" * 4000+ sha = hashlib.sha256(good).hexdigest()+ entry = {"id": "t", "name": "T", "repo": "org/t-GGUF", "file": "t.gguf"}+ monkeypatch.setattr(setup, "_hf_files", lambda repo, *a: ("c0ffee", {"t.gguf": {"size": 4000, "oid": sha, "sha256": sha}}))+ body = {"ok": good, "bad": b"B" * 4000}+ serving = ["ok"]+ _serve(monkeypatch, lambda req: httpx.Response(200, content=body[serving[0]]), api=False)+ r = setup.runner()+ got = r._download(entry)+ assert Path(got["file"]).read_bytes() == good+ assert (setup._repo_dir("org/t-GGUF") / "blobs" / sha).is_file()+ assert r.progress["done"] == r.progress["total"] == 4000 and r.state()["note"] is None++ # The same size, different bytes: the file is refused and removed, nothing is placed.+ serving[0] = "bad"+ monkeypatch.setattr(setup, "_hf_files", lambda repo, *a: ("c0ffee", {"t.gguf": {"size": 4000, "oid": "x" * 64, "sha256": "x" * 64}}))+ with pytest.raises(RuntimeError, match="checksum"):+ setup.LlamaCppRunner()._download({**entry, "repo": "org/u-GGUF"})+ blobs = setup._repo_dir("org/u-GGUF") / "blobs"+ assert not list(blobs.iterdir()) and not (setup._repo_dir("org/u-GGUF") / "snapshots").exists()+++def test_without_the_api_the_download_is_unverified_and_says_so(tmp_path, monkeypatch):+ data = b"Q" * 2500+ entry = {"id": "t", "name": "T", "repo": "org/t-GGUF", "file": "t.gguf"}++ def handler(req: httpx.Request) -> httpx.Response:+ if req.url.path.startswith("/api/"):+ raise httpx.ConnectError("api down")+ if req.method == "HEAD":+ # What huggingface.co's 302 to the CDN says about the file.+ return httpx.Response(302, headers={"Location": "https://cdn.example/x", "X-Repo-Commit": "abc123",+ "X-Linked-Size": str(len(data)), "X-Linked-ETag": '"etag-t"'})+ assert req.url.path == "/org/t-GGUF/resolve/abc123/t.gguf"+ return httpx.Response(200, content=data)++ _serve(monkeypatch, handler)+ r = setup.runner()+ got = r._download(entry)+ assert Path(got["file"]) == setup._repo_dir("org/t-GGUF") / "snapshots" / "abc123" / "t.gguf"+ assert Path(got["file"]).read_bytes() == data+ assert (setup._repo_dir("org/t-GGUF") / "blobs" / "etag-t").is_file()+ assert r.state()["note"] == "unverified"+++def test_a_429_is_waited_out_as_hugging_face_asks(tmp_path, monkeypatch):+ data = b"R" * 1200+ sha = hashlib.sha256(data).hexdigest()+ entry = {"id": "t", "name": "T", "repo": "org/t-GGUF", "file": "t.gguf"}+ limited = {"/api/models/org/t-GGUF/revision/main": 1, "/org/t-GGUF/resolve/c0ffee/t.gguf": 1}++ def handler(req: httpx.Request) -> httpx.Response:+ path = req.url.path+ if limited.get(path):+ limited[path] -= 1+ hdr = {"Retry-After": "1"} if path.startswith("/api/") else {"RateLimit": '"resolvers";r=0;t=1'}+ return httpx.Response(429, headers=hdr)+ if path.endswith("/revision/main"):+ return httpx.Response(200, json={"sha": "c0ffee"})+ if "/tree/" in path:+ return httpx.Response(200, json=[{"path": "t.gguf", "size": len(data), "lfs": {"oid": sha, "size": len(data)}}])+ return httpx.Response(200, content=data)++ _serve(monkeypatch, handler)+ r = setup.runner()+ waits = []+ real = r._rate_wait+ monkeypatch.setattr(r, "_rate_wait", lambda s: (waits.append(s), real(s)))+ got = r._download(entry)+ assert waits == [1, 1]+ assert Path(got["file"]).read_bytes() == data and r.state()["retry_in"] is None++ # While it waits, the card can count down; Cancel ends the wait at once.+ t = threading.Thread(target=lambda: pytest.raises(setup._Cancelled, real, 30))+ t.start()+ time.sleep(0.3)+ assert r.state()["retry_in"] == 30+ r.cancel()+ t.join(5)+ assert not t.is_alive() and r.state()["retry_in"] is None+++def test_too_many_429s_end_with_a_clear_error(tmp_path, monkeypatch):+ entry = {"id": "t", "name": "T", "repo": "org/t-GGUF", "file": "t.gguf"}+ monkeypatch.setattr(setup, "_hf_files", lambda repo, *a: ("c0ffee", {"t.gguf": {"size": 10, "oid": "o", "sha256": None}}))+ _serve(monkeypatch, lambda req: httpx.Response(429, headers={"Retry-After": "1"}), api=False)+ monkeypatch.setattr(setup, "RATE_LIMIT_RETRIES", 1)+ r = setup.runner()+ monkeypatch.setattr(r, "_rate_wait", lambda s: None)+ with pytest.raises(RuntimeError, match="rate-limiting"):+ r._download(entry)++# -- the managed server, against a stand-in llama-server --------------------------------FAKE = textwrap.dedent(