use serde::{Deserialize, Serialize};
use std::fmt;
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "source", rename_all = "snake_case")]
pub enum Reference {
Ollama {
namespace: String,
name: String,
tag: String,
},
HuggingFace {
owner: String,
repo: String,
revision: String,
quant: Option<String>,
},
Local { path: String },
Url {
url: String,
sha256: Option<String>,
},
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ParseError(pub String);
impl fmt::Display for ParseError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}", self.0)
}
}
impl std::error::Error for ParseError {}
fn bad(msg: impl Into<String>) -> ParseError {
ParseError(msg.into())
}
impl Reference {
pub fn parse(input: &str) -> Result<Reference, ParseError> {
let s = input.trim();
if s.is_empty() {
return Err(bad("empty model reference"));
}
if let Some(rest) = strip_scheme(s, "hf") {
return parse_hf(rest);
}
if let Some(rest) = strip_scheme(s, "huggingface") {
return parse_hf(rest);
}
if let Some(rest) = strip_scheme(s, "ollama") {
return parse_ollama(rest);
}
if let Some(rest) = strip_scheme(s, "file") {
if rest.is_empty() {
return Err(bad("file: needs a path"));
}
return Ok(Reference::Local {
path: rest.to_string(),
});
}
if s.starts_with("http://") || s.starts_with("https://") {
return parse_url(s);
}
if looks_like_path(s) {
return Ok(Reference::Local {
path: s.to_string(),
});
}
parse_ollama(s)
}
pub fn key(&self) -> String {
match self {
Reference::Ollama {
namespace,
name,
tag,
} => {
format!("ollama/{namespace}/{name}:{tag}")
}
Reference::HuggingFace {
owner,
repo,
revision,
quant,
} => {
let q = quant.as_deref().unwrap_or("auto");
format!("hf/{owner}/{repo}@{revision}#{q}")
}
Reference::Local { path } => format!("local/{path}"),
Reference::Url { url, .. } => format!("url/{url}"),
}
}
pub fn display_name(&self) -> String {
match self {
Reference::Ollama {
namespace,
name,
tag,
} if namespace == "library" => {
format!("{name}:{tag}")
}
Reference::Ollama {
namespace,
name,
tag,
} => format!("{namespace}/{name}:{tag}"),
Reference::HuggingFace {
owner, repo, quant, ..
} => match quant {
Some(q) => format!("{owner}/{repo}@{q}"),
None => format!("{owner}/{repo}"),
},
Reference::Local { path } => path
.rsplit('/')
.next()
.unwrap_or(path)
.trim_end_matches(".gguf")
.to_string(),
Reference::Url { url, .. } => {
let without_query = url.split(['?', '#']).next().unwrap_or(url);
without_query
.rsplit('/')
.next()
.filter(|s| !s.is_empty())
.unwrap_or(url)
.trim_end_matches(".gguf")
.to_string()
}
}
}
pub fn needs_download(&self) -> bool {
!matches!(self, Reference::Local { .. })
}
}
fn strip_scheme<'a>(s: &'a str, scheme: &str) -> Option<&'a str> {
let lower = s.to_ascii_lowercase();
let prefix = format!("{scheme}:");
if lower.starts_with(&format!("{prefix}//")) {
Some(&s[prefix.len() + 2..])
} else if lower.starts_with(&prefix) {
Some(&s[prefix.len()..])
} else {
None
}
}
fn looks_like_path(s: &str) -> bool {
s.starts_with('.')
|| s.starts_with('/')
|| s.starts_with('~')
|| s.ends_with(".gguf")
|| (s.len() > 2 && s.as_bytes()[1] == b':' && (s.contains('\\') || s.contains('/')))
}
fn parse_hf(rest: &str) -> Result<Reference, ParseError> {
if rest.is_empty() {
return Err(bad("hf: needs an owner/repo"));
}
let (head, revision) = match rest.split_once('#') {
Some((h, r)) if !r.is_empty() => (h, r.to_string()),
Some(_) => return Err(bad("empty revision after '#'")),
None => (rest, "main".to_string()),
};
let (path, quant) = match head.split_once('@') {
Some((p, q)) if !q.is_empty() => (p, Some(q.to_string())),
Some(_) => return Err(bad("empty quantization after '@'")),
None => (head, None),
};
let mut parts = path.split('/');
let owner = parts.next().unwrap_or("");
let repo = parts.next().unwrap_or("");
if owner.is_empty() || repo.is_empty() || parts.next().is_some() {
return Err(bad(format!(
"expected owner/repo, got \"{path}\" — a HuggingFace reference has exactly two parts"
)));
}
Ok(Reference::HuggingFace {
owner: owner.to_string(),
repo: repo.to_string(),
revision,
quant,
})
}
fn parse_url(s: &str) -> Result<Reference, ParseError> {
match s.split_once('#') {
None => Ok(Reference::Url {
url: s.to_string(),
sha256: None,
}),
Some((url, frag)) => {
let hex = frag.strip_prefix("sha256:").ok_or_else(|| {
bad(format!(
"unrecognised fragment \"#{frag}\" on a URL reference — \
the only one hearth understands is #sha256:HEX"
))
})?;
if hex.is_empty() || !hex.chars().all(|c| c.is_ascii_hexdigit()) {
return Err(bad(format!("\"{hex}\" after #sha256: is not a hex digest")));
}
Ok(Reference::Url {
url: url.to_string(),
sha256: Some(hex.to_ascii_lowercase()),
})
}
}
}
fn parse_ollama(rest: &str) -> Result<Reference, ParseError> {
if rest.is_empty() {
return Err(bad("ollama: needs a model name"));
}
let (path, tag) = match rest.rsplit_once(':') {
Some((p, t)) if !t.is_empty() && !t.contains('/') => (p, t.to_string()),
Some((_, "")) => return Err(bad("empty tag after ':'")),
_ => (rest, "latest".to_string()),
};
let mut parts = path.split('/');
let first = parts.next().unwrap_or("");
let second = parts.next();
if parts.next().is_some() {
return Err(bad(format!(
"expected name or namespace/name, got \"{path}\""
)));
}
let (namespace, name) = match second {
None => ("library".to_string(), first.to_string()),
Some(n) => (first.to_string(), n.to_string()),
};
if name.is_empty() || namespace.is_empty() {
return Err(bad(format!("incomplete model name: \"{rest}\"")));
}
Ok(Reference::Ollama {
namespace,
name,
tag,
})
}
#[cfg(test)]
mod file_scheme_tests {
use super::*;
#[test]
fn a_file_url_yields_a_path_you_can_actually_open() {
for (input, want) in [
("file:/models/muse.gguf", "/models/muse.gguf"),
("file:./muse.gguf", "./muse.gguf"),
("file:muse.gguf", "muse.gguf"),
("file:/models/model.bin", "/models/model.bin"),
] {
match Reference::parse(input).expect(input) {
Reference::Local { path } => assert_eq!(path, want, "for {input}"),
other => panic!("{input} should be Local, got {other:?}"),
}
}
}
#[test]
fn a_bare_path_still_works_without_a_scheme() {
for input in ["/models/muse.gguf", "./muse.gguf", "~/models/muse.gguf"] {
match Reference::parse(input).expect(input) {
Reference::Local { path } => assert_eq!(path, input),
other => panic!("{input} should be Local, got {other:?}"),
}
}
}
#[test]
fn a_windows_path_is_not_mistaken_for_a_scheme() {
for input in [r"C:\models\muse.gguf", "C:/models/muse.gguf"] {
match Reference::parse(input).expect(input) {
Reference::Local { path } => assert_eq!(path, input),
other => panic!("{input} should be Local, got {other:?}"),
}
}
}
#[test]
fn the_other_schemes_still_win_over_the_path_heuristic() {
assert!(matches!(
Reference::parse("hf:TheBloke/X-GGUF").unwrap(),
Reference::HuggingFace { .. }
));
assert!(matches!(
Reference::parse("ollama:library/llama3:latest").unwrap(),
Reference::Ollama { .. }
));
}
#[test]
fn an_empty_file_scheme_is_an_error_not_an_empty_path() {
assert!(Reference::parse("file:").is_err());
}
#[test]
fn display_name_is_the_model_name_now_that_the_scheme_is_gone() {
let r = Reference::parse("file:/models/muse.gguf").unwrap();
assert_eq!(r.display_name(), "muse");
assert_eq!(r.key(), "local//models/muse.gguf");
}
}
#[cfg(test)]
mod url_scheme_tests {
use super::*;
#[test]
fn a_gguf_url_is_not_mistaken_for_a_local_path() {
for scheme in ["http", "https"] {
let input = format!("{scheme}://example.com/models/model.gguf");
match Reference::parse(&input).expect(&input) {
Reference::Url { url, sha256 } => {
assert_eq!(url, input);
assert_eq!(sha256, None);
}
other => panic!("{input} should be Url, got {other:?}"),
}
}
}
#[test]
fn a_pinned_sha256_fragment_is_read_and_lowercased() {
let r = Reference::parse(
"https://example.com/m.gguf#sha256:DEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEF",
)
.unwrap();
match r {
Reference::Url { sha256, .. } => assert_eq!(
sha256.as_deref(),
Some("deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef")
),
other => panic!("expected Url, got {other:?}"),
}
}
#[test]
fn a_fragment_that_is_not_sha256_is_a_named_error() {
let err = Reference::parse("https://example.com/m.gguf#refs/pr/3").unwrap_err();
assert!(err.0.contains("sha256:"), "{}", err.0);
}
#[test]
fn a_non_hex_digest_is_refused_rather_than_stored_wrong() {
let err = Reference::parse("https://example.com/m.gguf#sha256:not-hex").unwrap_err();
assert!(err.0.contains("not a hex digest"), "{}", err.0);
}
#[test]
fn an_empty_digest_fragment_is_refused() {
assert!(Reference::parse("https://example.com/m.gguf#sha256:").is_err());
}
#[test]
fn display_name_is_the_filename_with_the_query_string_dropped() {
let r = Reference::parse("https://cdn.example.com/models/muse.gguf?token=abc123").unwrap();
assert_eq!(
r.display_name(),
"muse",
"a query-string token must never end up in a model name"
);
}
#[test]
fn display_name_falls_back_to_the_whole_url_when_the_path_is_empty() {
let r = Reference::parse("https://example.com/").unwrap();
assert_eq!(r.display_name(), "https://example.com/");
}
#[test]
fn key_is_stable_across_calls_for_the_same_url() {
let r = Reference::parse("https://example.com/m.gguf").unwrap();
assert_eq!(
r.key(),
Reference::parse("https://example.com/m.gguf")
.unwrap()
.key()
);
assert_eq!(r.key(), "url/https://example.com/m.gguf");
}
#[test]
fn a_url_needs_a_download_like_every_non_local_reference() {
let r = Reference::parse("https://example.com/m.gguf").unwrap();
assert!(r.needs_download());
}
}