Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Loading builds

A kit loads a model by name through bunsen::data::builds: providers answer names with builds, a factory dispatches a spec to them, and the kit’s hook builds from the files the cache brings local.

Prefabs, builds and resources

Three things are kept apart, because they vary independently:

  • A prefab is a geometry by name, with no weights, so a name means a shape before anything is fetched. A kit’s prefabs are constructors on its config (WhisperApiConfig::tiny_en()), listed by Prefabs.
  • A build, a ResolvedBuild, is what the catalog says one model is: its name and aliases, its tags and presets, the geometry it states, and the resources its contract’s slots are bound to.
  • A resource, a Resource, is one file (Resources and the cache).

A build states its geometry rather than naming a prefab, and a kit’s tests check that every stated geometry is a prefab’s. One file can serve many builds: Whisper’s two vocabulary files serve its twelve checkpoints, each a resource the builds bind. Builds and resources know nothing about how a model is built: that is the kit’s business (builds and resources).

Providers

A BuildProvider is a namespace of builds: the provider in provider:ref. Two are in use. catalog:, a CatalogBuildProvider, holds the builds of the kit’s contract in the built-in catalog, and in any extension layer imported over it. hf:, an HfProvider, is a Hugging Face repo, by org/repo, answered with a build named hf/<org>/<repo> from the repo’s listing, fetched once through the cache.

A factory holds a kit’s providers in search order. A spec whose prefix names a registered provider goes to that provider, and nowhere else. Any other spec is offered whole to each provider that answers bare names, in order, and the first build wins. A hub never answers a bare name, so hf: is only reached when the spec names it. The two kinds of “no” are kept distinct. A provider that doesn’t have the build says so (Ok(None)), and the search moves on. A provider that fails returns an error, and the error aborts the lookup, because a hub that cannot be reached is not the same as a hub that has no such build (dispatch).

A spec is a lookup expression: [provider:]name, then an optional box of presets and an optional YAML patch over the resolved config, as in 'openai/small[translate]{beam_size: 1}'. Quote it on a shell command line, since [ and ] glob. Only the name is dispatched. The box and the patch are checked against the build found before anything is fetched, and a kit that takes no presets refuses them rather than ignore them (lookup expressions). Catalog names compare ignoring case, so Qwen/Qwen3-0.6B finds qwen/qwen3/qwen3-0.6b. hf: names compare as given, since they are paths in URLs.

There is no process-wide registry. Each kit ships a default_{kit}_factory(), and a caller that wants another provider adds it to that factory (no registry).

Deferred models and the kit’s hook

What a name resolves to is a DeferredBuild model: a BuildRef (the build, or a given resource set), plus the kit’s ConstructInit hook. The hook is chosen for the resource set by for_resource_set, from the resources’ formats, because builds from different providers can need different readers: an OpenAI .pt checkpoint and a Hugging Face safetensors repo are both Whisper, read two ways.

Loading runs three steps. The hook’s plan completes the resource set and checks what the build promises, such as its stated geometry, before any bytes are fetched. The cache then brings the files local. Finally the hook’s try_init builds the model from them. Before loading, a caller can lay its own resources over the build’s with with_overlay, where the caller’s resource wins by slot. bunsen-tool asr family whisper’s --vocab flag works this way.