Skip to content
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.json
index 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.py
index 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 datetime
import functools
+import hashlib
import json
import os
import re
@@ -34,6 +36,7 @@ import sys
import threading
import time
from collections import deque
+from email.utils import parsedate_to_datetime
from pathlib import Path
from typing import Any, Callable, Optional
@@ -48,6 +51,11 @@ DEFAULT_PORT = 8080
LOAD_TIMEOUT_S = 900.0
CHECK_TIMEOUT_S = 180.0
INSTALL_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] = None
self.check: Optional[dict[str, bool]] = None
self.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 += size
self._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 = None
self.lines.clear()
def body() -> None:
diff --git a/surfaces/gui/e2e/llamacpp-setup.spec.ts b/surfaces/gui/e2e/llamacpp-setup.spec.ts
index 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", async
await 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", async
await 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.ts
index 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.tsx
index 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.json
index 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.json
index 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.py
index 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 hashlib
import json
import os
import signal
+import threading
import sys
import textwrap
import time
@@ -104,7 +106,7 @@ def test_download_lands_in_the_hugging_face_layout_and_resumes(tmp_path, monkeyp
entry = {"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, monkeyp
assert 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(