Skip to main content

hearth_resolve/
reference.rs

1//! What model did the user mean?
2//!
3//! hearth aggregates two catalogs that do not agree on anything. Ollama has a
4//! curated few hundred models under short names people already have in muscle
5//! memory (`llama3`, `qwen3:14b`). HuggingFace has hundreds of thousands of
6//! GGUFs under `owner/repo`, several quantizations to a repo, and no opinion
7//! about which one you want.
8//!
9//! The bet is that both should work in the same command, because the catalogs
10//! are theirs and the serving is ours. So:
11//!
12//! ```text
13//! llama3                             ollama library/llama3:latest
14//! qwen3:14b                          ollama library/qwen3:14b
15//! ollama:someone/model:tag           ollama someone/model:tag
16//! hf:TheBloke/Llama-2-7B-GGUF        huggingface, quant chosen for you
17//! hf:TheBloke/Llama-2-7B-GGUF@Q5_K_M huggingface, quant pinned
18//! hf:owner/repo@Q4_K_M#refs/pr/3     ...at a specific revision
19//! https://example.com/model.gguf     a direct download, self-verified
20//! https://example.com/m.gguf#sha256:ab12…   ...with a digest pinned
21//! ./models/muse.gguf                 a file you already have
22//! ```
23//!
24//! A bare name means Ollama on purpose. It is what people already type, and a
25//! tool that punishes existing muscle memory to make a point about neutrality
26//! is a tool nobody switches to.
27//!
28//! A bare URL is the odd one out: neither registry publishes a digest for it,
29//! so there is nothing to verify against ahead of the download. hearth still
30//! refuses to trust it blindly — see [`hearth_pull`]'s self-computed digest —
31//! but `hearth why` on a URL pull says exactly that distinction, because
32//! "verified against what the registry published" and "internally consistent
33//! with itself" are different claims and only one of them is what "verified"
34//! usually means.
35
36use serde::{Deserialize, Serialize};
37use std::fmt;
38
39/// Where a model comes from, once we have understood the reference.
40#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
41#[serde(tag = "source", rename_all = "snake_case")]
42pub enum Reference {
43    Ollama {
44        /// `library` for the curated catalog, a username otherwise.
45        namespace: String,
46        name: String,
47        tag: String,
48    },
49    HuggingFace {
50        owner: String,
51        repo: String,
52        /// Git revision. `main` unless asked otherwise.
53        revision: String,
54        /// Which quantization, if the caller pinned one. When absent we choose,
55        /// and say which one we chose.
56        quant: Option<String>,
57    },
58    /// A GGUF already on disk. No catalog, no download, no opinions.
59    Local { path: String },
60    /// A direct download. Neither registry: no manifest, no repo listing, no
61    /// published digest — just a URL that is supposed to be a GGUF.
62    Url {
63        url: String,
64        /// Pinned via a `#sha256:HEX` fragment. `None` means hearth will hash
65        /// the file itself after downloading and trust that — self-consistent,
66        /// not registry-verified, and `hearth why` says which.
67        sha256: Option<String>,
68    },
69}
70
71#[derive(Debug, Clone, PartialEq, Eq)]
72pub struct ParseError(pub String);
73
74impl fmt::Display for ParseError {
75    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
76        write!(f, "{}", self.0)
77    }
78}
79
80impl std::error::Error for ParseError {}
81
82fn bad(msg: impl Into<String>) -> ParseError {
83    ParseError(msg.into())
84}
85
86impl Reference {
87    /// Read a reference the way a person typed it.
88    pub fn parse(input: &str) -> Result<Reference, ParseError> {
89        let s = input.trim();
90        if s.is_empty() {
91            return Err(bad("empty model reference"));
92        }
93
94        // KNOWN schemes first. An explicit scheme is a statement of intent and
95        // cannot be ambiguous; the path heuristic below is a guess for input
96        // that made no statement.
97        //
98        // This used to be the other way round, to keep a Windows path like
99        // `C:\models\x.gguf` from being read as a scheme. That concern is real
100        // but it is already handled by only ever stripping the four schemes we
101        // know — `c` is not one of them. Checking the heuristic first had a
102        // worse consequence: `looks_like_path` matches anything ending in
103        // `.gguf`, so EVERY `file:` URL pointing at a GGUF matched it and kept
104        // its scheme, producing `Local { path: "file:/m/muse.gguf" }` — a path
105        // that cannot be opened. The `file:` branch below was dead code for
106        // every realistic input, and the heuristic meant to recognise GGUF
107        // files was what broke GGUF file URLs.
108        if let Some(rest) = strip_scheme(s, "hf") {
109            return parse_hf(rest);
110        }
111        if let Some(rest) = strip_scheme(s, "huggingface") {
112            return parse_hf(rest);
113        }
114        if let Some(rest) = strip_scheme(s, "ollama") {
115            return parse_ollama(rest);
116        }
117        if let Some(rest) = strip_scheme(s, "file") {
118            if rest.is_empty() {
119                return Err(bad("file: needs a path"));
120            }
121            return Ok(Reference::Local {
122                path: rest.to_string(),
123            });
124        }
125        // http(s):// BEFORE the path heuristic below. `looks_like_path` matches
126        // anything ending in `.gguf`, and a direct download URL to a GGUF is
127        // exactly that — the same class of bug the `file:` fix above exists
128        // for, on a scheme that has no fallback interpretation at all: a URL
129        // read as a local path just fails to open, with an error that sends
130        // the reader looking at their filesystem instead of their network.
131        if s.starts_with("http://") || s.starts_with("https://") {
132            return parse_url(s);
133        }
134
135        // No scheme. Does it look like a path?
136        if looks_like_path(s) {
137            return Ok(Reference::Local {
138                path: s.to_string(),
139            });
140        }
141
142        // No scheme. Ollama, because that is what the name looks like to
143        // everyone who has ever used one of these tools.
144        parse_ollama(s)
145    }
146
147    /// A stable identity for this model on disk and in the event log.
148    ///
149    /// Two references that mean the same model must produce the same key, or
150    /// the same weights get downloaded twice and the residency history splits
151    /// in half.
152    pub fn key(&self) -> String {
153        match self {
154            Reference::Ollama {
155                namespace,
156                name,
157                tag,
158            } => {
159                format!("ollama/{namespace}/{name}:{tag}")
160            }
161            Reference::HuggingFace {
162                owner,
163                repo,
164                revision,
165                quant,
166            } => {
167                let q = quant.as_deref().unwrap_or("auto");
168                format!("hf/{owner}/{repo}@{revision}#{q}")
169            }
170            Reference::Local { path } => format!("local/{path}"),
171            Reference::Url { url, .. } => format!("url/{url}"),
172        }
173    }
174
175    /// What to call it in a report, a route, or an API response.
176    pub fn display_name(&self) -> String {
177        match self {
178            Reference::Ollama {
179                namespace,
180                name,
181                tag,
182            } if namespace == "library" => {
183                format!("{name}:{tag}")
184            }
185            Reference::Ollama {
186                namespace,
187                name,
188                tag,
189            } => format!("{namespace}/{name}:{tag}"),
190            Reference::HuggingFace {
191                owner, repo, quant, ..
192            } => match quant {
193                Some(q) => format!("{owner}/{repo}@{q}"),
194                None => format!("{owner}/{repo}"),
195            },
196            Reference::Local { path } => path
197                .rsplit('/')
198                .next()
199                .unwrap_or(path)
200                .trim_end_matches(".gguf")
201                .to_string(),
202            Reference::Url { url, .. } => {
203                // The filename off the end of the path, query string dropped
204                // first so `?token=…` does not end up in a model name.
205                let without_query = url.split(['?', '#']).next().unwrap_or(url);
206                without_query
207                    .rsplit('/')
208                    .next()
209                    .filter(|s| !s.is_empty())
210                    .unwrap_or(url)
211                    .trim_end_matches(".gguf")
212                    .to_string()
213            }
214        }
215    }
216
217    pub fn needs_download(&self) -> bool {
218        !matches!(self, Reference::Local { .. })
219    }
220}
221
222fn strip_scheme<'a>(s: &'a str, scheme: &str) -> Option<&'a str> {
223    let lower = s.to_ascii_lowercase();
224    let prefix = format!("{scheme}:");
225    // `hf://owner/repo` and `hf:owner/repo` both mean the same thing; people
226    // type both and neither is wrong.
227    if lower.starts_with(&format!("{prefix}//")) {
228        Some(&s[prefix.len() + 2..])
229    } else if lower.starts_with(&prefix) {
230        Some(&s[prefix.len()..])
231    } else {
232        None
233    }
234}
235
236fn looks_like_path(s: &str) -> bool {
237    s.starts_with('.')
238        || s.starts_with('/')
239        || s.starts_with('~')
240        || s.ends_with(".gguf")
241        // C:\models\x.gguf
242        || (s.len() > 2 && s.as_bytes()[1] == b':' && (s.contains('\\') || s.contains('/')))
243}
244
245fn parse_hf(rest: &str) -> Result<Reference, ParseError> {
246    if rest.is_empty() {
247        return Err(bad("hf: needs an owner/repo"));
248    }
249    // Split the optional pieces off the back before touching the path, so a
250    // '#' or '@' inside neither can confuse the owner/repo split.
251    let (head, revision) = match rest.split_once('#') {
252        Some((h, r)) if !r.is_empty() => (h, r.to_string()),
253        Some(_) => return Err(bad("empty revision after '#'")),
254        None => (rest, "main".to_string()),
255    };
256    let (path, quant) = match head.split_once('@') {
257        Some((p, q)) if !q.is_empty() => (p, Some(q.to_string())),
258        Some(_) => return Err(bad("empty quantization after '@'")),
259        None => (head, None),
260    };
261
262    let mut parts = path.split('/');
263    let owner = parts.next().unwrap_or("");
264    let repo = parts.next().unwrap_or("");
265    if owner.is_empty() || repo.is_empty() || parts.next().is_some() {
266        return Err(bad(format!(
267            "expected owner/repo, got \"{path}\" — a HuggingFace reference has exactly two parts"
268        )));
269    }
270
271    Ok(Reference::HuggingFace {
272        owner: owner.to_string(),
273        repo: repo.to_string(),
274        revision,
275        quant,
276    })
277}
278
279/// A pinned digest rides in a `#sha256:HEX` fragment — the same "extra
280/// context after `#`" convention `hf:` already uses for a revision, so a
281/// reference reader learns one rule instead of one per scheme.
282fn parse_url(s: &str) -> Result<Reference, ParseError> {
283    match s.split_once('#') {
284        None => Ok(Reference::Url {
285            url: s.to_string(),
286            sha256: None,
287        }),
288        Some((url, frag)) => {
289            let hex = frag.strip_prefix("sha256:").ok_or_else(|| {
290                bad(format!(
291                    "unrecognised fragment \"#{frag}\" on a URL reference — \
292                     the only one hearth understands is #sha256:HEX"
293                ))
294            })?;
295            if hex.is_empty() || !hex.chars().all(|c| c.is_ascii_hexdigit()) {
296                return Err(bad(format!("\"{hex}\" after #sha256: is not a hex digest")));
297            }
298            Ok(Reference::Url {
299                url: url.to_string(),
300                sha256: Some(hex.to_ascii_lowercase()),
301            })
302        }
303    }
304}
305
306fn parse_ollama(rest: &str) -> Result<Reference, ParseError> {
307    if rest.is_empty() {
308        return Err(bad("ollama: needs a model name"));
309    }
310    let (path, tag) = match rest.rsplit_once(':') {
311        Some((p, t)) if !t.is_empty() && !t.contains('/') => (p, t.to_string()),
312        Some((_, "")) => return Err(bad("empty tag after ':'")),
313        _ => (rest, "latest".to_string()),
314    };
315
316    let mut parts = path.split('/');
317    let first = parts.next().unwrap_or("");
318    let second = parts.next();
319    if parts.next().is_some() {
320        return Err(bad(format!(
321            "expected name or namespace/name, got \"{path}\""
322        )));
323    }
324    let (namespace, name) = match second {
325        // Ollama's curated catalog lives under `library`, which nobody types.
326        None => ("library".to_string(), first.to_string()),
327        Some(n) => (first.to_string(), n.to_string()),
328    };
329    if name.is_empty() || namespace.is_empty() {
330        return Err(bad(format!("incomplete model name: \"{rest}\"")));
331    }
332
333    Ok(Reference::Ollama {
334        namespace,
335        name,
336        tag,
337    })
338}
339
340#[cfg(test)]
341mod file_scheme_tests {
342    use super::*;
343
344    /// The bug: `looks_like_path` matches anything ending in `.gguf`, and it
345    /// used to be checked before the scheme strips. So every `file:` URL
346    /// pointing at a GGUF — which is every realistic one — came back with its
347    /// scheme still attached, as a path that cannot be opened.
348    #[test]
349    fn a_file_url_yields_a_path_you_can_actually_open() {
350        for (input, want) in [
351            ("file:/models/muse.gguf", "/models/muse.gguf"),
352            ("file:./muse.gguf", "./muse.gguf"),
353            ("file:muse.gguf", "muse.gguf"),
354            // Not a .gguf, which is the one case that used to work — it fell
355            // past the heuristic and reached the scheme branch.
356            ("file:/models/model.bin", "/models/model.bin"),
357        ] {
358            match Reference::parse(input).expect(input) {
359                Reference::Local { path } => assert_eq!(path, want, "for {input}"),
360                other => panic!("{input} should be Local, got {other:?}"),
361            }
362        }
363    }
364
365    #[test]
366    fn a_bare_path_still_works_without_a_scheme() {
367        for input in ["/models/muse.gguf", "./muse.gguf", "~/models/muse.gguf"] {
368            match Reference::parse(input).expect(input) {
369                Reference::Local { path } => assert_eq!(path, input),
370                other => panic!("{input} should be Local, got {other:?}"),
371            }
372        }
373    }
374
375    #[test]
376    fn a_windows_path_is_not_mistaken_for_a_scheme() {
377        // The reason the heuristic was first. It is safe under the new order
378        // because only four known schemes are ever stripped, and `c` is not
379        // one of them.
380        for input in [r"C:\models\muse.gguf", "C:/models/muse.gguf"] {
381            match Reference::parse(input).expect(input) {
382                Reference::Local { path } => assert_eq!(path, input),
383                other => panic!("{input} should be Local, got {other:?}"),
384            }
385        }
386    }
387
388    #[test]
389    fn the_other_schemes_still_win_over_the_path_heuristic() {
390        // `hf:owner/repo` ending in something path-ish must remain a HF
391        // reference, not become a local file.
392        assert!(matches!(
393            Reference::parse("hf:TheBloke/X-GGUF").unwrap(),
394            Reference::HuggingFace { .. }
395        ));
396        assert!(matches!(
397            Reference::parse("ollama:library/llama3:latest").unwrap(),
398            Reference::Ollama { .. }
399        ));
400    }
401
402    #[test]
403    fn an_empty_file_scheme_is_an_error_not_an_empty_path() {
404        // `Local { path: "" }` would fail much later as "no such file: ''".
405        assert!(Reference::parse("file:").is_err());
406    }
407
408    #[test]
409    fn display_name_is_the_model_name_now_that_the_scheme_is_gone() {
410        // Basename with the extension trimmed: a model is called "muse", not
411        // "muse.gguf" and certainly not "file:/models/muse.gguf". Before the
412        // reorder this returned the whole scheme-prefixed string, which then
413        // became the model's key in the spine.
414        let r = Reference::parse("file:/models/muse.gguf").unwrap();
415        assert_eq!(r.display_name(), "muse");
416        assert_eq!(r.key(), "local//models/muse.gguf");
417    }
418}
419
420#[cfg(test)]
421mod url_scheme_tests {
422    use super::*;
423
424    /// The bug this scheme exists to fix: a direct download URL that ends in
425    /// `.gguf` — every realistic one — matched `looks_like_path` and became
426    /// `Reference::Local`, a path that cannot be opened. The error a user saw
427    /// pointed at their filesystem for a problem that was on the network.
428    #[test]
429    fn a_gguf_url_is_not_mistaken_for_a_local_path() {
430        for scheme in ["http", "https"] {
431            let input = format!("{scheme}://example.com/models/model.gguf");
432            match Reference::parse(&input).expect(&input) {
433                Reference::Url { url, sha256 } => {
434                    assert_eq!(url, input);
435                    assert_eq!(sha256, None);
436                }
437                other => panic!("{input} should be Url, got {other:?}"),
438            }
439        }
440    }
441
442    #[test]
443    fn a_pinned_sha256_fragment_is_read_and_lowercased() {
444        let r = Reference::parse(
445            "https://example.com/m.gguf#sha256:DEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEF",
446        )
447        .unwrap();
448        match r {
449            Reference::Url { sha256, .. } => assert_eq!(
450                sha256.as_deref(),
451                Some("deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef")
452            ),
453            other => panic!("expected Url, got {other:?}"),
454        }
455    }
456
457    #[test]
458    fn a_fragment_that_is_not_sha256_is_a_named_error() {
459        let err = Reference::parse("https://example.com/m.gguf#refs/pr/3").unwrap_err();
460        assert!(err.0.contains("sha256:"), "{}", err.0);
461    }
462
463    #[test]
464    fn a_non_hex_digest_is_refused_rather_than_stored_wrong() {
465        let err = Reference::parse("https://example.com/m.gguf#sha256:not-hex").unwrap_err();
466        assert!(err.0.contains("not a hex digest"), "{}", err.0);
467    }
468
469    #[test]
470    fn an_empty_digest_fragment_is_refused() {
471        assert!(Reference::parse("https://example.com/m.gguf#sha256:").is_err());
472    }
473
474    #[test]
475    fn display_name_is_the_filename_with_the_query_string_dropped() {
476        let r = Reference::parse("https://cdn.example.com/models/muse.gguf?token=abc123").unwrap();
477        assert_eq!(
478            r.display_name(),
479            "muse",
480            "a query-string token must never end up in a model name"
481        );
482    }
483
484    #[test]
485    fn display_name_falls_back_to_the_whole_url_when_the_path_is_empty() {
486        let r = Reference::parse("https://example.com/").unwrap();
487        assert_eq!(r.display_name(), "https://example.com/");
488    }
489
490    #[test]
491    fn key_is_stable_across_calls_for_the_same_url() {
492        let r = Reference::parse("https://example.com/m.gguf").unwrap();
493        assert_eq!(
494            r.key(),
495            Reference::parse("https://example.com/m.gguf")
496                .unwrap()
497                .key()
498        );
499        assert_eq!(r.key(), "url/https://example.com/m.gguf");
500    }
501
502    #[test]
503    fn a_url_needs_a_download_like_every_non_local_reference() {
504        let r = Reference::parse("https://example.com/m.gguf").unwrap();
505        assert!(r.needs_download());
506    }
507}