Skip to main content

rigspark_runtime/
hf_add.rs

1//! Add a GGUF model from Hugging Face to the user's local catalog: search, inspect a
2//! repository's single-file quantizations, and build a pinned entry. Network use is
3//! explicit and limited to allow-listed Hugging Face URLs; advice stays offline.
4
5use crate::{
6    admission::AdmissionTransport,
7    catalog_request::{SelectedGguf, build_entry, get, gguf, today},
8};
9use rigspark_core::{
10    catalog::{CatalogModel, EntryProvenance},
11    catalog_request::Repository,
12    generation_admission::{HfModel, MAX_METADATA_BYTES, license_from_tags},
13};
14use serde::{Deserialize, Serialize};
15use tokio_util::sync::CancellationToken;
16use url::Url;
17
18const SEARCH_LIMIT: &str = "20";
19const MAX_SEARCH_BYTES: usize = 2 * 1024 * 1024;
20
21#[derive(Debug, thiserror::Error)]
22pub enum HfAddError {
23    #[error("{0}")]
24    Reference(&'static str),
25    #[error("the repository must be public, ungated and pinned to a commit")]
26    Unpinned,
27    #[error("the repository is not a text-generation model")]
28    Pipeline,
29    #[error("the repository does not declare one recognized open-weight license")]
30    License,
31    #[error("the repository has no single-file GGUF RigSpark can run")]
32    NoGguf,
33    #[error("{0} is not one of this repository's quantizations")]
34    UnknownQuant(String),
35    #[error("the GGUF cannot be added: {0}")]
36    Metadata(String),
37    #[error(transparent)]
38    Io(#[from] std::io::Error),
39}
40
41#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
42#[serde(rename_all = "camelCase")]
43pub struct GgufChoice {
44    pub file: String,
45    pub quant: String,
46    pub bytes: u64,
47    pub sha256: String,
48}
49
50#[derive(Debug, Clone, Serialize)]
51#[serde(rename_all = "camelCase")]
52pub struct Inspection {
53    pub repository: String,
54    pub revision: String,
55    pub license: &'static str,
56    pub choices: Vec<GgufChoice>,
57    #[serde(skip)]
58    model: HfModel,
59}
60
61#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
62#[serde(rename_all = "camelCase")]
63pub struct SearchHit {
64    pub id: String,
65    pub downloads: u64,
66    pub likes: u64,
67}
68
69/// `owner/repo`, `https://huggingface.co/owner/repo` or `hf.co/owner/repo`, each with an
70/// optional `:QUANT` suffix (returned upper-cased).
71pub fn parse_reference(raw: &str) -> Result<(Repository, Option<String>), HfAddError> {
72    let raw = raw.trim();
73    let path = raw
74        .strip_prefix("https://huggingface.co/")
75        .or_else(|| raw.strip_prefix("hf.co/"))
76        .or_else(|| raw.strip_prefix("huggingface.co/"))
77        .unwrap_or(raw);
78    let (path, quant) = match path.split_once(':') {
79        Some((path, quant)) => {
80            if quant.is_empty()
81                || quant.len() > 32
82                || !quant
83                    .bytes()
84                    .all(|byte| byte.is_ascii_alphanumeric() || byte == b'_')
85            {
86                return Err(HfAddError::Reference("invalid quantization name"));
87            }
88            (path, Some(quant.to_ascii_uppercase()))
89        }
90        None => (path, None),
91    };
92    // URL parsing would normalize dot segments away, so refuse them first.
93    if path
94        .split('/')
95        .any(|part| part.is_empty() || part == "." || part == "..")
96    {
97        return Err(HfAddError::Reference(
98            "use owner/repository or a Hugging Face URL",
99        ));
100    }
101    let repository = Repository::parse(&format!("https://huggingface.co/{path}"))
102        .map_err(|_| HfAddError::Reference("use owner/repository or a Hugging Face URL"))?;
103    Ok((repository, quant))
104}
105
106/// The quantization named in a GGUF file name, if RigSpark can size it.
107fn quant_of(file: &str) -> Option<String> {
108    let stem = file
109        .strip_suffix(".gguf")
110        .or_else(|| file.strip_suffix(".GGUF"))?;
111    let upper = stem.to_ascii_uppercase();
112    upper
113        .rsplit(['-', '.'])
114        .map(|token| token.trim_start_matches("UD_"))
115        .find(|token| {
116            let known = [
117                "IQ1_", "IQ2_", "IQ3_", "IQ4_", "Q2_", "Q3_", "Q4_", "Q5_", "Q6_", "Q8_",
118            ]
119            .iter()
120            .any(|prefix| token.starts_with(prefix))
121                || ["F16", "BF16", "F32", "MXFP4"].contains(token);
122            known
123                && token.len() <= 16
124                && token
125                    .bytes()
126                    .all(|byte| byte.is_ascii_alphanumeric() || byte == b'_')
127        })
128        .map(str::to_owned)
129}
130
131pub async fn inspect(
132    repository: &Repository,
133    transport: &dyn AdmissionTransport,
134    cancel: &CancellationToken,
135) -> Result<Inspection, HfAddError> {
136    let url = format!(
137        "https://huggingface.co/api/models/{}?blobs=true",
138        repository.as_str()
139    );
140    let bytes = get(transport, cancel, &url, None, MAX_METADATA_BYTES).await?;
141    let model = HfModel::parse(
142        std::str::from_utf8(&bytes)
143            .map_err(|_| HfAddError::Metadata("metadata is not UTF-8".into()))?,
144    )
145    .map_err(|error| HfAddError::Metadata(error.0))?;
146    if !model.id.eq_ignore_ascii_case(repository.as_str()) || !model.pinned() {
147        return Err(HfAddError::Unpinned);
148    }
149    if model
150        .pipeline_tag
151        .as_deref()
152        .is_some_and(|tag| tag != "text-generation")
153    {
154        return Err(HfAddError::Pipeline);
155    }
156    let license = license_from_tags(&model.tags).ok_or(HfAddError::License)?;
157    let mut choices: Vec<GgufChoice> = model
158        .siblings
159        .iter()
160        .filter(|sibling| {
161            let lower = sibling.rfilename.to_ascii_lowercase();
162            !lower.contains("mmproj") && !lower.contains("-of-") && !sibling.rfilename.contains('/')
163        })
164        .filter_map(|sibling| {
165            let artifact = sibling.lfs.as_ref()?;
166            let quant = quant_of(&sibling.rfilename)?;
167            (artifact.size > 0
168                && artifact.size <= 9_007_199_254_740_991
169                && artifact.sha256.len() == 64
170                && artifact.sha256.bytes().all(|byte| byte.is_ascii_hexdigit()))
171            .then(|| GgufChoice {
172                file: sibling.rfilename.clone(),
173                quant,
174                bytes: artifact.size,
175                sha256: artifact.sha256.to_ascii_lowercase(),
176            })
177        })
178        .collect();
179    choices.sort_by(|left, right| {
180        left.bytes
181            .cmp(&right.bytes)
182            .then(left.file.cmp(&right.file))
183    });
184    choices.dedup_by(|later, earlier| later.quant == earlier.quant);
185    if choices.is_empty() {
186        return Err(HfAddError::NoGguf);
187    }
188    Ok(Inspection {
189        repository: repository.as_str().into(),
190        revision: model.sha.clone(),
191        license,
192        choices,
193        model,
194    })
195}
196
197/// Pinned `local` catalog entries for every inspected quantization. One GGUF header
198/// (from the smallest file) supplies the shared model facts; each entry keeps its own
199/// file, size and SHA-256, which `up` verifies before serving.
200pub async fn entries(
201    inspection: &Inspection,
202    transport: &dyn AdmissionTransport,
203    now: &str,
204    cancel: &CancellationToken,
205) -> Result<Vec<CatalogModel>, HfAddError> {
206    let smallest = inspection.choices.first().ok_or(HfAddError::NoGguf)?;
207    let repository =
208        Repository::parse(&format!("https://huggingface.co/{}", inspection.repository))
209            .map_err(|_| HfAddError::Reference("invalid repository"))?;
210    let url = format!(
211        "https://huggingface.co/{}/resolve/{}/{}",
212        inspection.repository, inspection.revision, smallest.file
213    );
214    let parsed = gguf(transport, cancel, &url)
215        .await?
216        .map_err(|reason| HfAddError::Metadata(reason.into()))?;
217    let today = today(now)?;
218    inspection
219        .choices
220        .iter()
221        .map(|choice| {
222            let selected = SelectedGguf {
223                file: &choice.file,
224                sha256: &choice.sha256,
225                bytes: choice.bytes,
226                quant: &choice.quant,
227            };
228            let mut model = build_entry(
229                &repository,
230                &inspection.model,
231                &parsed,
232                &selected,
233                inspection.license,
234                &today,
235            )
236            .map_err(HfAddError::Metadata)?;
237            let id = format!(
238                "hf.co/{}:{}",
239                inspection.repository.to_ascii_lowercase(),
240                choice.quant.to_ascii_lowercase()
241            );
242            model.id = id.clone();
243            model.provenance = EntryProvenance::Local;
244            model.source.ollama = Some(id);
245            Ok(model)
246        })
247        .collect()
248}
249
250/// The entry for one quantization of an inspected repository.
251pub async fn entry(
252    inspection: &Inspection,
253    quant: &str,
254    transport: &dyn AdmissionTransport,
255    now: &str,
256    cancel: &CancellationToken,
257) -> Result<CatalogModel, HfAddError> {
258    if !inspection
259        .choices
260        .iter()
261        .any(|choice| choice.quant.eq_ignore_ascii_case(quant))
262    {
263        return Err(HfAddError::UnknownQuant(quant.to_ascii_uppercase()));
264    }
265    entries(inspection, transport, now, cancel)
266        .await?
267        .into_iter()
268        .find(|model| model.quantizations[0].name.eq_ignore_ascii_case(quant))
269        .ok_or_else(|| HfAddError::UnknownQuant(quant.to_ascii_uppercase()))
270}
271
272/// The largest quantized file that fits this machine; unquantized F16/BF16/F32 files only
273/// when nothing smaller fits. `None` when nothing fits.
274pub fn best_fit<'a>(
275    entries: &'a [CatalogModel],
276    hardware: &rigspark_core::sizing::Hardware,
277) -> Option<&'a CatalogModel> {
278    let unquantized = |model: &CatalogModel| {
279        ["F16", "BF16", "F32"].contains(&model.quantizations[0].name.as_str())
280    };
281    entries
282        .iter()
283        .filter(|model| fits(model, hardware))
284        .max_by(|left, right| {
285            (!unquantized(left)).cmp(&!unquantized(right)).then(
286                left.quantizations[0]
287                    .disk_bytes
288                    .total_cmp(&right.quantizations[0].disk_bytes),
289            )
290        })
291}
292
293/// Whether an entry's weights fit this machine at its default context.
294pub fn fits(model: &CatalogModel, hardware: &rigspark_core::sizing::Hardware) -> bool {
295    rigspark_core::sizing::evaluate(&rigspark_core::sizing::SizingRequest {
296        model: model.sizing(),
297        hardware: hardware.clone(),
298        context: None,
299    })
300    .is_ok_and(|result| result.fit.fits)
301}
302
303pub fn search_url(query: &str) -> Result<Url, HfAddError> {
304    let query = query.trim();
305    if query.is_empty()
306        || query.len() > 80
307        || !query
308            .bytes()
309            .all(|byte| byte.is_ascii_alphanumeric() || b" ._-/".contains(&byte))
310    {
311        return Err(HfAddError::Reference(
312            "search with letters, numbers, spaces, dots, dashes or slashes",
313        ));
314    }
315    let mut url = Url::parse("https://huggingface.co/api/models")
316        .map_err(|_| HfAddError::Reference("invalid search URL"))?;
317    url.query_pairs_mut()
318        .append_pair("search", query)
319        .append_pair("filter", "gguf")
320        .append_pair("sort", "downloads")
321        .append_pair("limit", SEARCH_LIMIT);
322    Ok(url)
323}
324
325/// Whether `url` is exactly a search this module builds.
326pub fn is_search_url(url: &Url) -> bool {
327    let pairs: Vec<(String, String)> = url.query_pairs().into_owned().collect();
328    matches!(pairs.as_slice(), [(search, term), (filter, gguf), (sort, downloads), (limit, count)]
329        if search == "search" && filter == "filter" && gguf == "gguf" && sort == "sort"
330            && downloads == "downloads" && limit == "limit" && count == SEARCH_LIMIT
331            && search_url(term).is_ok_and(|built| built.query() == url.query()))
332}
333
334pub async fn search(
335    query: &str,
336    transport: &dyn AdmissionTransport,
337    cancel: &CancellationToken,
338) -> Result<Vec<SearchHit>, HfAddError> {
339    #[derive(Deserialize)]
340    struct Hit {
341        id: String,
342        #[serde(default)]
343        downloads: u64,
344        #[serde(default)]
345        likes: u64,
346    }
347    let url = search_url(query)?;
348    let bytes = get(transport, cancel, url.as_str(), None, MAX_SEARCH_BYTES).await?;
349    let hits: Vec<Hit> = serde_json::from_slice(&bytes)
350        .map_err(|_| HfAddError::Metadata("invalid search response".into()))?;
351    Ok(hits
352        .into_iter()
353        .filter(|hit| parse_reference(&hit.id).is_ok_and(|(_, quant)| quant.is_none()))
354        .map(|hit| SearchHit {
355            id: hit.id,
356            downloads: hit.downloads,
357            likes: hit.likes,
358        })
359        .collect())
360}
361
362/// The current time in the RFC 3339 form `entries` expects.
363pub fn now() -> String {
364    time::OffsetDateTime::now_utc()
365        .format(&time::format_description::well_known::Rfc3339)
366        .unwrap_or_else(|_| "1970-01-01T00:00:00Z".into())
367}