Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
feat(ollama): Hugging Face GGUF browsing — search repositories, list quantizations, build the pull name
rubenluetke10-beepf5ef226fd6fc
diff --git a/jarvis/brain/hf_gguf.py b/jarvis/brain/hf_gguf.pynew file mode 100644index 0000000000..ef2c0968c7--- /dev/null+++ b/jarvis/brain/hf_gguf.py@@ -0,0 +1,312 @@+"""Browse GGUF repositories on Hugging Face for an Ollama pull.++Ollama pulls ``hf.co/<user>/<repo>[:<quant>]`` through the same ``/api/pull``+as its own library. What it does NOT offer is a way to find those names. This+module is that finder — read-only, anonymous JSON, no scraping:++- search: ``GET /api/models?filter=gguf&search=…&sort=…&expand[]=gguf``+- files: ``GET /api/models/{user}/{repo}/tree/main`` filtered to ``.gguf``++Contract, same as :mod:`jarvis.brain.ollama_library`: every failure degrades+to ``{"repos"/"files": [], "error": "<English sentence>"}`` and is logged;+the pull itself never depends on this module, the local server stays the+authority on whether a name exists.++Rate limits: anonymous callers get 500 API calls per 5-minute window per IP+(shared with everything else the box does). A 10-minute cache keeps a browsing+session far below that; a 429 names the window and the optional token+(``get_secret("huggingface")``, sent as a bearer when present, never required).++Lazy-importable on purpose: the routes import this module only when+``[brain.providers.ollama].hf_enabled`` is true, so an install that wants no+outbound Hugging Face traffic makes none.+"""++from __future__ import annotations++import logging+import re+import time+from typing import Any, Literal++import httpx++from jarvis.brain.ollama_pull import accelerator_gb, fit_verdict, total_memory_gb++log = logging.getLogger(__name__)++_HF_ROOT = "https://huggingface.co"++#: Short connect so a dead network fails the panel fast; the tree listing of a+#: repository with dozens of quantizations is still small JSON.+_FETCH_TIMEOUT = httpx.Timeout(connect=3.0, read=10.0, write=10.0, pool=10.0)++#: Ten minutes, like the Ollama library browser: the catalogue moves slowly and+#: the panel re-queries on every keystroke burst.+_CACHE_TTL_SECONDS = 600.0++#: One page of results; a narrower query beats scrolling.+_SEARCH_LIMIT = 30+_SEARCH_LIMIT_MAX = 100++SortKey = Literal["downloads", "lastModified", "trendingScore"]+_SORT_KEYS: tuple[str, ...] = ("downloads", "lastModified", "trendingScore")++#: Hugging Face namespaces and repository names. Doubles as the URL-injection+#: guard: a value that fails this never reaches the fetch layer.+_SEGMENT_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,95}$")++#: A quantization label inside a GGUF filename, e.g. ``Q4_K_M``, ``IQ2_XS``,+#: ``Q8_0``, ``F16``, ``BF16``. Anchored on separators so ``iq2`` in an+#: unrelated word does not match.+_QUANT_RE = re.compile(+ r"(?<![A-Za-z0-9])((?:I?Q\d(?:_[A-Z0-9]+)*)|F16|F32|BF16)(?![A-Za-z0-9])",+ re.IGNORECASE,+)++_RATE_LIMIT_SENTENCE = (+ "Hugging Face is rate-limiting this machine (anonymous callers get 500 "+ "requests per 5-minute window). Wait a few minutes, or add a Hugging Face "+ "token under API keys to raise the limit."+)+_OFFLINE_SENTENCE = (+ "huggingface.co did not answer, so repositories cannot be browsed right "+ "now. Pulling by exact hf.co/<user>/<repo> name still works."+)++# Caches hold the CATALOGUE only — fit verdicts are judged fresh per call.+_search_cache: dict[str, tuple[float, list[dict[str, Any]]]] = {}+_files_cache: dict[str, tuple[float, list[dict[str, Any]]]] = {}+++# ── validation & naming ───────────────────────────────────────────────────+++def valid_segment(value: str) -> bool:+ """True when ``value`` is a well-formed Hugging Face user or repo name."""+ return bool(value) and ".." not in value and _SEGMENT_RE.match(value) is not None+++def pull_name(user: str, repo: str, quant: str | None = None) -> str:+ """The name Ollama pulls: ``hf.co/{user}/{repo}`` plus ``:{quant}`` if given.++ Raises ``ValueError`` on a malformed segment so a caller can never build a+ name that smuggles a path or query into ``/api/pull``.+ """+ if not (valid_segment(user) and valid_segment(repo)):+ raise ValueError("Not a valid Hugging Face repository name.")+ name = f"hf.co/{user}/{repo}"+ quant = (quant or "").strip()+ if quant:+ if not _QUANT_RE.fullmatch(quant) and not _SEGMENT_RE.match(quant):+ raise ValueError("Not a valid quantization label.")+ name = f"{name}:{quant}"+ return name+++def parse_quant(filename: str) -> str | None:+ """The quantization label a GGUF filename carries, or ``None``.++ Upper-cased so ``q4_k_m`` and ``Q4_K_M`` build the same pull name — Ollama+ matches the suffix case-insensitively anyway.+ """+ stem = filename.rsplit("/", 1)[-1]+ if stem.lower().endswith(".gguf"):+ stem = stem[: -len(".gguf")]+ match = _QUANT_RE.search(stem)+ return match.group(1).upper() if match else None+++# ── fetch layer ───────────────────────────────────────────────────────────+++def _bearer() -> str | None:+ """An optional Hugging Face token; absence is the normal state."""+ try:+ from jarvis.core import config as cfg_mod # noqa: PLC0415 — lazy (AP-26)++ return cfg_mod.get_secret("huggingface", env_fallback="HF_TOKEN") or None+ except Exception: # noqa: BLE001 — a broken secret store must not block browsing+ log.debug("hf-gguf: token lookup failed", exc_info=True)+ return None+++async def _fetch_json(+ path: str, params: list[tuple[str, str]] | None = None+) -> tuple[Any | None, str | None]:+ """``(payload, error)`` for one Hugging Face API call — exactly one is non-None."""+ url = f"{_HF_ROOT}{path}"+ headers = {"User-Agent": "Jarvis-Agents local model browser"}+ if token := _bearer():+ headers["Authorization"] = f"Bearer {token}"+ try:+ async with httpx.AsyncClient(+ timeout=_FETCH_TIMEOUT, follow_redirects=True, headers=headers+ ) as client:+ resp = await client.get(url, params=list(params or []))+ except Exception as exc: # noqa: BLE001 — offline is a normal state here+ log.info("hf-gguf: %s unreachable (%s)", url, type(exc).__name__)+ return None, _OFFLINE_SENTENCE+ if resp.status_code == 429:+ log.info("hf-gguf: rate-limited by huggingface.co on %s", path)+ return None, _RATE_LIMIT_SENTENCE+ if resp.status_code == 404:+ return None, "Hugging Face has no repository with that name."+ if resp.status_code in (401, 403):+ return None, (+ "Hugging Face refused access to this repository. It is private or "+ "gated — a token under API keys is needed to browse it."+ )+ if resp.status_code != 200:+ return None, (+ f"huggingface.co answered {resp.status_code}, so repositories cannot "+ "be browsed right now."+ )+ try:+ return resp.json(), None+ except ValueError:+ log.warning("hf-gguf: %s answered non-JSON", url)+ return None, "huggingface.co answered something that is not JSON."+++def _cache_get(cache: dict[str, tuple[float, Any]], key: str) -> Any | None:+ hit = cache.get(key)+ if hit and (time.monotonic() - hit[0]) < _CACHE_TTL_SECONDS:+ return hit[1]+ return None+++# ── search ────────────────────────────────────────────────────────────────+++def _shape_repo(raw: dict[str, Any]) -> dict[str, Any] | None:+ """One search entry in the shape the panel reads; ``None`` if unreadable."""+ repo_id = raw.get("id") or raw.get("modelId")+ if not isinstance(repo_id, str) or "/" not in repo_id:+ return None+ author = raw.get("author") or repo_id.split("/", 1)[0]+ gguf: dict[str, Any] = raw["gguf"] if isinstance(raw.get("gguf"), dict) else {}+ total = gguf.get("total")+ context = gguf.get("context_length")+ return {+ "id": repo_id,+ "author": str(author),+ "downloads": int(raw.get("downloads") or 0),+ "likes": int(raw.get("likes") or 0),+ "last_modified": str(raw.get("lastModified") or ""),+ "architecture": str(gguf.get("architecture") or ""),+ "total_params": int(total) if isinstance(total, (int, float)) else None,+ "context_length": int(context) if isinstance(context, (int, float)) else None,+ }+++def parse_search_payload(payload: Any) -> list[dict[str, Any]]:+ """Repositories from a ``/api/models`` answer, order kept, junk skipped."""+ if not isinstance(payload, list):+ return []+ repos: list[dict[str, Any]] = []+ for raw in payload:+ if isinstance(raw, dict) and (shaped := _shape_repo(raw)):+ repos.append(shaped)+ return repos+++async def search(q: str, *, sort: str = "downloads", limit: int = _SEARCH_LIMIT) -> dict[str, Any]:+ """GGUF repositories matching ``q``: ``{"repos": [...], "error": str | None}``."""+ q = (q or "").strip()+ if sort not in _SORT_KEYS:+ sort = "downloads"+ limit = max(1, min(int(limit or _SEARCH_LIMIT), _SEARCH_LIMIT_MAX))+ key = f"{sort}|{limit}|{q.lower()}"+ repos = _cache_get(_search_cache, key)+ if repos is None:+ params: list[tuple[str, str]] = [+ ("filter", "gguf"),+ ("sort", sort),+ ("direction", "-1"),+ ("limit", str(limit)),+ ("expand[]", "gguf"),+ ]+ if q:+ params.insert(1, ("search", q))+ payload, error = await _fetch_json("/api/models", params)+ if error:+ return {"repos": [], "error": error}+ repos = parse_search_payload(payload)+ if not repos and payload:+ log.warning("hf-gguf: search answered %d entries, none readable", len(payload))+ return {+ "repos": [],+ "error": "Hugging Face answered in a shape this version cannot read.",+ }+ _search_cache[key] = (time.monotonic(), [dict(r) for r in repos])+ return {"repos": [dict(r) for r in repos], "error": None}+++# ── files ─────────────────────────────────────────────────────────────────+++def parse_tree_payload(payload: Any) -> list[dict[str, Any]]:+ """``.gguf`` entries from a ``/tree/main`` answer with quant and size."""+ if not isinstance(payload, list):+ return []+ files: list[dict[str, Any]] = []+ for raw in payload:+ if not isinstance(raw, dict) or raw.get("type") != "file":+ continue+ path = raw.get("path")+ if not isinstance(path, str) or not path.lower().endswith(".gguf"):+ continue+ # Only the LFS size is the weight file's size; the plain ``size`` of a+ # pointer file is a few hundred bytes and would read as "0 GB, fits".+ lfs: dict[str, Any] = raw["lfs"] if isinstance(raw.get("lfs"), dict) else {}+ size = lfs.get("size")+ size_gb = round(size / 1e9, 2) if isinstance(size, (int, float)) and size > 0 else None+ files.append({"filename": path, "quant": parse_quant(path), "size_gb": size_gb})+ files.sort(key=lambda f: (f["size_gb"] is None, f["size_gb"] or 0.0))+ return files+++async def files(user: str, repo: str) -> dict[str, Any]:+ """GGUF files of one repository with a fit verdict each.++ ``{"files": [{filename, quant, size_gb, fit, fit_note}], "error": str | None}``.+ The catalogue half is cached; the verdicts are judged fresh against this+ machine on every call.+ """+ if not (valid_segment(user) and valid_segment(repo)):+ return {"files": [], "error": "Not a valid Hugging Face repository name."}+ key = f"{user}/{repo}"+ listed = _cache_get(_files_cache, key)+ if listed is None:+ payload, error = await _fetch_json(f"/api/models/{user}/{repo}/tree/main")+ if error:+ return {"files": [], "error": error}+ listed = parse_tree_payload(payload)+ if not listed:+ return {"files": [], "error": f"{key} holds no GGUF file Ollama could pull."}+ _files_cache[key] = (time.monotonic(), [dict(f) for f in listed])++ memory_gb = total_memory_gb()+ accel, _source = accelerator_gb()+ out: list[dict[str, Any]] = []+ for entry in listed:+ row = dict(entry)+ if row["size_gb"] is None:+ row["fit"], row["fit_note"] = "unknown", ""+ else:+ row["fit"], row["fit_note"] = fit_verdict(row["size_gb"], memory_gb, accel)+ out.append(row)+ return {"files": out, "error": None}+++__all__ = [+ "SortKey",+ "files",+ "parse_quant",+ "parse_search_payload",+ "parse_tree_payload",+ "pull_name",+ "search",+ "valid_segment",+]diff --git a/jarvis/brain/ollama_pull.py b/jarvis/brain/ollama_pull.pyindex ceddb0d6d3..cccf720c50 100644--- a/jarvis/brain/ollama_pull.py+++ b/jarvis/brain/ollama_pull.py@@ -486,6 +486,37 @@ async def recommendations() -> dict[str, Any]:}+#: Name prefixes Ollama resolves against Hugging Face instead of its own+#: library (``ollama pull hf.co/<user>/<repo>[:<quant>]``).+HF_NAME_PREFIXES = ("hf.co/", "huggingface.co/")+++def not_found_message(model: str) -> str:+ """The English sentence for a ``/api/pull`` 404, by where the name lives.++ A Hugging Face name is never in the Ollama library, so pointing at+ ollama.com/library would send the user to the wrong catalogue; the+ sentence names the repository (or the quantization suffix) instead.+ """+ lowered = model.lower()+ if lowered.startswith(HF_NAME_PREFIXES):+ repo, _, quant = model.partition(":")+ if quant:+ return (+ f"Hugging Face has no GGUF file matching '{quant}' in {repo}, or "+ "the repository does not exist. Pick one of the listed "+ "quantizations and try again."+ )+ return (+ f"Ollama could not find the repository '{repo}' on Hugging Face, or "+ "it holds no GGUF file. Check the name at huggingface.co and try again."+ )+ return (+ f"Ollama does not know a model called '{model}'. Check the "+ "name at ollama.com/library and try again."+ )++async def _run_pull(model: str) -> None:"""Stream ``/api/pull`` into the run state. Never raises."""run = _run_for(model)@@ -499,10 +530,7 @@ async def _run_pull(model: str) -> None:):if resp.status_code == 404:run.state = "error"- run.message = (- f"Ollama does not know a model called '{model}'. Check the "- "name at ollama.com/library and try again."- )+ run.message = not_found_message(model)returnresp.raise_for_status()async for line in resp.aiter_lines():@@ -616,6 +644,7 @@ async def pull_status(model: str) -> dict[str, Any]:__all__ = [+ "HF_NAME_PREFIXES","PULL_CAPABLE_PROVIDERS","RECOMMENDED_MODELS","ROLE_ORDER",@@ -624,6 +653,7 @@ __all__ = ["accelerator_gb","fit_verdict","installed_models",+ "not_found_message","pull_status","recommendations","registry_size_gb",diff --git a/tests/fixtures/brain/hf_models_search.json b/tests/fixtures/brain/hf_models_search.jsonnew file mode 100644index 0000000000..e826376646--- /dev/null+++ b/tests/fixtures/brain/hf_models_search.json@@ -0,0 +1,54 @@+[+ {+ "_id": "68f1a2b3c4d5e6f7a8b9c0d1",+ "id": "unsloth/Qwen3.8-27B-GGUF",+ "author": "unsloth",+ "private": false,+ "downloads": 184213,+ "likes": 412,+ "tags": ["gguf", "qwen3", "text-generation", "license:apache-2.0"],+ "lastModified": "2026-08-19T10:14:02.000Z",+ "createdAt": "2026-08-17T08:00:00.000Z",+ "modelId": "unsloth/Qwen3.8-27B-GGUF",+ "gguf": {+ "total": 27200000000,+ "architecture": "qwen3",+ "context_length": 262144,+ "chat_template": "{% for message in messages %}…{% endfor %}",+ "bos_token": "<|endoftext|>",+ "eos_token": "<|im_end|>"+ }+ },+ {+ "_id": "68f1a2b3c4d5e6f7a8b9c0d2",+ "id": "bartowski/gemma-4-12b-it-GGUF",+ "author": "bartowski",+ "private": false,+ "downloads": 99120,+ "likes": 233,+ "tags": ["gguf", "gemma4", "text-generation"],+ "lastModified": "2026-08-02T21:40:11.000Z",+ "createdAt": "2026-07-30T00:00:00.000Z",+ "modelId": "bartowski/gemma-4-12b-it-GGUF",+ "gguf": {+ "total": 12300000000,+ "architecture": "gemma4",+ "context_length": 131072+ }+ },+ {+ "_id": "68f1a2b3c4d5e6f7a8b9c0d3",+ "id": "someone/mystery-GGUF",+ "private": false,+ "downloads": 12,+ "likes": 0,+ "tags": ["gguf"],+ "lastModified": "2026-06-01T00:00:00.000Z",+ "modelId": "someone/mystery-GGUF"+ },+ {+ "_id": "68f1a2b3c4d5e6f7a8b9c0d4",+ "id": "not-a-repo-id",+ "downloads": 1+ }+]diff --git a/tests/fixtures/brain/hf_tree_main.json b/tests/fixtures/brain/hf_tree_main.jsonnew file mode 100644index 0000000000..e1d0ab7b66--- /dev/null+++ b/tests/fixtures/brain/hf_tree_main.json@@ -0,0 +1,69 @@+[+ {+ "type": "file",+ "oid": "0a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3",+ "size": 1519,+ "path": ".gitattributes"+ },+ {+ "type": "file",+ "oid": "1a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3",+ "size": 4021,+ "path": "README.md"+ },+ {+ "type": "file",+ "oid": "2a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3",+ "size": 135,+ "lfs": {+ "oid": "9f3c2b1a0e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1",+ "size": 16700000000,+ "pointerSize": 135+ },+ "path": "Qwen3.8-27B-Q4_K_M.gguf"+ },+ {+ "type": "file",+ "oid": "3a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3",+ "size": 135,+ "lfs": {+ "oid": "8f3c2b1a0e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1",+ "size": 29100000000,+ "pointerSize": 135+ },+ "path": "Qwen3.8-27B-Q8_0.gguf"+ },+ {+ "type": "file",+ "oid": "4a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3",+ "size": 135,+ "lfs": {+ "oid": "7f3c2b1a0e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1",+ "size": 9400000000,+ "pointerSize": 135+ },+ "path": "Qwen3.8-27B-IQ2_XS.gguf"+ },+ {+ "type": "file",+ "oid": "5a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3",+ "size": 135,+ "lfs": {+ "oid": "6f3c2b1a0e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1",+ "size": 54400000000,+ "pointerSize": 135+ },+ "path": "Qwen3.8-27B-BF16.gguf"+ },+ {+ "type": "file",+ "oid": "6a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3",+ "size": 135,+ "path": "weird-no-size.gguf"+ },+ {+ "type": "directory",+ "oid": "7a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3",+ "path": "imatrix"+ }+]diff --git a/tests/integration/test_hf_gguf_live.py b/tests/integration/test_hf_gguf_live.pynew file mode 100644index 0000000000..f05cd439f3--- /dev/null+++ b/tests/integration/test_hf_gguf_live.py@@ -0,0 +1,46 @@+"""The Hugging Face finder must keep understanding the LIVE API.++The unit tests pin the parsers against JSON snapshots, which cannot notice+Hugging Face renaming a field. This guard fetches one real search and one+real tree listing and asserts the shapes still read. Network-dependent, so it+is marked ``integration`` and self-skips when huggingface.co cannot be reached+or rate-limits the runner. Run explicitly with ``pytest -m integration``.+"""++from __future__ import annotations++import pytest++import jarvis.brain.hf_gguf as hf++pytestmark = pytest.mark.integration+++def _skip_on_network_error(error: str | None) -> None:+ if error and ("did not answer" in error or "rate-limiting" in error):+ pytest.skip(f"huggingface.co unavailable: {error}")+++async def test_live_search_and_tree_still_parse() -> None:+ hf._search_cache.clear()+ hf._files_cache.clear()++ result = await hf.search("qwen", sort="downloads", limit=5)+ _skip_on_network_error(result["error"])+ assert result["error"] is None, result["error"]+ assert result["repos"], "the live search answered no GGUF repository for 'qwen'"+ first = result["repos"][0]+ assert "/" in first["id"]+ assert first["downloads"] > 0+ assert first["architecture"], "expand[]=gguf no longer carries the architecture"++ user, repo = first["id"].split("/", 1)+ listing = await hf.files(user, repo)+ _skip_on_network_error(listing["error"])+ assert listing["error"] is None, listing["error"]+ assert listing["files"], f"{first['id']} listed no .gguf file"+ sized = [f for f in listing["files"] if f["size_gb"] is not None]+ assert sized, "tree/main no longer reports lfs.size for GGUF files"+ assert any(f["quant"] for f in listing["files"]), "no quantization label parsed"+ assert all(f["fit"] in ("comfortable", "tight", "unknown") for f in listing["files"])diff --git a/tests/unit/brain/test_hf_gguf.py b/tests/unit/brain/test_hf_gguf.pynew file mode 100644index 0000000000..bac88e8bf9--- /dev/null+++ b/tests/unit/brain/test_hf_gguf.py@@ -0,0 +1,311 @@+"""Hugging Face GGUF browsing: honest parsing, honest degradation, safe names.++The module is a read-only finder for ``hf.co/<user>/<repo>:<quant>`` names.+These tests pin the pieces that would silently lie if they broke — a filename+whose quant is misread (the pull then downloads the wrong file), a repository+name that smuggles a path into the URL, a rate limit that reads as "no+results", and a fit verdict that survives the cache when it must not.+"""++from __future__ import annotations++import json+from pathlib import Path+from typing import Any++import pytest++import jarvis.brain.hf_gguf as hf+import jarvis.brain.ollama_pull as pull++_FIXTURES = Path(__file__).resolve().parents[2] / "fixtures" / "brain"++[email protected](autouse=True)+def _fresh_caches():+ hf._search_cache.clear()+ hf._files_cache.clear()+ yield+ hf._search_cache.clear()+ hf._files_cache.clear()+++def search_payload() -> list[dict[str, Any]]:+ return json.loads((_FIXTURES / "hf_models_search.json").read_text(encoding="utf-8"))+++def tree_payload() -> list[dict[str, Any]]:+ return json.loads((_FIXTURES / "hf_tree_main.json").read_text(encoding="utf-8"))+++def _fake_fetch(payload: Any, error: str | None, calls: list[tuple[str, Any]]):+ async def fetch(+ path: str, params: list[tuple[str, str]] | None = None+ ) -> tuple[Any | None, str | None]:+ calls.append((path, params))+ return payload, error++ return fetch+++def _machine(monkeypatch):+ """32 GB RAM, a 16 GB card."""+ monkeypatch.setattr(hf, "total_memory_gb", lambda: 32.0)+ monkeypatch.setattr(hf, "accelerator_gb", lambda: (16.0, "cuda"))+++# ── quant parsing & pull names ───────────────────────────────────────────+++ ("filename", "expected"),+ [+ ("Qwen3.8-27B-Q4_K_M.gguf", "Q4_K_M"),+ ("qwen3.8-27b-q4_k_m.gguf", "Q4_K_M"),+ ("model-IQ2_XS.gguf", "IQ2_XS"),+ ("model.Q8_0.gguf", "Q8_0"),+ ("model-BF16.gguf", "BF16"),+ ("gemma-4-12b-it-f16.gguf", "F16"),+ ("split/Qwen-Q5_K_S-00001-of-00002.gguf", "Q5_K_S"),+ ("model-without-a-label.gguf", None),+ ],+)+def test_quant_is_read_from_the_filename(filename: str, expected: str | None) -> None:+ assert hf.parse_quant(filename) == expected+++def test_pull_name_builds_the_ollama_form() -> None:+ assert hf.pull_name("unsloth", "Qwen3.8-27B-GGUF") == "hf.co/unsloth/Qwen3.8-27B-GGUF"+ assert (+ hf.pull_name("unsloth", "Qwen3.8-27B-GGUF", "Q4_K_M")+ == "hf.co/unsloth/Qwen3.8-27B-GGUF:Q4_K_M"+ )+ assert hf.pull_name("u", "r", " ") == "hf.co/u/r"+++ ("user", "repo", "quant"),+ [+ ("../etc", "repo", None),+ ("user", "repo/../../x", None),+ ("user?x=1", "repo", None),+ ("user", "repo", "Q4_K_M?download=true"),+ ("", "repo", None),+ ],+)+def test_pull_name_rejects_path_and_query_shaped_segments(+ user: str, repo: str, quant: str | None+) -> None:+ with pytest.raises(ValueError):+ hf.pull_name(user, repo, quant)+++# ── search ───────────────────────────────────────────────────────────────+++def test_search_parser_reads_the_gguf_block(search_payload) -> None:+ repos = hf.parse_search_payload(search_payload)+ assert [r["id"] for r in repos] == [+ "unsloth/Qwen3.8-27B-GGUF",+ "bartowski/gemma-4-12b-it-GGUF",+ "someone/mystery-GGUF",+ ]+ qwen = repos[0]+ assert qwen["author"] == "unsloth"+ assert qwen["downloads"] == 184213+ assert qwen["likes"] == 412+ assert qwen["last_modified"].startswith("2026-08-19")+ assert qwen["architecture"] == "qwen3"+ assert qwen["total_params"] == 27_200_000_000+ assert qwen["context_length"] == 262144+++def test_search_parser_keeps_an_entry_without_gguf_metadata(search_payload) -> None:+ """A repo without the expanded block still lists — author falls back to+ the id, the unknown numbers stay ``None`` rather than 0."""+ mystery = hf.parse_search_payload(search_payload)[2]+ assert mystery["author"] == "someone"+ assert mystery["architecture"] == ""+ assert mystery["total_params"] is None+ assert mystery["context_length"] is None+++def test_search_parser_answers_empty_on_garbage() -> None:+ assert hf.parse_search_payload({"error": "nope"}) == []+ assert hf.parse_search_payload("text") == []+++async def test_search_sends_the_documented_query(monkeypatch, search_payload) -> None:+ calls: list[tuple[str, Any]] = []+ monkeypatch.setattr(hf, "_fetch_json", _fake_fetch(search_payload, None, calls))+ result = await hf.search("qwen", sort="lastModified", limit=10)+ assert result["error"] is None+ assert len(result["repos"]) == 3+ path, params = calls[0]+ assert path == "/api/models"+ assert dict(params) == {+ "filter": "gguf",+ "search": "qwen",+ "sort": "lastModified",+ "direction": "-1",+ "limit": "10",+ "expand[]": "gguf",+ }+++async def test_search_falls_back_to_downloads_on_an_unknown_sort(+ monkeypatch, search_payload+) -> None:+ calls: list[tuple[str, Any]] = []+ monkeypatch.setattr(hf, "_fetch_json", _fake_fetch(search_payload, None, calls))+ await hf.search("", sort="evil; drop")+ params = dict(calls[0][1])+ assert params["sort"] == "downloads"+ assert "search" not in params+++async def test_search_caches_per_query_and_sort(monkeypatch, search_payload) -> None:+ calls: list[tuple[str, Any]] = []+ monkeypatch.setattr(hf, "_fetch_json", _fake_fetch(search_payload, None, calls))+ await hf.search("qwen")+ await hf.search("Qwen")+ assert len(calls) == 1+ await hf.search("qwen", sort="trendingScore")+ assert len(calls) == 2+++async def test_search_degrades_honestly_when_offline(monkeypatch) -> None:+ monkeypatch.setattr(hf, "_fetch_json", _fake_fetch(None, hf._OFFLINE_SENTENCE, []))+ result = await hf.search("qwen")+ assert result["repos"] == []+ assert "huggingface.co" in result["error"]+++async def test_search_names_the_rate_limit_window(monkeypatch) -> None:+ monkeypatch.setattr(hf, "_fetch_json", _fake_fetch(None, hf._RATE_LIMIT_SENTENCE, []))+ result = await hf.search("qwen")+ assert result["repos"] == []+ assert "5-minute" in result["error"]+ assert "token" in result["error"]+++async def test_search_reports_an_unreadable_shape(monkeypatch) -> None:+ """A schema change upstream must surface as a sentence, not "no results"."""+ monkeypatch.setattr(hf, "_fetch_json", _fake_fetch([{"weird": 1}], None, []))+ result = await hf.search("qwen")+ assert result["repos"] == []+ assert "cannot read" in result["error"]+++# ── files ────────────────────────────────────────────────────────────────+++def test_tree_parser_keeps_only_gguf_files_with_sizes(tree_payload) -> None:+ files = hf.parse_tree_payload(tree_payload)+ names = [f["filename"] for f in files]+ assert ".gitattributes" not in names+ assert "README.md" not in names+ assert "imatrix" not in names+ # Smallest first, unknown size last.+ assert names == [+ "Qwen3.8-27B-IQ2_XS.gguf",+ "Qwen3.8-27B-Q4_K_M.gguf",+ "Qwen3.8-27B-Q8_0.gguf",+ "Qwen3.8-27B-BF16.gguf",+ "weird-no-size.gguf",+ ]+ q4 = files[1]+ assert q4["quant"] == "Q4_K_M"+ assert q4["size_gb"] == 16.7+ assert files[-1]["size_gb"] is None+++async def test_files_carry_a_fit_verdict_per_quant(monkeypatch, tree_payload, _machine) -> None:+ calls: list[tuple[str, Any]] = []+ monkeypatch.setattr(hf, "_fetch_json", _fake_fetch(tree_payload, None, calls))+ result = await hf.files("unsloth", "Qwen3.8-27B-GGUF")+ assert result["error"] is None+ assert calls[0][0] == "/api/models/unsloth/Qwen3.8-27B-GGUF/tree/main"+ by_quant = {f["quant"]: f for f in result["files"] if f["quant"]}+ assert by_quant["IQ2_XS"]["fit"] == "comfortable"+ assert "graphics memory" in by_quant["IQ2_XS"]["fit_note"]+ assert by_quant["Q4_K_M"]["fit"] == "tight"+ assert by_quant["BF16"]["fit"] == "tight"+ unknown = next(f for f in result["files"] if f["size_gb"] is None)+ assert unknown["fit"] == "unknown"+ assert unknown["fit_note"] == ""+++async def test_files_verdicts_follow_the_machine_not_the_cache(monkeypatch, tree_payload) -> None:+ """The cache holds the CATALOGUE; the verdict is judged fresh each call."""+ calls: list[tuple[str, Any]] = []+ monkeypatch.setattr(hf, "_fetch_json", _fake_fetch(tree_payload, None, calls))+ monkeypatch.setattr(hf, "total_memory_gb", lambda: 32.0)+ monkeypatch.setattr(hf, "accelerator_gb", lambda: (0.0, "none"))+ first = await hf.files("unsloth", "Qwen3.8-27B-GGUF")+ q4_first = next(f for f in first["files"] if f["quant"] == "Q4_K_M")+ assert q4_first["fit"] == "comfortable"+ assert "graphics" not in q4_first["fit_note"]++ monkeypatch.setattr(hf, "accelerator_gb", lambda: (24.0, "cuda"))+ second = await hf.files("unsloth", "Qwen3.8-27B-GGUF")+ q4_second = next(f for f in second["files"] if f["quant"] == "Q4_K_M")+ assert "graphics memory" in q4_second["fit_note"]+ assert len(calls) == 1+++async def test_files_reject_a_path_shaped_repository(_machine) -> None:+ result = await hf.files("unsloth", "../../admin")+ assert result["files"] == []+ assert result["error"] == "Not a valid Hugging Face repository name."+++async def test_files_report_a_repository_without_gguf(monkeypatch, _machine) -> None:+ monkeypatch.setattr(+ hf,+ "_fetch_json",+ _fake_fetch([{"type": "file", "path": "model.safetensors", "size": 5}], None, []),+ )+ result = await hf.files("someone", "safetensors-only")+ assert result["files"] == []+ assert "no GGUF" in result["error"]+++async def test_files_pass_through_a_404(monkeypatch, _machine) -> None:+ monkeypatch.setattr(+ hf, "_fetch_json", _fake_fetch(None, "Hugging Face has no repository with that name.", [])+ )+ result = await hf.files("nobody", "nothing")+ assert result["files"] == []+ assert "no repository" in result["error"]+++# ── the pull's 404 sentence ──────────────────────────────────────────────+++def test_not_found_sentence_names_hugging_face_for_hf_names() -> None:+ plain = pull.not_found_message("no-such-model")+ assert "ollama.com/library" in plain++ repo = pull.not_found_message("hf.co/nobody/nothing-GGUF")+ assert "Hugging Face" in repo+ assert "nobody/nothing-GGUF" in repo+ assert "ollama.com/library" not in repo++ quant = pull.not_found_message("huggingface.co/unsloth/Qwen3.8-27B-GGUF:Q9_Z")+ assert "Q9_Z" in quant+ assert "quantization" in quant