Coverage for src / lilbee / catalog / refs.py: 100%

1"""HuggingFace ref helpers: parse and format ``<org>/<repo>/<file>.gguf`` strings.""" 

2 

3from __future__ import annotations 

4 

5GGUF_GLOB = "*.gguf" 

6 

7_QUANT_PREFERENCE = ("Q4_K_M", "Q4_K_S", "Q5_K_M", "Q5_K_S", "Q8_0", "Q6_K", "Q3_K_M") 

8 

9 

10def pick_best_gguf(filenames: list[str]) -> str: 

11 """Pick the best GGUF file by quantization preference.""" 

12 for quant in _QUANT_PREFERENCE: 

13 for f in filenames: 

14 if quant in f: 

15 return f 

16 return filenames[0] 

17 

18 

19def is_bare_hf_repo(ref: str) -> bool: 

20 """True if *ref* has the bare ``<org>/<repo>`` shape (no filename segment).""" 

21 return ref.count("/") == 1 and not ref.endswith(".gguf") 

22 

23 

24def hf_repo_from_ref(ref: str) -> str: 

25 """Return the ``<org>/<repo>`` portion of a native GGUF ref. 

26 

27 Native GGUF refs have the form ``<org>/<repo>/<filename>.gguf``; the 

28 repo is the prefix before the final slash. Provider-prefixed refs 

29 (``openai/gpt-4``, ``ollama/llama3:8b``) and bare repos lack the 

30 ``.gguf`` suffix and are returned unchanged. 

31 """ 

32 if ref.endswith(".gguf") and "/" in ref: 

33 return ref.rsplit("/", 1)[0] 

34 return ref 

35 

36 

37def format_native_gguf_ref(hf_repo: str, gguf_filename: str) -> str: 

38 """Render the canonical ``<hf_repo>/<gguf_filename>`` native GGUF ref.""" 

39 return f"{hf_repo}/{gguf_filename}"