Skip to content

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.

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.py
new file mode 100644
index 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.py
index 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)
return
resp.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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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