hf_browse.py 5.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135
  1. """Browse Hugging Face for GGUF models the user can run.
  2. The curated catalog is the front page; this module is the firehose behind it — day-0 models not yet
  3. in the catalog, community quants, anything. Acquisition only: nothing here serves a model. A browsed
  4. download lands in the machine-scoped models dir and from that moment the normal machinery owns it —
  5. staleness bounce, preset generation from the real GGUF header, fit policy, placement pills.
  6. """
  7. from __future__ import annotations
  8. import json
  9. import logging
  10. import re
  11. import time
  12. import urllib.parse
  13. import urllib.request
  14. from dataclasses import dataclass, replace
  15. logger = logging.getLogger(__name__)
  16. _HF = "https://huggingface.co"
  17. _TIMEOUT_S = 15
  18. # Rough-fit fill-in for pre-download pricing: a mid-size model's 64K-floor KV plus runtime
  19. # overhead. Deliberately round — the verdict bands are coarse, not window grants.
  20. _ROUGH_KV_AND_OVERHEAD = 4 << 30
  21. # Tiny TTL cache: the pane fires a search per keystroke pause and re-opens repos the user flips
  22. # between. Process-local, size-capped; upstream truth changes slowly at this granularity.
  23. _CACHE: dict[str, tuple[float, object]] = {}
  24. _CACHE_TTL_S = 300
  25. _CACHE_MAX = 128
  26. def _get_json(url: str) -> object:
  27. now = time.monotonic()
  28. hit = _CACHE.get(url)
  29. if hit and now - hit[0] < _CACHE_TTL_S:
  30. return hit[1]
  31. req = urllib.request.Request(url, headers={"User-Agent": "hermes-local-models"})
  32. with urllib.request.urlopen(req, timeout=_TIMEOUT_S) as r:
  33. data = json.load(r)
  34. if len(_CACHE) >= _CACHE_MAX:
  35. _CACHE.pop(min(_CACHE, key=lambda k: _CACHE[k][0]))
  36. _CACHE[url] = (now, data)
  37. return data
  38. @dataclass(frozen=True)
  39. class HFModelHit:
  40. repo: str # e.g. "unsloth/Qwen3.8-27B-GGUF"
  41. downloads: int
  42. likes: int
  43. updated: str # ISO date from HF
  44. gated: bool
  45. @dataclass(frozen=True)
  46. class HFFileGroup:
  47. """One downloadable quant: a single GGUF or all parts of a split one."""
  48. label: str # e.g. "Q4_K_M" or the file stem
  49. paths: tuple[str, ...] # repo-relative, split parts in order
  50. total_bytes: int
  51. fit: str = "unknown" # fits-gpu | needs-ram | too-big | unknown
  52. _QUANT_RE = re.compile(r"(?:IQ|Q)\d[_A-Z0-9]*|F16|BF16|F32", re.IGNORECASE)
  53. _SPLIT_RE = re.compile(r"-(\d{5})-of-(\d{5})\.gguf$", re.IGNORECASE)
  54. def search_models(query: str, limit: int = 20) -> list[HFModelHit]:
  55. """Full-text search over HF models that ship GGUF files, most downloaded first (the closest
  56. public signal to 'trending')."""
  57. q = urllib.parse.quote(query.strip())
  58. url = (f"{_HF}/api/models?search={q}&filter=gguf&sort=downloads"
  59. f"&direction=-1&limit={max(1, min(int(limit), 50))}")
  60. return [HFModelHit(repo=str(m.get("id", "")),
  61. downloads=int(m.get("downloads") or 0),
  62. likes=int(m.get("likes") or 0),
  63. updated=str(m.get("lastModified") or ""),
  64. gated=bool(m.get("gated")))
  65. for m in _get_json(url)]
  66. def _quant_label(filename: str) -> str:
  67. m = _QUANT_RE.search(filename)
  68. return m.group(0).upper() if m else filename
  69. def repo_files(repo: str) -> list[HFFileGroup]:
  70. """The servable GGUFs in a repo, grouped: split parts collapse into one entry (first part is
  71. what llama.cpp loads); mmproj/draft/MTP-head companions are excluded. Largest quant first."""
  72. url = f"{_HF}/api/models/{urllib.parse.quote(repo)}/tree/main?recursive=true"
  73. files = _get_json(url)
  74. singles: list[tuple[str, int]] = []
  75. splits: dict[str, list[tuple[int, str, int]]] = {}
  76. for f in files:
  77. path = str(f.get("path", ""))
  78. if not path.lower().endswith(".gguf"):
  79. continue
  80. name = path.rsplit("/", 1)[-1].lower()
  81. # An MTP head (unsloth's mtp-<model>-<quant>.gguf) drafts for its model; it cannot serve.
  82. if name.startswith(("mmproj", "dspark", "mtp-")) or "draft" in name:
  83. continue
  84. size = int(f.get("size") or 0)
  85. m = _SPLIT_RE.search(path)
  86. if m:
  87. splits.setdefault(path[: m.start()], []).append((int(m.group(1)), path, size))
  88. else:
  89. singles.append((path, size))
  90. groups = [HFFileGroup(label=_quant_label(path), paths=(path,), total_bytes=size)
  91. for path, size in singles]
  92. for stem, parts in splits.items():
  93. parts.sort()
  94. groups.append(HFFileGroup(label=_quant_label(stem), paths=tuple(p for _, p, _ in parts),
  95. total_bytes=sum(s for _, _, s in parts)))
  96. groups.sort(key=lambda g: g.total_bytes, reverse=True)
  97. return groups
  98. def rough_fit(total_bytes: int, budget) -> str:
  99. """Coarse pre-download verdict from file size alone (GGUF file size ≈ in-memory weights);
  100. the GGUF header refines this after download. Bands match the catalog pills' language."""
  101. need = total_bytes + _ROUGH_KV_AND_OVERHEAD
  102. if need <= budget.usable_vram_bytes:
  103. return "fits-gpu"
  104. if need <= budget.usable_vram_bytes + budget.ram_available_bytes:
  105. return "needs-ram"
  106. return "too-big"
  107. def priced_repo_files(repo: str, budget) -> list[HFFileGroup]:
  108. return [replace(g, fit=rough_fit(g.total_bytes, budget)) for g in repo_files(repo)]