1use 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
69pub 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 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
106fn 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
197pub 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
250pub 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
272pub 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
293pub 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
325pub 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
362pub 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}