use crate::{
admission::AdmissionTransport,
catalog_request::{SelectedGguf, build_entry, get, gguf, today},
};
use rigspark_core::{
catalog::{CatalogModel, EntryProvenance},
catalog_request::Repository,
generation_admission::{HfModel, MAX_METADATA_BYTES, license_from_tags},
};
use serde::{Deserialize, Serialize};
use tokio_util::sync::CancellationToken;
use url::Url;
const SEARCH_LIMIT: &str = "20";
const MAX_SEARCH_BYTES: usize = 2 * 1024 * 1024;
#[derive(Debug, thiserror::Error)]
pub enum HfAddError {
#[error("{0}")]
Reference(&'static str),
#[error("the repository must be public, ungated and pinned to a commit")]
Unpinned,
#[error("the repository is not a text-generation model")]
Pipeline,
#[error("the repository does not declare one recognized open-weight license")]
License,
#[error("the repository has no single-file GGUF RigSpark can run")]
NoGguf,
#[error("{0} is not one of this repository's quantizations")]
UnknownQuant(String),
#[error("the GGUF cannot be added: {0}")]
Metadata(String),
#[error(transparent)]
Io(#[from] std::io::Error),
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct GgufChoice {
pub file: String,
pub quant: String,
pub bytes: u64,
pub sha256: String,
}
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct Inspection {
pub repository: String,
pub revision: String,
pub license: &'static str,
pub choices: Vec<GgufChoice>,
#[serde(skip)]
model: HfModel,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct SearchHit {
pub id: String,
pub downloads: u64,
pub likes: u64,
}
pub fn parse_reference(raw: &str) -> Result<(Repository, Option<String>), HfAddError> {
let raw = raw.trim();
let path = raw
.strip_prefix("https://huggingface.co/")
.or_else(|| raw.strip_prefix("hf.co/"))
.or_else(|| raw.strip_prefix("huggingface.co/"))
.unwrap_or(raw);
let (path, quant) = match path.split_once(':') {
Some((path, quant)) => {
if quant.is_empty()
|| quant.len() > 32
|| !quant
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || byte == b'_')
{
return Err(HfAddError::Reference("invalid quantization name"));
}
(path, Some(quant.to_ascii_uppercase()))
}
None => (path, None),
};
if path
.split('/')
.any(|part| part.is_empty() || part == "." || part == "..")
{
return Err(HfAddError::Reference(
"use owner/repository or a Hugging Face URL",
));
}
let repository = Repository::parse(&format!("https://huggingface.co/{path}"))
.map_err(|_| HfAddError::Reference("use owner/repository or a Hugging Face URL"))?;
Ok((repository, quant))
}
fn quant_of(file: &str) -> Option<String> {
let stem = file
.strip_suffix(".gguf")
.or_else(|| file.strip_suffix(".GGUF"))?;
let upper = stem.to_ascii_uppercase();
upper
.rsplit(['-', '.'])
.map(|token| token.trim_start_matches("UD_"))
.find(|token| {
let known = [
"IQ1_", "IQ2_", "IQ3_", "IQ4_", "Q2_", "Q3_", "Q4_", "Q5_", "Q6_", "Q8_",
]
.iter()
.any(|prefix| token.starts_with(prefix))
|| ["F16", "BF16", "F32", "MXFP4"].contains(token);
known
&& token.len() <= 16
&& token
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || byte == b'_')
})
.map(str::to_owned)
}
pub async fn inspect(
repository: &Repository,
transport: &dyn AdmissionTransport,
cancel: &CancellationToken,
) -> Result<Inspection, HfAddError> {
let url = format!(
"https://huggingface.co/api/models/{}?blobs=true",
repository.as_str()
);
let bytes = get(transport, cancel, &url, None, MAX_METADATA_BYTES).await?;
let model = HfModel::parse(
std::str::from_utf8(&bytes)
.map_err(|_| HfAddError::Metadata("metadata is not UTF-8".into()))?,
)
.map_err(|error| HfAddError::Metadata(error.0))?;
if !model.id.eq_ignore_ascii_case(repository.as_str()) || !model.pinned() {
return Err(HfAddError::Unpinned);
}
if model
.pipeline_tag
.as_deref()
.is_some_and(|tag| tag != "text-generation")
{
return Err(HfAddError::Pipeline);
}
let license = license_from_tags(&model.tags).ok_or(HfAddError::License)?;
let mut choices: Vec<GgufChoice> = model
.siblings
.iter()
.filter(|sibling| {
let lower = sibling.rfilename.to_ascii_lowercase();
!lower.contains("mmproj") && !lower.contains("-of-") && !sibling.rfilename.contains('/')
})
.filter_map(|sibling| {
let artifact = sibling.lfs.as_ref()?;
let quant = quant_of(&sibling.rfilename)?;
(artifact.size > 0
&& artifact.size <= 9_007_199_254_740_991
&& artifact.sha256.len() == 64
&& artifact.sha256.bytes().all(|byte| byte.is_ascii_hexdigit()))
.then(|| GgufChoice {
file: sibling.rfilename.clone(),
quant,
bytes: artifact.size,
sha256: artifact.sha256.to_ascii_lowercase(),
})
})
.collect();
choices.sort_by(|left, right| {
left.bytes
.cmp(&right.bytes)
.then(left.file.cmp(&right.file))
});
choices.dedup_by(|later, earlier| later.quant == earlier.quant);
if choices.is_empty() {
return Err(HfAddError::NoGguf);
}
Ok(Inspection {
repository: repository.as_str().into(),
revision: model.sha.clone(),
license,
choices,
model,
})
}
pub async fn entries(
inspection: &Inspection,
transport: &dyn AdmissionTransport,
now: &str,
cancel: &CancellationToken,
) -> Result<Vec<CatalogModel>, HfAddError> {
let smallest = inspection.choices.first().ok_or(HfAddError::NoGguf)?;
let repository =
Repository::parse(&format!("https://huggingface.co/{}", inspection.repository))
.map_err(|_| HfAddError::Reference("invalid repository"))?;
let url = format!(
"https://huggingface.co/{}/resolve/{}/{}",
inspection.repository, inspection.revision, smallest.file
);
let parsed = gguf(transport, cancel, &url)
.await?
.map_err(|reason| HfAddError::Metadata(reason.into()))?;
let today = today(now)?;
inspection
.choices
.iter()
.map(|choice| {
let selected = SelectedGguf {
file: &choice.file,
sha256: &choice.sha256,
bytes: choice.bytes,
quant: &choice.quant,
};
let mut model = build_entry(
&repository,
&inspection.model,
&parsed,
&selected,
inspection.license,
&today,
)
.map_err(HfAddError::Metadata)?;
let id = format!(
"hf.co/{}:{}",
inspection.repository.to_ascii_lowercase(),
choice.quant.to_ascii_lowercase()
);
model.id = id.clone();
model.provenance = EntryProvenance::Local;
model.source.ollama = Some(id);
Ok(model)
})
.collect()
}
pub async fn entry(
inspection: &Inspection,
quant: &str,
transport: &dyn AdmissionTransport,
now: &str,
cancel: &CancellationToken,
) -> Result<CatalogModel, HfAddError> {
if !inspection
.choices
.iter()
.any(|choice| choice.quant.eq_ignore_ascii_case(quant))
{
return Err(HfAddError::UnknownQuant(quant.to_ascii_uppercase()));
}
entries(inspection, transport, now, cancel)
.await?
.into_iter()
.find(|model| model.quantizations[0].name.eq_ignore_ascii_case(quant))
.ok_or_else(|| HfAddError::UnknownQuant(quant.to_ascii_uppercase()))
}
pub fn best_fit<'a>(
entries: &'a [CatalogModel],
hardware: &rigspark_core::sizing::Hardware,
) -> Option<&'a CatalogModel> {
let unquantized = |model: &CatalogModel| {
["F16", "BF16", "F32"].contains(&model.quantizations[0].name.as_str())
};
entries
.iter()
.filter(|model| fits(model, hardware))
.max_by(|left, right| {
(!unquantized(left)).cmp(&!unquantized(right)).then(
left.quantizations[0]
.disk_bytes
.total_cmp(&right.quantizations[0].disk_bytes),
)
})
}
pub fn fits(model: &CatalogModel, hardware: &rigspark_core::sizing::Hardware) -> bool {
rigspark_core::sizing::evaluate(&rigspark_core::sizing::SizingRequest {
model: model.sizing(),
hardware: hardware.clone(),
context: None,
})
.is_ok_and(|result| result.fit.fits)
}
pub fn search_url(query: &str) -> Result<Url, HfAddError> {
let query = query.trim();
if query.is_empty()
|| query.len() > 80
|| !query
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || b" ._-/".contains(&byte))
{
return Err(HfAddError::Reference(
"search with letters, numbers, spaces, dots, dashes or slashes",
));
}
let mut url = Url::parse("https://huggingface.co/api/models")
.map_err(|_| HfAddError::Reference("invalid search URL"))?;
url.query_pairs_mut()
.append_pair("search", query)
.append_pair("filter", "gguf")
.append_pair("sort", "downloads")
.append_pair("limit", SEARCH_LIMIT);
Ok(url)
}
pub fn is_search_url(url: &Url) -> bool {
let pairs: Vec<(String, String)> = url.query_pairs().into_owned().collect();
matches!(pairs.as_slice(), [(search, term), (filter, gguf), (sort, downloads), (limit, count)]
if search == "search" && filter == "filter" && gguf == "gguf" && sort == "sort"
&& downloads == "downloads" && limit == "limit" && count == SEARCH_LIMIT
&& search_url(term).is_ok_and(|built| built.query() == url.query()))
}
pub async fn search(
query: &str,
transport: &dyn AdmissionTransport,
cancel: &CancellationToken,
) -> Result<Vec<SearchHit>, HfAddError> {
#[derive(Deserialize)]
struct Hit {
id: String,
#[serde(default)]
downloads: u64,
#[serde(default)]
likes: u64,
}
let url = search_url(query)?;
let bytes = get(transport, cancel, url.as_str(), None, MAX_SEARCH_BYTES).await?;
let hits: Vec<Hit> = serde_json::from_slice(&bytes)
.map_err(|_| HfAddError::Metadata("invalid search response".into()))?;
Ok(hits
.into_iter()
.filter(|hit| parse_reference(&hit.id).is_ok_and(|(_, quant)| quant.is_none()))
.map(|hit| SearchHit {
id: hit.id,
downloads: hit.downloads,
likes: hit.likes,
})
.collect())
}
pub fn now() -> String {
time::OffsetDateTime::now_utc()
.format(&time::format_description::well_known::Rfc3339)
.unwrap_or_else(|_| "1970-01-01T00:00:00Z".into())
}