hearth-resolve
One reference syntax over Ollama's registry, HuggingFace GGUFs, and your own disk.
Their catalogs, our runtime. hearth does not want to be a model registry — two good ones already exist, with the models people actually run. This crate turns any reference into fetchable blobs without downloading anything, so the VRAM planner can refuse a model before a single byte moves.
[]
= "0.3"
One syntax, three origins
use Reference;
// A bare name is Ollama's curated library — the shorthand everyone already types.
parse?; // ollama library/llama3:latest
parse?; // ollama library/deepseek-r1:32b
parse?; // a user namespace
// HuggingFace, with the quantization pinned or left to us.
parse?;
parse?;
// Already on disk. No catalog, no download, no opinions.
parse?;
let r = parse?;
r.key; // stable identity for the store and the models dir
r.display_name; // what a human should read
r.needs_download; // false for Local — nothing to fetch
A bare name resolving to Ollama is a deliberate compatibility choice: it is what every existing script and every operator's muscle memory already types, and gratuitously breaking that buys nothing.
Choosing a quantization, and saying so
Point at a HuggingFace repo without pinning a quant and something has to choose. That choice is explicit and reported, never silent:
use ;
quant_of; // Some("Q4_K_M")
Preference order starts at Q4_K_M — the quality/size knee for most GGUF models, and the one a human would pick if they were reading the file list themselves.
Two details in here exist because getting them wrong is quiet and expensive:
Longest-token-match wins. Q4_K is a prefix of Q4_K_M, so naive matching silently hands you a different model than the one named in the file. The tokenizer takes the longest match, so Q4_K_M is never swallowed by Q4_K.
Multi-part GGUFs are all-or-nothing. A file named -00001-of-00003 is one third of a model. total_parts() reads the count and is_multipart() flags it, so a plan either has every shard or is refused — rather than loading a third of a model and reporting a corrupt tokenizer.
A plan is bytes, before any bytes move
use ;
let plan = plan_from_ollama_manifest?;
plan.total_bytes; // Option<u64> — feed straight into the VRAM budget
plan.is_multipart;
total_bytes() is the whole point of resolving before downloading: it is what lets hearth-core say "short by 14.8 GiB" at declare time instead of after a 40 GiB download and an out-of-memory error.
From an Ollama manifest, only application/vnd.ollama.image.model is the weights layer — the manifest also carries templates, params and licenses, and summing all of them would overstate VRAM by a comfortable margin and refuse models that fit.
Verified against the live registries
The parsers were checked against real manifests and real repo listings, not fixtures invented to match the code:
Fixtures written by the same person who wrote the parser agree with the parser by construction. Live registries do not.
The rest of the workspace
| crate | what it does |
|---|---|
hearth-core |
state machine, VRAM planner, fleet router. Pure logic. |
| hearth-resolve | this crate — references to fetchable blobs |
hearth-store |
the NEDB spine — bi-temporal, causal, tamper-evident |
hearth-serve |
the supervisor and the hearth CLI |
Built by Vex × Interchained
© Interchained LLC · BUSL-1.1 (converts to Apache-2.0 on 2030-08-27)