Introduction
bunsen - tackling tomorrow’s burn problems today!
The burn team is working hard to give us a stable long term foundation for developing high-performance and maintainable tensor programming in Rust; The “in Rust” aspect requires a degree of type and runtime R&D research and that requires a conservative posture to api extension.
bunsen provides a “batteries included” complementary community standard library
for research extensions to burn; ideas which are useful enough
to collect into one place, document, and build upon; but front-run
the burn interface frontier.
Every idea in bunsen seeks to either be refined and ported into burn,
or supplanted by the eventual burn solution to that problem.
This book and the API docs
The API docs answer what is this type, and how do I call it? This book answers how is bunsen put together, why is it built that way, and how do we work on it? The two are deliberately split:
- every interface, lifecycle and example lives in the API docs, where the compiler checks it;
- this book explains the organization, the bunsen-specific systems that cut across modules, and the development strategies behind the code, and links into the API docs for everything else.
Every link from this book into the API is checked when the book is built, so a renamed or moved item breaks the build, not the reader.
Why a “standard library”?
The burn ecosystem moves quickly, and single-purpose extension crates tend
to drift out of sync with each burn release. bunsen exists to:
- track the
burnrelease cycle, so dependent code doesn’t have to; - give one dependency surface for common building blocks, instead of a tangle of single-purpose crates;
- centralize testing, documentation and validation, so contributed components can be trusted across projects.
How to read this book
- New to bunsen? Start with the workspace and the bunsen crate, then installing and first use.
- Building models on bunsen? Read module design conventions and the systems chapters relevant to you: shape contracts, pretrained models, streaming contexts, parameter groups.
- Contributing? The development strategies
part explains how bunsen is tested, validated and released;
CONTRIBUTING.mdis the canonical contributor guide.
The workspace
bunsen is two Cargo workspaces. The main one, at the repository root, has
three kinds of member; only the crates under crates/public are published,
and everything else exists to build, check or demonstrate them. The
validation workspace, under validation/, holds bunsen’s models to
reference implementations; nothing the main workspace runs builds it.
crates/public/ the published crates (released together, one version)
crates/dev/ development tooling: upstream bug repros, benches, test audio
examples/ runnable programs, one per kit or system
tools/ one-shot fixture generators and repo checks (Python, stdlib-first)
validation/ a workspace of its own (validation/Cargo.toml, validation/Cargo.lock)
onnx/ the ONNX references and checkpoints, fetched at build time
models.yml the validation schedule: the models the validation crates check, which a profile chooses from
models/ cross-checks of bunsen models against those references
tools/ the fixture generators whose output lands in models/
Published crates
All published crates share the workspace version and are released together by release-plz (Releasing).
| Crate | What it is |
|---|---|
bunsen | The library: contracts, ops, blocks, kits, the pretrained-model machinery, audits. Most users depend on this alone. See the bunsen crate. |
bunsen-contracts-macros | The proc macro behind shape_contract!. Never a direct dependency; bunsen re-exports it. |
bunsen-firehose | A column-oriented data-processing pipeline that feeds burn’s Batcher. Independent of bunsen. See Firehose. |
bunsen-firehose-image | Image operators for firehose: loading, augmentation, conversion to tensor data. |
bunsen-arrow-dataloaders | Preview. Parquet shards to tokenized training batches, for language-model training. See Datasets. |
bunsen-app | Shared command-line plumbing for bunsen’s binaries: device and precision flags, logging, shard selection, and the weights cache’s flags and cache commands. The examples and bunsen-tool are built on it. |
bunsen-tool | A binary, cargo install bunsen-tool: bunsen-tool asr, speech to text by profile (en, multi, translate-en) or with Parakeet, Qwen3-ASR, Voxtral Realtime or Whisper directly, each through its stream driver; speaker diarization with Sortformer; bunsen-tool chat, chat with Qwen3 or nanochat, whose driver is also a library (bunsen_tool::chat); and bunsen-tool cache over the weights cache. |
Development crates
| Crate | Role |
|---|---|
burn_bug_repro | Reproductions of defects in burn and its ecosystem, each paired with a pin on today’s behaviour. See Upstream bug reproductions. |
silero-bench | A benchmark CLI for Silero VAD. See Benchmarks. |
bunsen-test-audio | The audio clips the tests, the validation suites and the fixture scripts read, with their provenance and ground truth. A leaf crate, so bunsen takes it as a dev-dependency. |
The validation workspace
validation/ depends on the main workspace’s crates by path, and has a
lockfile of its own; every package bunsen’s crates reach in it is the
version Cargo.lock has (tools/check_validation_lock.py, run in CI).
Building it with its default features fetches nothing; checkpoints (at
run time) and reference (at build time) fetch, and only the validation
runs turn them on
(Validation). No CI job builds it;
cargo make check-validation does, by hand.
ONNX binding crates
| Crate | Role |
|---|---|
rewrite-genai-onnx | Rewrites an onnxruntime-genai ONNX export’s com.microsoft ops to standard ONNX, so burn-onnx imports it; the bind-{model}-onnx build scripts call it. |
bind-{model}-onnx (whisper, silero, parakeet, qwen3, qwen3-asr, sortformer, voxtral) | Each validation crate’s assets: the checkpoints it compares, fetched and digest-pinned at build time and laid out as a resource cache, and the reference model burn-onnx generates from an upstream ONNX export. Host no files. See Assets, bundling and the network. |
Validation crates
| Crate | Validates |
|---|---|
gemma-model-validation | Gemma 2 and 3 against transformers’ own greedy decodes, past each row’s sliding window, at the end of a long conversation and in chat sessions, in float32 and, on CUDA, in bf16. |
nanochat-model-validation | nanochat against upstream’s own code at the pinned commit of each model, on the community d20 and d18 checkpoints: prefill logits and greedy decodes, in float32 and, on CUDA, in bf16. |
parakeet-model-validation | Parakeet TDT against an independent implementation generated from NeMo’s own ONNX export, stage by stage. |
qwen3-asr-model-validation | Qwen3-ASR against an implementation generated from an ONNX export, and against transformers’ own decode of real speech. |
qwen3-model-validation | Qwen3 against an implementation generated from the published ONNX export, and against transformers’ own greedy decodes, long conversation and chat sessions, in float32 and, on CUDA, in bf16. |
silero-model-validation | Silero VAD against the ONNX graph it was transliterated from, and against a committed golden trace. |
sortformer-model-validation | Sortformer diarization against ONNX exports of the same checkpoints (Nemotron-3-Diarization, Sortformer v2.1), each held itself to onnxruntime’s run of the published graph, and against NeMo’s own diarization of an AMI excerpt by each model. |
voxtral-model-validation | Voxtral Realtime against an implementation generated from the published ONNX export, and against transformers’ own greedy decodes of real speech. |
whisper-model-validation | Whisper against an ONNX export, stage by stage, and against openai-whisper’s own decode of real speech. |
Their reference checks are not part of a normal build’s test run; they are how a kit earns trust. See Validation against reference implementations.
Examples and tools
The examples are runnable programs, one or more per kit or
system. tools/ holds the Python scripts that generate bunsen’s committed
test fixtures from reference implementations, and the repository checks CI
runs; validation/tools/ holds those that generate the validation crates’
fixtures. Each fixture script is run once by hand, never by CI
(Validation).
The bunsen crate
bunsen is organized as layers: components higher up are built from the
ones below and never the reverse. Knowing the layers tells you where a new
piece of code belongs, and what it may depend on.
From the top of the stack down:
| Layer | Contents |
|---|---|
kits, sims | Whole models, with their configs, pretrained indexes and runtime drivers; simulations. |
blocks | torch.nn-like components: module roots and tree parts. |
ops | Operations: free functions, and Module/Config types that hold cached tables or stream state. |
| foundation | burner (burn extensions), contracts (shape checks), errors, rust_ext (Rust helpers), support, zspace. |
burn | The framework underneath; not part of bunsen. |
Beside the stack, outside the layering:
data: files, caches, pretrained models and dataset shards; kits load through it.audit: recording and verifying tensor checkpoints across runs and backends.
The split between ops and blocks is a rule, not a convenience: blocks
are nn-like components meant to sit in a module tree; ops are operations
that may use the Module and Config machinery only to hold cached tables
or state. The bunsen::ops module docs state
it, and Ops, blocks and burn extensions
explains why.
The modules
Each module’s own docs carry its map; this table is the one-line version.
| Module | What it is for |
|---|---|
kits | Complete domain implementations: image models (images), language models (language), speech (speech), and the shared token seam (tokens). See Kits. |
sims | Simulations written as tensor programs: Conway’s Game of Life (conway) and a lattice-Boltzmann fluid (lbm). |
blocks | Reusable Module components: conv blocks, image layers, recurrent cells, transformer parts. |
ops | Tensor operations, including the signal-processing front ends and attention ops. |
burner | Extensions to burn’s module machinery: the config lifecycle (ModuleInit, ToStructureConfig), reflection, grouped optimizers, tensor extension traits, PyTorch-load repairs. |
contracts | Runtime tensor-shape contracts. See Shape contracts. |
data | The disk cache, resources, the catalog, model loading, formats and dataset shard sets. See Data: from files to models. |
audit | Audit probes: record a stream of tensor checkpoints from one run and verify another against it. See Audit probes and baselines. |
errors | BunsenError and its kinds, context frames and typed causes; BunsenResult; the try_x / x convention; and, with testing, the ErrorMatcher test matchers. |
rust_ext | Rust-language extensions with no tensor or burn dependency: CloneBox / CloneRef, array and range helpers, and LocationDesc, a serializable source location. |
support | Shared utilities, including the test backends and devices in support::testing. |
zspace | Integer-lattice index and shape helpers. |
prelude | The traits most code needs in scope, for one glob import. |
public | Re-exports of public dependencies (burn), so downstream code uses the same versions. |
Where new code goes
- A new layer or module family used as part of a model is a block.
- A new operation, even one that keeps a precomputed table or stream state, is an op.
- A whole model with its configs, weights and drivers is a kit; its
reusable parts get promoted to
blocksoropsonce a second consumer appears. - Anything that extends burn’s machinery itself (module traversal,
records, optimizers) goes in
burner. - A Rust-language helper with no tensor or burn dependency goes in
rust_ext.
Whatever the layer, a new module follows the module design conventions.
Features, backends and the network
bunsen’s cargo features fall into a few families, and each family answers a different question about your build. The crate docs render every feature with its own description; this page explains how to choose among them. The naming rules behind them are in STYLE.md’s cargo features chapter.
Which backend?
wgpu, vulkan, cuda, metal and flex compile a burn backend into
bunsen’s build. The accelerators decide what
performance_device
returns, which is the device bunsen’s tests and benchmarks run on. Your own
code can run bunsen on any device that burn was built with, whatever these
say; the features only matter for the device bunsen itself picks.
Without a backend feature, performance_device() is the CPU. A plain
cargo test therefore passes while testing nothing on a GPU; see
Testing and backends.
Which parts of bunsen?
Some modules are optional because they pull in dependencies most users don’t need, or code most users don’t compile:
kits,speechandsims: the model kits; the speech kits among them (speech recognition, diarization, voice activity), which turn onkitsandaudio; and the simulations. All three are default.reflection: the XML/XPath module reflection behind parameter groups.train: the grouped optimizers and otherburn/trainintegration.audioandtokenizer: audio file decoding, and turning token ids into text, for the speech kits.testingandaudit: the test support insupport::testingand the audit probes.store: reading checkpoints through burn-store, in every format bunsen knows: burnpacks, PyTorch.ptstate dicts, safetensors, NeMo’s.nemoarchives and Phonon archives. Default.
The crate docs say which are on by default. default-features = false plus
the features you use gives the smallest build; the no-default-features
configuration is checked in CI, so it always builds.
May the build, or the program, reach the network?
Two separate switches, never on by default:
fetch: the program may reach the network at run time, to fetch pretrained weights or dataset shards into the disk cache. Without it, everything works from files already in the cache.indicatifadds a progress bar.- Build-time network: a build script may fetch assets. No bunsen feature
does; only the validation crates’
referenceturns on the bind crates’ fetches of the ONNX references and their bundles, digest-pinned. Theircheckpointstests fetch at run time, throughfetch.
Assets, bundling and the network explains the scheme, and why bundled weights are “a populated cache directory”.
What does docs.rs show?
docs.rs builds bunsen with an explicit feature list (fetch, indicatif,
testing, audit), not all-features, which would turn on every backend.
Items behind a
feature carry a badge saying which one. This book’s API links are resolved
against the same list, so a link that works here works on docs.rs.
Installing and first use
Add the dependency
cargo add bunsen
bunsen is versioned on its own semver line, released by release-plz; its
version is not tied to burn’s. Each release builds against one burn
version, and bunsen re-exports it as bunsen::public::burn,
so you can use the same burn without pinning it twice. bunsen requires a
recent stable Rust; its minimum supported version is the rust-version on its
crates.io page.
Pick features as described in Features, backends and the network. The defaults build offline and include the common modules.
A first program
This builds a block from its config, runs it, and checks the shape of its
output with a shape contract. It is compiled and run by cargo test as part
of the workspace, so it can’t drift from the API:
use bunsen::{
blocks::transformers::mlp::{
TransformerMlp,
TransformerMlpConfig,
},
prelude::*,
support::testing::cpu_device,
};
use burn::tensor::Tensor;
let device = cpu_device();
// `init` comes from `ModuleInit`; the binding's type names the module.
let mlp: TransformerMlp = TransformerMlpConfig::new(16).init(&device);
let x = Tensor::<3>::zeros([2, 5, 16], &device);
let y = mlp.forward(x);
// Check the output's shape, and name its dimensions while doing it.
let [batch, time, embed] = unpack_shape_contract!(["batch", "time", "embed"], &y.dims());
assert_eq!((batch, time, embed), (2, 5, 16));
Three things to notice, each with its own chapter:
TransformerMlpConfig::initcomes fromModuleInit, whichbunsen::preludebrings into scope, and the binding’s type (TransformerMlp) names the module it builds. See Module design conventions.unpack_shape_contract!both checks the shape and names its dimensions. See Shape contracts.- The device comes from bunsen’s test support:
cpu_deviceis burn’s CPU backend. Your own code can create devices however burn allows, such asDevice::default(), which follows the backends compiled in. See Testing and backends.
Next
- The bunsen crate: what’s in the library, and where things go.
- Kits: whole models you can load by name.
- The API docs for everything else.
Kits
A kit is a whole thing you can pick up and use: a model family with its
configs, the weights it can load and a program that runs it. The
simulations, bunsen::sims, are built the same way. Where blocks and ops are parts,
a kit is what the parts are for.
The bunsen::kits docs list the kits, and describe
the anatomy of a kit piece by piece, with a
table of how the ResNet, Whisper and Silero kits fill each piece in. This
page explains why kits are shaped that way, and what building one involves.
Why a shared shape
No trait makes a module a kit. Kits share a shape because they solve the same problems, and a solved problem should look the same each time it appears:
- Naming a model. A user should be able to say
resnet50oropenai/base.enand get a model. A prefab map names geometries; a pretrained table names checkpoints; a factory turns either name into a loaded module. The machinery is shared and lives inbunsen::data::pretrained. A kit contributes tables and aConstructInithook, not a loader of its own. See Data: from files to models. - Configuring it. A kit’s configs follow the Simple or Stacked shape from Module design conventions. A user-facing policy config is small and stable; the structure config spells out the implementation.
- Running it. A model that decodes or streams keeps no per-stream state of its own. The state is injected as a context or cache, so one loaded model serves several streams. See Stateless modules and streaming contexts.
- Trusting it. A port of a published model is only as good as its agreement with the original. Kits that load published weights have a validation crate that steps them against the reference implementation. See Validation against reference implementations.
Building a kit
A new kit grows in roughly this order, and each step is useful on its own:
- The model and its configs, in the kit’s module, built from existing
blocks and ops where they fit, with shape contracts at its boundaries and
a narrow
Metatrait. - An example under
examples/that runs it end to end. - Names: a prefab map, then pretrained rows and a
ConstructInithook, and adefault_{kit}_factory(), once there are weights to load. - A validation crate under
validation/models/, once the kit claims parity with an upstream implementation. - Promotion: a layer that a second kit needs moves out to
blocksorops.
The kit’s module docs carry its lifecycle and an example; the
bunsen::kits table gains a row. This book doesn’t
need to change unless the kit brings a new cross-cutting system.
Kits evolve faster than the rest of the crate while their domains are being
filled in; see bunsen::kits on stability.
Examples
The examples/ directory holds runnable programs. Each one exercises a kit
or a system end to end, and its README says which bunsen features it uses
and how to run it. They are not published, and they are where a change to a
public API is felt first, so CI builds all of them.
Speech to text is bunsen-tool asr,
a published binary rather than an example: files or the microphone, through
the Parakeet, Qwen3-ASR and Whisper stream drivers, and who spoke when
through the Sortformer diarizer, with commands that fetch and inspect models
and manage the weights cache. It is built on the same
bunsen-app plumbing.
| Example | What it shows |
|---|---|
train-chat | Trains a NanoChat GPT from scratch on streamed dataset shards, with nanochat’s Muon + AdamW parameter groups. |
resnet_finetune | Fine-tunes a pretrained ResNet for multi-label classification, with model surgery: a new head, a swapped activation, DropBlock and stochastic depth. |
resnet_tiny | Trains a ResNet from scratch on CINIC-10 through a firehose pipeline, loading a checkpoint into a modified prefab. |
swin_tiny | Trains a Swin Transformer V2 on CINIC-10, sharing resnet_tiny’s data pipeline. |
conway | Conway’s Game of Life in 2D and 3D, on any backend: an interactive view and a benchmark. |
lbm2d_vis | A D2Q9 lattice-Boltzmann fluid simulation, rendered live. |
Choosing a device
Every example picks its device at run time with --device (auto, cuda,
metal, vulkan, wgpu or flex) and --device-index, through
bunsen-app’s DeviceArgs. A backend is offered only when the example was
built with its cargo feature (cuda, metal, vulkan, wgpu); flex, the
CPU, always is, and auto, the default, takes the first accelerator built
in. Each README has the exact command.
--precision picks the default float dtype: auto is the example’s own
choice, full is f32, and half is the example’s half precision, which
resolves per backend: bf16 where a training example wants f32’s range and
the backend runs it well, f16 where any 16-bit float will do, and f32 on
the CPU or where the backend lacks the half. --float-dtype and --int-dtype
name an exact dtype instead. The training examples also draw burn’s terminal
dashboard (their default tui feature) when run in a terminal.
Features, backends and the network explains bunsen’s own
backend features and why some examples also need fetch.
Module design conventions
A bunsen module family has three parts: a config, the module it builds, and
a narrow trait that both of them answer. This chapter explains
why the parts are shaped as they are, and how to choose between the two
config shapes, Simple and Stacked. What the shapes are and how they work is
defined, with a compiled example of each, in
ModuleInit and
ToStructureConfig. What the
author of a family must do (naming, promotion, the required tests) is set by
STYLE.md, “Module design”.
Why conventions at all
burn provides the basic parts: a #[derive(Config)] struct that builds a
#[derive(Module)] struct. That is enough for one self-contained module. It
starts to strain once modules nest inside larger ones, and once configs come
from files, loaders and users instead of from your own code. Nesting raises
three questions, and the conventions answer each of them the same way
everywhere:
- how a config reports that it cannot build its module;
- how a parent, a loader or a test reads a child’s geometry without keeping a second copy of it;
- how a module can offer users a short list of knobs while its implementation needs a long list of parameters.
Common to both shapes
The config lives in the module’s file. The knobs sit next to the code they drive, and a reader never has to search for the other half.
A narrow FooMeta trait. A parent that owns a child needs structural
facts about it: its width, its head count, its output resolution. If the
parent copies those numbers into its own fields, the same number lives in
two places, and the copies can disagree. Instead, the family defines a trait
that holds only the values a caller or a test needs to read back. Both the
config and the module implement it, and the module answers from its live
tensor shapes. Code that holds either form can ask the same question.
ModuleInit, with a fallible
try_init. A config is data. It is deserialized, assembled by loaders,
and edited by users. A config whose fields disagree is an input error to
report, not a bug, so try_init returns an error and init is the
panicking convenience
(why it is fallible).
The trait is in bunsen::prelude. The module type comes
from the binding, not from the device
(calling it). A few configs
need more than a device to build their module, and keep an inherent init
instead
(hand-written init).
try_x and x. The same pairing runs through the whole crate. try_x
returns a BunsenResult, and x (or
expect_x) panics through
WithOkOrPanic. Input that can be wrong is
reported as an error of the kind it is,
not as a panic: a config that breaks its own documented rule is Illegal,
and the same config read from a file is Policy
(the convention,
which kind; see also Errors).
Modules over bare tensors. A type that owns a tensor derives Module
even when nothing in it is learnable. Module is burn’s traversal trait,
and deriving it is what lets to_device reach the tensors. Hold fixed
tables as bare tensors, not as Params. A bare tensor is not written to a
record, ModuleMapper passes skip it, and reflection does not see it, so
say so on the type. A config that the module keeps is a #[module(skip)]
field with an accessor, as in
PerceptiveAudioConverter::options.
The derive treats every field that is not a primitive as a sub-module, so
any other value object the module holds is skipped too.
The agreement test. A family’s tests build a module from a config that
is non-default in every field, then assert that the config and the module
answer every FooMeta method alike. This test catches a module that
silently ignores one of its knobs.
Variant behaviour lives on the enum. When a value differs per variant,
it is a method on the enum, not a match at each use site. A new variant
then changes one place.
Simple Config
FooConfig builds Foo and implements ModuleInit itself. Both implement
FooMeta. This is the shape for a module whose user-facing knobs are the
parameters its implementation needs.
In the crate, TransformerMlpConfig
builds TransformerMlp, and
SlidingStftConfig builds
SlidingStft. The compiled toy is
ModuleInit’s Simple Config example.
Stacked Config
A module’s parameter list grows in two unrelated directions. The knobs that describe what the module is for, such as “12 layers, 768 wide”, are few and stable. The parameters the implementation needs, a config for every sub-module of every layer, are many, and they change whenever the implementation does. A single config that holds both is tedious to fill in. It also turns every implementation change into a breaking change for callers who only wanted twelve layers.
The Stacked shape keeps the two apart:
FooStructureConfigis the unrolled tree, with one field per sub-module config, and it implementsModuleInit. Loaders and tooling work with it, because the layers are spelled out there.- At least one upper policy config computes that tree from the user’s
knobs. It is named for its policy (
FooContractConfig,FooApiConfig,FooSignalConfig) and never bareFooConfig, which would mean the Simple shape. “Contract” here names the user-facing knobs; it has nothing to do with shape contracts. Several policies may build the same structure, or refine one another. - A policy implements
ToStructureConfig, and getsModuleInitfrom that trait’s blanket impl. If a policy also implementsModuleInititself, the compiler rejects it (E0119). That is deliberate:policy.init(&device)andpolicy.to_structure().init(&device)run the same code, so they cannot drift apart (initfor free). Per-policy logic, including validation, goes intry_to_structure. FooMetais required on the structure config and the module, and optional on the policies.
Both pathways are real uses. A caller lowers first to inspect or edit the
tree before building it, as a loader overriding one layer would. A caller
that only has the knobs builds straight from the policy. Each Stacked family
has a test that the two pathways build modules that agree. The compiled toy
is ModuleInit’s Stacked Config example.
The crate’s Stacked families show the variations:
- ResNet has one policy,
ResNetContractConfig, overResNetStructureConfig. Inside it,ResidualBlockStructureConfigis an enum. That makes it one contract with two implementations (basic and bottleneck), and the enum, not its callers, dispatches each method to the variant it holds. - Silero VAD has two chained policies.
SileroVadSignalConfigrefines intoSileroVadStftConfigthrough an inherentto_stft, and both lower straight toSileroVadStructureConfig. - Whisper has
WhisperApiConfigoverWhisperStructureConfig. - The decoder stack has two policies over one structure.
UniformStackConfigrepeats one layer config, andPatternedStackConfigpicks each layer’s from a few kinds (Gemma 3’s five sliding-window layers to each full one). Both lower toDecoderStackStructureConfig, one block config per layer, which a kit with its own per-layer rules (nanochat’s window pattern and value embeddings) builds directly. - Swin Transformer V2 has a fallible lowering.
SwinTransformerV2ContractConfigchecks that its stages fit the input and the window, sotry_initon a bad policy returns an error instead of panicking.
Choosing, and promoting
Start with Simple. Promote a family to Stacked when one of these happens:
- the knobs users set diverge from the parameters the implementation needs;
- a second default policy appears;
- loaders or tooling need the unrolled tree.
When you promote, FooConfig takes a policy name and a FooStructureConfig
appears. A bare FooConfig never coexists with a FooStructureConfig. Call
sites that build with .init(&device) keep working, because the policy gets
init from the blanket impl; only the type name changes.
Pitfalls
initneeds the module type.ModuleInitis generic over the module it builds, so where nothing else pins that type,config.init(&device)needs a binding such aslet m: Foo = ..., or inference fails.- A bare tensor is not loaded. A fixed table held as a bare tensor is not
in the record, so
initmust recompute it. A load never restores it. - Don’t override a policy’s
init. The E0119 error you get when you try is the convention working as intended. Put the logic intry_to_structure.
Errors
Every fallible bunsen function returns a
BunsenResult, and every failure is a
BunsenError. This section explains how the
error is shaped and why, from three points of view, one per chapter:
- Consuming errors: code that calls bunsen and receives errors. It needs to know what to do with one, and how to show one to a person.
- Producing errors: code that builds errors. It needs to know which kind to pick, what to put in the message, and what belongs in a cause.
- Complex handlers: subsystems with a recovery strategy of their own, such as the cache that tries another mirror. They need typed facts that generic code never reads.
The reference for all of it, with compiled examples, is the
bunsen::errors module docs.
The shape of an error
An error has five parts:
- a kind, a
BunsenErrorKind, which says what a generic consumer should do; - a one-line message, which says what went wrong;
- optional multi-line details, the evidence: a diff, a dump, a list;
- the frames of context it gathered on its way up, each saying what a layer was doing, with that layer’s source location;
- an optional cause: a typed fact, such as which key a lookup missed, or the foreign error underneath.
The kind is the only part generic code branches on. Kinds are reaction classes, not descriptions of a failure. There are few of them on purpose: a generic consumer must be able to handle each one without knowing which subsystem raised it. What went wrong in detail is the job of the message and the cause.
Why kinds, and not a variant per failure
A variant per failure grows with every subsystem. It forces each consumer to know every subsystem’s vocabulary, and turns every new failure into a breaking change. It also invites a catch-all variant that ends up holding unrelated failures, which callers then tell apart by reading message text.
Bunsen’s errors separate the two questions. What should I do about it? is the kind, which is small and stable. What exactly happened? is the cause, which a subsystem defines for itself and only the code that wants it reads. The complex handlers chapter shows the second question at work.
Why context is separate from the message
An error passes through several layers on its way to a person, and each layer knows something the layer below it does not: the model being loaded, the shard set, the block index. Adding that knowledge by formatting the error into a new message loses the original kind and cause, and the result cannot be matched or retried correctly. Frames add the knowledge without touching the error itself. Together they make the report a logical traceback: the layers that chose to say something, with their source locations, in release builds, and across threads.
Consuming errors
This chapter is for code that calls bunsen and gets an error back: an application, a training script, a kit that uses another subsystem, a test.
React to the kind
A consumer that is not a specialist reads one thing, the kind, and has a small, fixed set of reactions to choose from:
- A bug,
IllegalorInternal.is_bugis true. Escalate it. A script panics. A long-running service logs the report and fails the one request or graph, not the process.Illegalmeans the calling code broke a documented rule.Internalmeans bunsen broke its own, and is worth an issue. - Retry,
Unavailable.is_retryableis true for this kind only. Back off and try again, within a budget. No other kind improves with time, so retrying any other kind only delays the same failure. - Fall back,
Lookup. A key did not resolve. Try the next source, or tell the person which keys exist. TheLookupErrorcause carries the candidates. - Fix the settings,
Policy. The request is misconfigured: a config breaks a rule, downloads are turned off, values do not match a baseline. Tell the person which setting to change. - Report the source,
InvalidResource. Something from outside the program is not what it should be: a corrupt download, a file in the wrong format, a checkpoint that is not the model it claims to be. Name the source. Retrying the same source will not help. - Take another path,
Unsupported. The request is valid, but this code or this build does not do it. - Tell the operator,
Sys. The host failed: a full disk, a thread that would not spawn. Other. Unclassified; treat it as a bug in whatever produced it.
Do not branch on message text. Messages are written for people, and are free to change. Anything a program should branch on is either the kind or a typed cause. Reading causes is the subject of the complex handlers chapter.
Show it to a person
An error prints two ways:
Display({}) is one line: the frames of context, outermost first, then the message. Use it in log lines and status text.- The report (
report,{:#}, orDebug) is the whole story: the kind, the message and where it was built, the details, each frame with its source location, the cause chain, and a backtrace for a bug. Print it wherever a person will debug the failure.
main() -> BunsenResult<()> prints the report on failure, because Rust
prints a returned error’s Debug. So does
ok_or_panic.
try_x or x
Bunsen’s fallible operations come in pairs
(the convention): try_x returns a
BunsenResult, and x panics with the report. Call x when the input is
yours and known to be good, or when nothing above you could recover anyway.
Call try_x when the input comes from outside the program, and when you are
a service that must outlive one bad request.
Pass it up with context
A consumer is usually also a layer that the error passes through on its way
to someone else. Add what you know with
ResultContext: .context("loading the corpus"), or .with_context(|| ..) to build the text only on failure. This
costs nothing on success, and does not change the kind or the cause.
Two situations call for more than context, because you know something about the blame that the code below you could not:
- You passed values you read from outside the program, such as a config
file or a command line, and got an
Illegalback. The rule that broke is the input’s fault, so re-mark it withas_policy. - You passed a name your own code chose, and got a
Lookupback. That is a bug on your side, so re-mark it withas_illegal.
The re-marking rules keep a bunsen bug from ever becoming the caller’s fault.
Testing what you got
A test that expects a failure checks the parts it is about, with
ErrorMatcher (feature
testing): the kind, and perhaps a phrase of the message or a typed cause.
A test that pins the whole message breaks every time a word changes.
BunsenError is not PartialEq for that reason.
Producing errors
This chapter is for code that builds errors: any fallible function in bunsen,
or in a crate built on it that returns BunsenResult. What each constructor
and cause type does is in the
bunsen::errors docs. This chapter is
about the decisions those calls encode.
Choose the kind by who has to change
The kind answers one question: who or what has to change for the operation
to succeed? The errors docs ask it as an
ordered list:
- If the code has to change, the kind is
Illegal, orInternalwhen the code at fault is bunsen’s own. - If the request or its settings have to change, the kind is
Policy. - Otherwise the world disagrees:
Lookup(a key did not resolve),Unavailable(not now), orInvalidResource(present, but wrong).
Unsupported, Sys and the Other bail-out cover what is left.
Locality, and why blame is not final
The hard case is the boundary between Illegal and Policy, because the
same check can be either. A config whose fields disagree is a bug when a
program built it, and a bad setting when it was read from a file. The
function that checks the config cannot know which.
The rule is locality:
- a rule documented by the function that checks it (in its
# Errorsor# Panics) isIllegalwhen broken; - a rule set elsewhere, which this function only enforces, is
Policy.
So the checking function reports Illegal, because the rule is its own.
The code that read the config from outside the program is an input
boundary, and it re-marks what comes back with as_policy. A handful of
boundaries do this: loaders, command-line parsers, deserializers. The
alternative would be to make every check guess where its input came from.
Rules also move. A policy that becomes part of an API’s documented contract
turns Illegal, and a refusal that turns out to mean “not yet” turns
Unavailable. Pick the kind that is true today. Re-marking exists because
the answer depends on the caller.
One line, then the evidence
A message is one line, written for a person: what went wrong, naming the thing it went wrong with. Evidence goes in the details: the values that differ, the config that was rejected, the shards that are missing. Details print only in the report.
This split keeps log lines readable and test expectations stable. A
{:#?} dump in a message breaks both.
Put facts in causes
A fact that a program may want to read belongs in a typed cause, not only in the text:
- A check that a value breaks is a
ConstraintError: the owner, the field, and theRule. - A name that is not in a table is a
LookupError, with the names there are. The four “no such X; there are: …” messages in the crate all come from it. - Text that did not parse is a
ParseError, and the site chooses the kind by where the text came from: outside data givesInvalidResource, a request givesPolicy, and the program’s own text givesIllegal. - A foreign error stays the cause. Do not format it into the message. An
io::Errorgoes throughsys_at, which also names the path. There is deliberately noFrom<io::Error>, because a bare?could not say which file failed.
A subsystem with failures of its own that a caller may act on defines its own cause type. The complex handlers chapter covers that.
Add context; do not re-wrap
A function that calls another and passes its error up adds a frame with
ResultContext. It never rebuilds the
error with a longer message. Rebuilding loses the kind, unless every
variant is copied by hand, and loses the cause in any case. A specialist
further up then cannot find what it is looking for.
Document it, and test it
A try_x function’s # Errors section names each kind it returns and when,
and the cause type where a caller may want it.
STYLE.md
sets the rule. Its x twin panics with the report.
Each kind a function documents gets a test that names it, with
ErrorMatcher: the kind, plus the
one phrase or cause field the test is about.
Complex handlers
Most code handles an error by its kind alone (Consuming errors). Some code has a recovery strategy of its own, and needs facts that the kind does not carry. The disk cache, for example, decides between retrying a URL and moving to the next mirror. This chapter is about that code.
Kind and cause together
A specialist reads two things:
- the kind, which it shares with every other consumer;
- a cause type it knows, which it reaches with
find.findwalks the cause chain and returns the first error of the requested type.
The kind keeps the ontology small. Generic consumers never see a subsystem’s cause types, so a subsystem can define them freely without growing the set of kinds everyone has to handle. The cause gives the specialist a precise vocabulary that only it reads.
The cache’s mirror loop
The cache fetches a file from one or more URLs. Each failure is a
BunsenError whose cause is the cache’s own
FetchFailure, and the loop reads kind
and cause together:
- An
Unavailablefailure, such as a timeout, a server error or a truncated transfer, retries the same URL, within the cache’s retry budget, and waits as long as aRetry-Afterheader asked. - A
Lookupfailure means the URL is missing or forbidden. The loop moves to the next mirror. - A download whose digest does not match the pin is
InvalidResourceto everyone else. To the cache, its cause says “this mirror served the wrong bytes”, and the loop moves to the next mirror instead of retrying the same one. - Anything else, such as
PolicyorSys, stops the loop. No other mirror would help.
If every mirror fails, the loop returns one error that holds each mirror’s
error, labelled by URL. Outside the cache, a consumer sees only the kind of
that aggregate: it is Unavailable only if every mirror was unavailable, so
a generic retry happens only when a retry could help.
Defining a cause type
A subsystem that needs this kind of handling defines a cause type next to the code that uses it:
- It owns its kind mapping. It provides
From<Cause> for BunsenError, which picks the kind from the variant in one place. A site cannot then build an error whose kind and cause disagree, and?works. - It prints once. The
Fromimpl builds the error withfrom_cause, so the cause’s text becomes the message and is not repeated in the report. A cause with more to say than one line implementsDetailed. - It is public,
#[non_exhaustive], and documented in the# Errorssections of the functions that return it, so callers can find it.
The shared cause types in bunsen::errors, such as
LookupError and
DigestMismatch, follow the same rules.
Aggregates
A batch reports its failures as one error with a
Multiple cause, whose members are the
BunsenErrors themselves, each labelled. The aggregate’s kind is derived
from the members. A specialist reads each member’s kind and cause, for
example to retry only the parts of a batch that can succeed.
Keep the chain intact
find sees only what is still a typed error. Text loses it:
- formatting an error into a new message, instead of adding a frame;
- joining a list of errors into one string, instead of using
Multiple; - sending an error across a thread as a
String.BunsenErrorisClone, shared behind anArc, so send the error itself.
One boundary cannot be helped. A serde (de)serializer accepts only a message for its own error type, so an error that crosses serde arrives as text.
find matches type identity: a cause type from a second,
semver-incompatible copy of bunsen in the same build is a different type,
and is not found.
Run containers
A long-running service, or one that loads and runs graphs dynamically, calls
the try_x half of bunsen’s operations, and treats Illegal and Internal
as the failure of one job, not the process: it logs the report and moves on.
To contain the panics of code that does panic, it wraps the job in a
catch_unwind boundary and turns the panic into an Illegal error, with the
panic text as its message. Re-marking applies at that boundary like any
other. The container knows whether a job’s input came from outside, and
re-marks accordingly.
Shape contracts
A shape contract is a runtime check of a tensor’s shape against a pattern
that reads like the shape in the docs. This chapter explains why bunsen
checks shapes this way, where contracts go, how to choose what a check
costs, and how to read a failure. The pattern language, the solver and the
macros are documented in bunsen::contracts.
Why contracts
Shape errors in tensor code are hard to diagnose. A reshape that almost
works produces a tensor with the wrong meaning, not an error. An off-by-one
in a transpose silently swaps two axes. The eventual failure, a matmul
panic three layers later or a loss that won’t go down, points at a symptom,
not the cause.
A contract writes the expected shape down, in code, at the boundary where one piece of code hands a tensor to another. It is used in one of two ways:
- Assert: does this shape match the pattern? If not, fail with a message that says which dimension broke.
- Unpack: the shape matches, so return the named dimension sizes the function needs for its arithmetic and reshapes.
Unpacking asserts too: the same pass that checks the pattern solves for the
names the caller asked for. This removes a familiar kind of drift. Ad-hoc
code checks dims()[1] % window == 0 in one line and computes
dims()[1] / window in the next, and the two can disagree. With a contract,
the check and the values come from one declaration.
Contracts read like the docs
STYLE.md writes a tensor shape in rustdoc as one code span in square
brackets, such as [batch, h_wins*size, w_wins*size, channels]. A contract
for that tensor uses the same names and the same arithmetic, one term per
dimension. A reader can then check the docs against the code at a glance,
and the contract enforces what the docs promise.
The module docs have a
compiled example of the correspondence.
A contract’s names are its own: "batch" in one function has nothing to do
with "batch" in another. What makes a contract readable is matching the
docstring next to it.
Where contracts go
The natural home is a function or module boundary. The usual pattern has three steps:
- Unpack the inputs at the top of the function. You needed the dimensions anyway, and the check comes with them.
- Do the work in terms of the unpacked names.
- Assert the shapes of outputs or intermediates that the function promises but does not otherwise read, usually periodically.
Pass a tensor’s shape as &x.dims(), which the check borrows, rather than
&x, which copies the shape on every call
(passing shapes). The solver walks the
shape left to right and can solve for one unknown per dimension, so a
dimension like "h_wins" * "window" needs window bound by the caller or
by an earlier term (matching).
Choosing a cost model
Contracts are meant to stay on in release builds. A contract that is too
slow to leave on only catches the bugs its author already hit in tests. The
pattern is parsed at compile time and kept in a static, so a check is one
pass over the dimensions, but it still does some work: it allocates a small
scratch vector, and it formats a message on failure. The
cost section has the benchmark command and
indicative numbers.
When a check sits on a hot path, there are two ways to lower its cost, and a function often uses both:
| Strategy | Debug builds | Release builds | Use when |
|---|---|---|---|
assert_shape_contract! / unpack_shape_contract! | every call | every call | The path is cold or runs once per batch, or you want the failure in production. |
assert_shape_contract_periodically! | sampled | sampled | The path is hot, but you still want some coverage in production. |
Either, under #[cfg(debug_assertions)] | as above | removed | The check is a developer aid only, or you measured a cost you can’t afford. |
The periodic form runs the first few calls, then doubles the gap between
checks until it reaches one call in a thousand. The schedule is per call
site
(run_periodically!). An unpack
cannot be sampled, because the function needs its values on every call.
Sample the asserts on intermediates and outputs instead.
The default is no #[cfg]. Reach for #[cfg(debug_assertions)] only after
measuring, or when the check guards against mistakes that a release build
cannot make. When you do gate a check:
- Gate the whole chain. The names a gated unpack binds exist only in debug builds, so every check that uses them must be gated too. The compiler enforces this, which is useful: it tells you when release code depends on a debug-only binding.
- Periodic and gated combine. A periodic assert inside a gated block still keeps debug builds and test runs fast.
next_interior_3d is a
small example: a gated unpack of its input and a gated periodic assert of
its shrunken output. The ResNet blocks, such as
LayerBlock::forward,
use the same pattern.
Reading a failure
A failure message opens with the code that called the check. The next line
names the first dimension that failed, the pattern term it failed against,
and why. Then come the actual shape, the whole contract, and every value
bound when the match stopped, including the values the match itself bound on
the way. Read the failing term first, then the bindings: they show what the
solver believed when it gave up.
ShapeContract’s error messages
describe each part and each reason.
All the macros panic on a mismatch. To get the failure as a value, for
example to report a bad input as an error, define the contract with
shape_contract! and call
try_unpack_shape or
try_assert_shape.
Their # Errors sections say what they report, and try_unpack_shape’s
# Panics says what still panics.
Reference
- How the types relate and macros and methods: the module overview.
- The pattern language: terms, labels, params, constants and the grammar.
- Matching: the solver’s rules.
ShapeView: every accepted shape form and what each one costs.
Ops, blocks and burn extensions
bunsen’s reusable tensor code lives in three places:
bunsen::ops, bunsen::blocks, and the
tensor extension traits in bunsen::burner::tensor.
This chapter explains how they divide the work, so that you know where to
look for something and where new code belongs. Each module’s own docs carry
its map: ops,
blocks.
The rule: what a thing is for
- Blocks are
torch.nn-like components, meant to be used asModuleroots or as parts of a module tree. - Ops are operation-focused. They may use the
ModuleandConfigmachinery, but only to hold cached tables or state.
The rule asks what a type is for, not whether it owns parameters or is a
pure function. SlidingStft is
a Module that holds a fixed analysis window and learns nothing.
DropPath owns no
parameters but sits in a model as a layer.
KVCache is a Module over
a bare tensor that holds per-decode state. Asking “would you put this in a
module tree as a layer?” places each of these exactly once: DropPath is a
block, and the STFT and the cache are ops.
The dependency runs one way: blocks import ops, and ops never import blocks.
A block is typically “these parameters, plus these ops, called in order”.
For example, DropBlock2d
holds its settings and calls
drop_block_2d while training. Keeping
the operation separate means the math is tested on its own, and the block’s
tests only have to show that it is wired correctly.
The rule is defined in bunsen::ops.
Caches and stream state are ops
Cache and stream state is injected. The caller builds it and passes it in,
and the model never owns it, so one model can serve several caches or
streams in one process. That is why KVCache is an op, not a block, even
though attention blocks use it:
CausalSelfAttention::forward
takes the cache as an argument and does not hold it. The same split, an
immutable module plus a per-stream context, runs through the signal front
ends and the speech kits. Stateless modules and streaming
contexts covers the pattern.
Ops or extension methods
Two places hold tensor helpers, and the split is about how the helper reads at the call site:
burner::tensorholds extension traits: small, general methods that read as if they were burn’s own, such ascount_dim,in_rangeorreplace_with.bunsen::preludebrings them into scope.opsholds free functions: operations you would name as a step in a model, often with settings of their own, such asdrop_path,scaled_dot_product_attentionorrepeat_interleave.
Value objects as configuration
When an op has settings worth naming, they form one small value object: cloneable, comparable and serializable. That value is the unit of configuration. A config embeds it as a field rather than copying its fields, and passes it straight to the op. The in-tree chain nests four deep:
ClampOp ⊂ NoiseConfig ⊂ DropBlockOptions ⊂ DropBlock2dConfig
ClampOp is an optional min and max.
NoiseConfig is a distribution plus an
optional clamp.
DropBlockOptions holds the
DropBlock settings plus an optional noise fill. And
DropBlock2dConfig’s
one field is a DropBlockOptions.
The payoff is that a setting added to an op reaches every config that
embeds it, with no fields to keep in sync, and the whole chain is saved with
the config. The implementation styles and names are mixed today (*Op,
*Config, *Options); the
module docs list which is which.
Where blocks come from
blocks is a curated catalog, not a comprehensive one. A block lands there
in one of three ways:
- A port of a known layer from a paper or a reference library, kept in
burn form so that every kit can use it.
DropBlock2dandDropPathare the DropBlock and stochastic-depth regularizers, the latter aftertimm’s. - A part shared by kits. A layer that a second kit needs moves out of
the first one.
ConvBlock1dandConvSeq1dserve both Whisper and Silero VAD, andTransformerMlpserves both Whisper and NanoChat. The language models share their ends:LmHead(tied or its own, with an optional logit soft-cap) serves Qwen3, Gemma, NanoChat and Voxtral, andTokenEmbedding(with an optional scale) serves Gemma and NanoChat. - A gap in burn. burn ships a sequence-level
Lstm.FusedLstmis what a streaming model needs instead: one step at a time, with the caller carrying the state. And burn’s activation kinds have no SiLU and no way to compose two:BunsenActivationConfigkeeps burn’s kinds under burn’s names, and addsSilu,PowandChain(NanoChat’srelu(x)²isChain([Relu, Pow(2)])).
New blocks arrive when a kit or a downstream user needs them, and each one follows the module design conventions.
Two attention stacks
bunsen has two attention stacks, and both are deliberate:
- bunsen’s own
CausalSelfAttentionblock (the NanoChat, Qwen3 and Gemma language kits) has its own projections, QK-norm, rotary embeddings and grouped-query attention, with the options those families differ by: a score scale, an attention logit soft-cap, a sliding window, and each layer’s rotary table from the stack’sRotarySet(Gemma 3’s local and global tables). Use it for a decoder-only model whose layers you define. - Functions over burn’s
MultiHeadAttention(the Whisper kit) keep burn’s module, so its weights, its checkpoint loading and any cross-checks are unchanged, and add KV-cached decoding, cross-attention included. Use them when the model is built on burn’s module: a ported checkpoint in that layout, or encoder-decoder cross-attention.
Both decode through one
KVCache, which a model
hands out sized for itself.
An encoder’s attention decodes nothing, so it carries no cache.
CausalSelfAttention
with a bidirectional
AttentionMask
is one (every key seen, padding keys masked, rotary embeddings kept);
RelPosSelfAttention
(the Conformer’s) is a block of its own.
The ops attention docs
say when to use which, and
the cache describes
KVCache.
Data: from files to models
This section covers how a name such as tiny, hf:openai/whisper-tiny or
fineweb-edu-100b-shuffle becomes a loaded model or a set of training
files: what a name means, who answers it, where the files land, and why
bunsen trusts them once they are there. The reference is
bunsen::data, whose lifecycle diagram links
every step.
bunsen::data is split along what each part is about, each built on the
one before:
| Module | What it holds | Chapter |
|---|---|---|
cache | the disk cache: where files land, digests, links, downloads | Resources and the cache |
resources | pinned files, the places they come from, the resource cache, the Hub client | Resources and the cache |
catalog | what there is to build, as data: a layered catalog of contracts, builds, resources, tags and presets | The catalog |
formats | reading the files: safetensors, PyTorch, MLX, the Phonon formats | Formats |
builds | a name to a model: providers, the factory, the kit’s hook | Loading builds |
pretrained | the kits’ prefabs, geometries by name | Loading builds |
datasets | dataset shard sets | Datasets |
The kits show three sizes of the same machinery.
default_resnet_factory
is the simple case: the catalog’s torchvision and timm checkpoints.
default_whisper_factory
is the full one: the catalog’s builds, and Hugging Face repos.
default_silero_factory
is the smallest: one build, upstream’s 16 kHz checkpoint.
The pathway
spec ("tiny", "hf:org/repo")
│ the kit's factory asks its providers
▼
build: what the catalog says the model is, and its resources
│ paired with the kit's hook, optionally overlaid
▼
deferred model
│ plan, bring the files local through the cache, construct
▼
loaded model, behind an Arc
A BuildFactory is the one object a
caller holds for a kit, and its
load runs the whole pathway. A
file on disk does not go through the factory at all: it is a given resource
set (ResourceSet::given),
loaded the same way from the deferred step on. A dataset takes a shorter
path: its build is a shard set, which a data loader reads
(Datasets).
The operational view
bunsen-tool shows the machinery from the outside. bunsen-tool catalog
reads, checks and queries the catalog. Each family’s list shows its
builds, their presets, and where each one’s files stand, and its fetch
brings a model’s resources local. Every --model takes a lookup expression,
and --preset adds to its box; a name no provider has fails with the names
nearest it, as “did you mean?”; bunsen-tool asr family whisper inspect
checks a checkpoint against the geometry its build states, and
bunsen-tool asr family whisper prefabs lists the geometries;
bunsen-tool cache lists and clears what the cache holds. Its
README
explains Whisper’s builds.
Resources and the cache
A Resource is one file: the slot a
kit reads it by (checkpoint, vocabulary), the file name it lands as, the
SHA-256 that pins it, its format, its full name, and the
Sources it can be had from, in order. A
ResourceSet is a named set of them,
what a loader reads, and two sets
fuse by slot: strictly for
authoring, where a repeated slot is a mistake, or as an overlay, where the
right-hand set wins. None of this is about models: a model’s build and a
dataset’s shards both load through it
(bunsen::data::resources).
The cache and its trust model
A ResourceCache keeps each
pinned file at <cache>/resources/<name>/<sha256>/<file>. The name is the
resource’s full name: a catalog resource’s (qwen/qwen3/qwen3-0.6b/checkpoint),
so a file two builds share is cached once; an hf: repo’s
(hf/<org>/<repo>/<slot>); given for a path’s. The digest in the path is
the pin. A file there was verified when it was written, so later runs
trust it without re-hashing gigabytes, and a model whose pin changes can
never collide with a stale copy. The cache trusts the path whoever wrote it:
a download, bundled bytes, or a build script or a deployment that laid the
directory out ahead of time
(trust model).
The cache looks at that path first, then at a resource’s local sources, and
only then at its URLs
(source order). A
local directory, such as openai-whisper’s own cache, is a “trust me”
source: its file is used in place and hashed only when the cache’s options
ask for verification. Nothing is linked or copied into the cache, and only
a download or bundled bytes write there. Downloads need the fetch feature.
Without it, or on an offline cache, a file that only a URL can supply is
reported as not found (features).
Bundling is a populated cache directory
Because the cache trusts its layout, shipping a model with a build does not
need a special kind of source. It needs a cache directory that is already
full. bind-whisper-onnx,
the Whisper validation crate’s asset crate, fetches Whisper’s base files
at build time into its build directory, laid out as a cache, and a
ResourceCache rooted there finds them without knowing they were bundled.
An offline deployment does the same thing at install time: fill a cache
directory ahead of time, and point the cache at it. Files a deployment ships
in place are a catalog layer instead, which adds them to their builds as
local-dir sources (extension layers).
The other form links the bytes into the binary: a
Source::Bundled, checked
against its digest and written into the cache on first use. Both forms are
described under
the cache and bundles.
The Hub
resources::hub is what a client of the
Hugging Face Hub needs to name its files: a
HubRepo at a revision, a model’s
or a dataset’s, the URLs it serves a file and its tree listing at, and the
listing’s entries, whose LFS digests pin the files. The hf: provider reads
a repo’s listing through the cache, and cargo catalog pins the catalog’s
Hub files from the same listings.
The Hub may be mirrored. A mirror is a build of the hf-mirror contract,
which states the origin that serves the Hub’s paths, and a catalog’s mirror
set is its hf-mirror builds in the catalog’s order: the built-in catalog’s
hub layer declares huggingface/hub, the Hub itself, and a layer above can
add more. Every Hub fetch tries them in order: a catalog build’s $hub files
and an hf: repo’s files and listing each carry one URL per mirror, and the
cache moves to the next when one is unreachable, lacks the file or serves the
wrong bytes. A file is pinned and cached the same whichever mirror served it.
The catalog
The catalog is what bunsen can build, as data: a stack of YAML layers that
name contracts, builds, resources, tags and presets, imported one after
another into one materialized state. The reference is
bunsen::data::catalog: its
format describes the document and
the stack, and its usage guide the API, from
importing layers to choosing a build.
Entries
Every entry has a full name, a /-separated path (qwen/qwen3/qwen3-0.6b),
and a kind:
- a contract is the interface a loader implements: the resource slots it
reads, each with the formats it accepts, and the argument slots it is
told. A kit’s contract is its own
contract.yml, gathered into the base layer’s$contracts; a dataset contract, such asparquet-shards, isdata::datasets’. - a build is one thing a loader builds: a model, or a data source. It names its contract, binds the contract’s slots to resources and arguments (a stated geometry, for a kit whose weights carry none), and carries its tags and presets. A template class is what builds of one family share, and a build’s presets fold down its chain.
- a resource is one artifact: a file, a sharded checkpoint (its index
and shards), or a templated set of numbered files, a dataset’s shards. Its
sources are places (
$hub,$base_url,$local_dir) or URLs. - namespaces, facets and releases group builds: a publisher, a family, a release sequence. Tags and axes are declared once, in the base layer, and builds state them; a tag’s declaration is its type.
Names are looked up by shorter spellings too (qwen3-0.6b), and an alias
is another name for one entry. A Hugging Face repo that no catalog names is
a build under the reserved root hf (hf/openai/whisper-tiny), whose names
keep the Hub’s spelling.
The built-in catalog
The catalog bunsen ships is
bunsen-catalog:
the prelude (the vocabulary and the contracts), the commons (the
publishers), the Hub’s mirrors, the datasets, and a layer per kit, each with the bunsen feature
it needs. BuiltinCatalog::get
imports and resolves it once in a process; its
build is what a name
means, and its provider
is a kit’s catalog: provider.
The layers are built, not hand-written. cargo catalog, in the validation
workspace, reads each layer’s source under
validation/catalog_builder/probe_contracts/, pins every file from its
remote (an LFS digest from the Hub’s listing, a small file hashed as it is
fetched), runs the probes a source names over a model’s files to fill its
presets, and writes the built layers. cargo catalog check fails when the
checked-in catalog is not what the sources build.
Presets
A build’s presets are named, described
merge patches over the config its kit builds
the model under: a Whisper policy, a Sortformer streaming setup, a Qwen3
generation policy
(PresetEntry). Which fields
a preset may set is the config’s business. A field the construction reads
changes what is built, and one a driver reads changes how it runs.
A build’s ResolvedPresetSet
groups them. An axis holds presets that exclude one another, such as
Whisper’s task (transcribe, translate) or Sortformer’s latency; a
selection names at most one member of each. The default selection is
explicit: each axis has a default member, and the set names the presets on
no axis that apply by default, so the build’s config with nothing selected is
its config under the default presets. A common patch holds what every
selection keeps, such as the stop tokens a checkpoint’s
generation_config.json names.
Resolution stacks the layers, each a patch over the one before
(resolve_presets):
- the family’s config, serialized;
- the set’s
commonpatch; - the default presets, except where the selection names another member of the same axis;
- the selected presets, as one layer: two that set the same path are an error, so their order never matters;
- the lookup expression’s patch.
Every layer is checked against the config it patches, so a misspelled field
fails, naming the preset or the patch, and the result must deserialize as
the config. A kit’s hook resolves presets before it builds, and
BuildFactory::resolve_presets
resolves a build’s config with nothing fetched or built.
A catalog states presets once per template class, and its builds inherit
them under their own. An hf: repo that no build describes gets its
template class’s. Some presets are read from a model’s own files: a source
names probes, such as one that reads generation_config.json, and cargo catalog runs them when it builds the catalog, so a build’s presets are
fixed data and need no probing when the model loads. A probe may read a
token by name: Gemma’s instruction-tuned builds read the id
tokenizer_config.json gives <end_of_turn> into their stop tokens. A chat
model’s template is a preset field too (generation.chat_template): a file
of the checkpoint’s, which the chat_template probe finds, or a template’s
source.
What a build’s probes find accumulates: two probes’ stop ids join. The
hand-written layers are merge patches, which replace. The build’s own
presets lay over what its probes found, and the family’s lie under the
build’s. Then a lookup lays its selected presets (--preset too) over the
build’s, and last its own patch, name{generation: {stop_ids: [1]}}.
bunsen-tool catalog resolve <build> prints a build’s preset set, and
bunsen-tool summary each build’s axes, their defaults starred.
Choosing a build
The catalog also chooses among builds: a selection is a pipeline of stages
over the builds a command may pick from, which keep, weigh and order them by
their tags (select). bunsen-tool chat’s
--model, --keep and --weigh are stages, and --think is a shortcut
into a build’s presets: it keeps only the builds that can think, and selects
the preset that makes them.
Extension layers
A stack takes layers beyond the built-in ones. A later layer may declare new
entries, or meet an existing one by its $merge: update adds to a
namespace, retargets an alias, or adds sources to a resource, tried first;
replace substitutes an entry. A build is reached as a scope: an extending
build occurrence carries only its kind and children, so a layer can add a
source to a resource the build declares.
That is how a deployment ships its files: a layer that updates its builds’
resources with local-dir sources, so the same name loads from the shipped
files. whisper-model-validation builds its bundle’s layer that way, and
loads openai/whisper/base through two factories, with the layer and
without it.
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 byPrefabs. - 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.
Formats
A kit’s hook reads its checkpoint’s own format with the readers in
bunsen::data::formats: the safetensors checkpoint and header
(SafetensorsCheckpoint),
the PyTorch reader, MLX’s affine-quantized tensors, FermionResearch’s
Phonon formats, and named-tensor application, which loads any of them into
a module under a kit’s names, or under a
Rekey whose targets may also change a
tensor’s data on the way. The readers need the store feature
(features).
A LoadPolicy is the load call’s
choice of the float dtype a model’s parameters are placed in. A load only
ever widens: a tensor goes in the dtype it was stored in, or f32, the first
the policy, the device and the hook allow. performance() keeps a half
dtype only where the device accelerates it, as_stored() wherever the
device computes in it, and at_least(f32) holds a model to an f32
reference.
PyTorch checkpoints
An OpenAI .pt checkpoint is read through burn-store’s PyTorch reader, and
a Hugging Face safetensors repo through its safetensors reader. The PyTorch
reader honours each tensor’s strides, so a weight that PyTorch saved as a
transposed view of another tensor loads as the weight it is.
Datasets
A language model trains on a corpus too large to fetch at once, published as
many numbered files. This chapter covers how bunsen names, pins and fetches
those files, and where they go next. The reference is
bunsen::data::datasets, whose
lifecycle links every step.
The pathway
a catalog build a dataset, a templated resource of numbered files
│ view it, select a range of shards
▼
ShardSet the set, bound to a directory
│ locate / fetch / fetch_many
▼
shard paths
│
▼
a data loader bunsen-arrow-dataloaders, in train-chat
A ShardSetDescriptor says
what a set is: its name, the base URLs its files come from, how they are
named and numbered, and whether they are pinned. It is plain data, a view of
a catalog build of a dataset contract (parquet-shards), whose shards are
one templated resource; NanoChat’s corpus
is the built-in catalog’s karpathy/fineweb-edu-100b-shuffle
(from_builtin). A
ShardSet binds a descriptor to a
directory, the disk cache’s or one the caller gives, and brings shards in.
Binding needs the cache feature; downloading needs fetch. Without
fetch, a set works from shards that are already on disk.
Pinned shards
A pinned set carries one SHA-256 per shard, and a fetch verifies each file
as its bytes land. The pins are generated, not typed: cargo catalog reads
the dataset’s file listing at a pinned revision of its Hugging Face
repository and lists each shard’s digest in the build’s resource, and the
descriptor’s base URL resolves that same revision. The files and their
digests therefore can’t drift apart.
bunsen stops at paths
bunsen’s part ends with a list of local paths. Reading them is a data
loader’s job, and the loader that reads NanoChat’s Parquet shards is a
separate crate,
bunsen_arrow_dataloaders, a preview that does
not depend on bunsen. Its
ChatDataLoader
streams the shards through text selection, tokenization and packing into
fixed-shape blocks of token ids, with an optional shuffle
(pipeline overview).
A selection of shards can also become a
ResourceSet, through
to_resource_set,
for a build or a loader that takes the shards as resources.
End to end: train-chat
examples/train-chat
joins the two halves. Its command line selects shards of NanoChat’s corpus
and a fetch policy, it fetches the selection through a ShardSet, splits the
paths into training and validation, and hands each part to a
ChatDataLoader. The shard-selection arguments come from the bunsen-app
dev crate, and the loader crate’s own dl-test example uses the same ones.
Stateless modules and streaming contexts
This chapter covers how bunsen keeps state that changes as data arrives: a decoder’s key/value cache, an audio front end’s leftover samples, a recurrent model’s hidden state, a transcription in progress. It opens with the principle behind all of them, then the pattern that follows from it, and ends with the Whisper stream driver, the largest system built on it.
The principle: state is injected
Cache and stream state is injected, never owned by the model. The rule
is defined in bunsen::ops: the model is
immutable once it is built or loaded, and the state of one stream or one
decode lives in a value the caller holds and passes in.
The payoff is that one model serves several streams, or several caches, in the same process. A server transcribes many streams with one copy of the weights. Several decodes run at once over one model, each with a cache of its own. A batch of decodes from different streams runs through the model together. None of that works if the model holds a stream’s state in its own fields, because then the model is the stream.
The rule also decides where code lives: a cache or a stream context is an op, not a block, even when blocks use it (Ops, blocks and burn extensions).
The pattern
Each stateful system splits three ways, as
bunsen::ops::signal
spells out for the audio front ends:
- A config, which builds the module.
- An immutable module: the weights, or fixed tables such as an analysis window or a mel filterbank. Fixed tables are bare tensors, so they move with the module but are not recorded (module design conventions).
- A context or cache per stream or per decode, made by the caller and passed back in on every call.
The pairs in the tree:
SlidingStftandSlidingStftContext: an STFT over a stream of samples.PerceptiveAudioConverterandPerceptiveAudioConversionContext: waveform to log-mel, Whisper’s front end.CausalSelfAttentionandKVCache: one multi-layer cache per decode, shared by every layer of the model (decode modes).GatedDeltaNetandDeltaNetState: a linear-attention layer’s carried state, its convolution’s last inputs and its delta rule’s matrix. A hybrid model (Qwen3.5) decodes through aDecoderStackCachethat holds both kinds, a KV cache for its attention layers and aDeltaNetCachefor its linear ones. Unlike a KV history the state summarizes the whole prefix: it cannot rewind, only reset.SileroVadandSileroVadContext: the recurrent state and the tail of the last chunk (streams).WhisperStreamDriverandWhisperStreamContext: a whole transcription, including the front-end and voice-activity contexts of one stream.
The speech kits’ table of pairs adds Whisper’s text-decoder cache.
Chunking must not be observable
A context’s job is to carry what a stream has not finished with, so that feeding audio in chunks gives the same result as one call over the whole signal. With the log-mel context, for example, hop-aligned chunks produce exactly the frames one call would. This guarantee shapes the APIs. Whisper’s “keep 8 dB below the maximum” clamp is a step the caller applies to a finished spectrogram, not an option on the converter: a clamp relative to a maximum reduces over whatever it is given, so inside a streaming converter it would make the chunking visible (why).
Constructor names vary
The pattern is consistent, but the names of the methods that open a context
are not, yet. A context comes from
SlidingStft::init_state,
PerceptiveAudioConverter::new_context,
WhisperStreamDriver::new_context,
KVCacheModel::new_kv_cache (a model’s),
KVCacheConfig::init
(which takes no device), or
SileroVadContextConfig::init
(which takes the model it serves). Look on the module first, then on a
context config.
The Whisper stream driver
The Whisper driver turns audio written in chunks into timed transcript
events. It is the principle applied at the scale of a whole pipeline, and
its design is documented in whisper::driver.
Most of it does not depend on Whisper. The buffering, the voice-activity
gate, the decision of when to decode and what to commit, the clock and the
batching live in asr_driver, and a
model plugs in as an AsrEngine:
its streaming features, the decode of one window, and its text. Whisper is one
engine;
Qwen3AsrEngine is
another, driven by a
Qwen3AsrStreamDriver
under the same policies. Qwen3-ASR has no timestamps, so it commits each
window whole.
ParakeetEngine is a
third: its transducer times every token, so a window cut at its full length
commits up to a pause between words, and the rest is decoded again with the
audio after it.
Driver and context
A transcription splits in two. The
WhisperStreamDriver
is the shared, immutable half: the model and its token layout, the mel
front end, the logit filters, the decode settings, and the voice-activity
model if one is attached. A
WhisperStreamContext
is one stream in progress, and it is the only stateful type: the front
end’s carry, the frames not yet decoded, the committed transcript, the
stream’s clock, its level and its voice-activity state. One driver
serves any number of contexts, and
AsrStreamDriver::advance_ready
batches the decodes of many contexts through the one model
(driver and context).
One driver, three deployments
The driver serves three deployments, and it is configured for each, never
forked: server-batch offline inference; conservative real time, for a
program that consumes the transcript; and best-effort real time, for a
person reading along during the utterance. The three
EmissionModes of an
EmissionPolicy are
those three deployments.
The write_read fold
write_read
has two halves. write takes samples in any buffer size, moves whole hops
through the mel front end, and runs the voice-activity model. read runs
every decode the emission policy says is due. They are separate so that a
batch of streams can be written one at a time and then read together.
No decode state crosses a window boundary: each decode opens its own text-decoder cache. What carries from one window to the next is host-side: the seek pointer, the prompt carry, the detected language and the clock (the fold).
Emission: commit and draft
The policy has two axes: DecodeTriggers,
which says when a decode runs, and a
CommitRule, which
says when its output is final. A decode triggered by a full window or by
the end of a speech region commits. A decode triggered by the interval
timer drafts.
Drafts are opt-in, per policy. offline never drafts. conservative
drafts only the unfinished tail of a timestamped decode, before that tail
is decoded again with more audio. drafting adds a draft every 600 ms of
speech. A consumer that wants final text only keeps the
Committed
events. A draft covers the audio after the last commit and replaces the
previous draft whole, so there is no retraction protocol.
A draft is the same decode as a commit, not a second code path. A decode
reads the context through &self, and only a commit moves the stream, so
drafting commits exactly what conservative commits on the same audio.
That holds with language detection too: only a commit fixes a stream’s
language
(what a decode may touch).
The preset table
lists each preset’s triggers, commit rule and drafts.
The stream clock
Every context carries a
StreamClock: anchors
that map a sample index to media time. A bare stream gets one anchor at
zero, which reproduces upstream’s arithmetic exactly. A capture timestamp, a
container’s presentation time, or a dropped buffer is one more anchor. The
bare case is the general case with one anchor, so the general case costs
nothing extra
(the stream clock).
The level is the stream’s policy
Whisper floors its log-mels a fixed distance below a reference maximum, and
upstream takes that maximum over the whole clip. A stream cannot see the
whole clip, so where the reference comes from is the stream’s
LevelPolicy, given to
each context when it opens and shared by every model on the driver core.
The context offers every new frame to its level, and asks it for a reference
just before a window is packaged.
Running
gives upstream’s whole-clip behaviour, a running maximum, or a per-region
one, depending on how the context is fed.
PerWindow
floors each window on its own. What the level summarizes is the model’s:
Whisper’s is a maximum
(MaxLevel)
(the level).
Voice-activity regions as sub-streams
The real-time emission modes decode at the end of each speech region, so they need
a voice-activity model, attached with
with_vad.
Each stream then runs Silero in a Silero context of its own. A
VoiceActivityFilterConfig
turns Silero’s probabilities into
SpeechRegions.
A closed region is decoded as a unit of its own, with times taken off the
parent stream’s clock, and a full window of silence is skipped instead of
decoded. That gives a region the behaviour of a stream without a second
stream object
(regions as sub-streams).
Speakers
A driver can carry a diarizer as well as a voice-activity model, attached
with
with_speakers.
The driver knows it only as a
SpeakerActivityModel,
per-frame speaker probabilities, so any diarizer serves any engine. Each
stream runs it in a stream of its own, and every segment the driver emits is
attributed to a speaker by a
SpeakerAttribution
rule, such as NeMo’s
MeanActivity.
A diarizer finalizes a frame only after some look-ahead, so a unit is
decoded only once the diarizer has finalized all of its audio: its commits
are attributed from final activity, and an engine that reads the activity
sees all of it, however the audio was chunked. A draft is attributed from
what the diarizer has finalized so far. The engine sees the window’s activity
in its decode request, and one that decodes windows whole cuts them at a
change of speaker first
(SpeakerCutConfig::cut), so a
window is one speaker’s as far as the turns go. Turns on their own, without transcription, come from a
TurnFilter over the
diarizer’s activity.
Known gaps
CommitRule::Agreementis not implemented yet: building a driver under it fails with anUnsupportederror.- The
intervaltrigger drafts only while the voice-activity gate says speech is in progress, and that gate runs only underendpoint(DecodeTriggers), so a driver withintervaland withoutendpointfails to build.
Parameter groups
Training recipes often step different parts of a model differently. bunsen
handles this in two pieces that compose. Reflection selects parameters by
where they sit in the model, and the group optimizers step each selection
with its own optimizer and learning rate. This chapter explains how the two
fit together and where they bite. The reference is
bunsen::burner::module::reflection
and bunsen::burner::optim.
Why
A burn optimizer steps every parameter of a module with one rule. Real recipes want more than that:
- 2-D weight matrices train well with Muon, while embeddings, norms and biases are better served by AdamW;
- some groups want their own learning rates: the NanoChat recipe scales the
lm_headand embedding rates separately; - some groups want their own weight decay or betas.
Grouping needs a way to name “every rank-2 weight under the transformer
blocks”. A burn module is a Rust type. It tells the compiler about its
sub-modules, but it has no structure you can query at run time, so without
help each grouping is a hand-written ModuleVisitor. Reflection builds that
structure once, as a document, and the groups are queries against it.
The model as an XML document
XmlModuleTree mirrors
a built module as an XML document, and you select from it with XPath.
The element name is the module’s type name, and the field name is the
@name attribute. A field gpt: NanoChatGpt is the element
<NanoChatGpt name="gpt">, and each parameter is a <Param> leaf with its
rank, shape and dtype as attributes. So “every rank-2 weight of a
Linear under the field h” is a short path:
*[@name='h']//Linear/*[@name='weight'][@rank=2]. A selection returns
burn ParamIds, which are what an optimizer group is made of.
The document covers the rest of the mapping (enums, containers, empty modules), and the XPath crib covers the few XPath forms you need.
The pattern
- Build an
XmlModuleTreeover the live module. - Select each group’s
ParamIds with a query, by structure. - Gather every parameter that no group claimed into a remnant group, and check that no group is empty.
- Wrap each set in an
OptimizerGroupwith its optimizer (any burn optimizer, such asAdamWConfig::new().build()) and, if it needs them, a learning-rate rule (LrSelector) and a gradient clipping. - Plan the module and the groups with
GroupOptimizerPlan::try_new. - Build burn’s
ModuleOptimizerwithplan.optimizer()and itsModuleLrSchedulerwithplan.lr_scheduler(schedule), and hand both to aLearner, or step them in your own loop.
Groups of any number of optimizer types go in one Vec: burn’s
ModuleOptimizer erases the type. The plan checks that the groups
partition the module’s float parameters. It rejects a parameter that two
groups claim
(DuplicateParamId),
so nothing is stepped twice, and a float parameter that no group claims
(UnassignedParamIds,
listing each one’s module path), so nothing is silently left out. To keep
parameters fixed on purpose, put them in a frozen group
(OptimizerGroup::frozen),
whose optimizer never moves them. A group’s learning rate is a function of
the scheduled rate, so one schedule drives every group and each group shapes
its own rate.
The module docs have a compiled example
(optim) and a full
lifecycle.
examples/train-chat
is the full-size case: ParamGroups::select carves a NanoChatGpt into
matrix, embedding, lm_head and remnant groups for Muon and three AdamW
groups, and a test checks that the groups partition the model.
Pitfalls
Element names are type names, not field names. A path that names a field
as an element matches nothing. In train-chat the field gpt holds a
NanoChatGpt, so the element is NanoChatGpt and its queries start
GptHost/NanoChatGpt/.... Queries that started GptHost/gpt/... would all
come back empty, every parameter would fall into the remnant group, and Muon
would never step a single weight. Nothing would fail: training would run,
with AdamW stepping everything at the remnant group’s settings. Select a field
with *[@name='gpt'], or its type with NanoChatGpt, never with gpt.
An empty selection is not an error. A query that matches nothing
returns an empty set, and the remnant group quietly absorbs the parameters
it was meant to claim, with the remnant’s settings. Renaming a field or a
type elsewhere in the model can do this to a query that used to work.
Assert that every group is non-empty. When a query comes back empty, print
the document with
to_xml and
read the names off it.
[a][b], not [a,b]. In XPath a comma builds a sequence, not a
conjunction. *[@name='weight', @rank=2] parses, so building the query
succeeds. It fails with a type error only when it is evaluated, and over an
empty selection it is never evaluated at all, so a wrong path in front of it
hides the mistake. Stack the predicates, [@name='weight'][@rank=2], or use
and (XPath crib).
The plan holds paths, not ids. Groups are selected by ParamId, but
the plan keys each group by the module paths of its parameters, such as
gpt.h.0.attn.c_q.weight. A model with the same structure is stepped the
same way, whatever its ids. A parameter at a path the plan doesn’t hold, such
as a head added under a new field after the plan was built, goes to the
fallback optimizer. By default that fallback panics at step, naming the
parameter’s rank and shape, rather than train part of the model in silence.
Plan the groups after surgery. An
UnknownParamPolicy of
Freeze accepts unclaimed parameters at try_new and leaves them unchanged
at step. To keep parameters fixed on purpose, use a frozen group instead.
Resuming builds the same plan over a fresh model. Ids persist across a
checkpoint: load_record gives each parameter the id saved in the record,
so a restored model has the saved run’s ids, not the ones it was built with.
The optimizer record saves each parameter’s state with its module path, and
loading it hands each state to the group that holds that path. So a resumed
run builds a fresh model and plans it the same way the first run did, then
loads the model record and the optimizer record; a Learner resuming from a
checkpoint does the loading for you. The scheduler’s record is matched by
position, so build the resumed scheduler from a plan with the same groups,
in the same order, over the same schedule
(resuming).
Firehose
bunsen-firehose is a column-oriented data pipeline for feeding burn
models, and bunsen-firehose-image is its set of image operators. This
chapter is orientation only; the crate docs are the reference:
bunsen_firehose and
bunsen_firehose_image.
A firehose pipeline is declared, not hand-wired. A
FirehoseTableSchema
lists typed columns, and a
BuildPlan says how a derived
column is computed from others by a named operator, built from a
serializable config. Planning a column checks the operator’s parameter
types against the schema, so a pipeline such as “load the image at this
path, resize it, augment it, turn it into tensor data” is checked when it
is put together, not when the first batch fails. An executor then runs each
batch of rows through the plans in dependency order.
Operators register themselves globally when their crate is linked, and
init_default_operator_environment
collects every registration. A crate publishes operators just by being a
dependency: that is how bunsen-firehose-image adds image
loading,
seeded augmentation and
conversion to tensor data. The bridge
to burn is
FirehoseExecutorBatcher,
a burn Batcher that runs the executor over each batch and hands the
tensors to burn’s data loader.
Firehose is independent of bunsen, so it works with any burn model. The
resnet_tiny
and swin_tiny
examples train image classifiers through the same firehose pipeline, and
are the place to see it end to end.
Development setup and CI
This page explains what a working checkout needs, what CI checks on every
pull request, and why it checks the same code in several configurations.
The steps themselves, what to install and which commands to run, are in
CONTRIBUTING.md,
the canonical contributor guide. This page doesn’t repeat them.
What a checkout needs
- Stable Rust builds and tests everything.
- Nightly
rustfmtfor formatting. The repository’srustfmt.tomluses unstable options; stablerustfmtsilently ignores them and reformats the whole tree. - ALSA headers on Linux.
bunsen-tool asr livecaptures audio throughcpal, whose Linux backend links ALSA, and clippy and the tests build every workspace member. - cargo-make, which runs the project’s tasks, including the book’s (Writing documentation).
These are the cost of building the whole workspace. A crate that depends on bunsen needs none of them.
What CI checks
The workflow runs four jobs, and comments each step:
| Job | Checks |
|---|---|
| Format | nightly rustfmt, in check mode. |
| Clippy | the whole workspace, with warnings as errors. |
| Book | the book builds, and every API link in it resolves (Writing documentation). |
| CI | the API docs, the tests, and the feature configurations below. |
CI has no accelerator and passes no backend feature, so its tests run on the CPU (Testing and backends).
Why several configurations
Cargo unifies features. When one command builds several crates, each
dependency is built once, with every feature that any of them asked for. A
crate that forgot to enable a feature it needs still builds, because a
sibling enabled it, and the failure waits for a user who depends on that
crate alone. A crate that uses burn/std but leaves it to bunsen to turn
on builds cleanly in the workspace, and fails cargo publish.
So the test job builds the code several ways, each standing in for a real consumer:
- The workspace, with
indicatif. Everything, with the tests and the run-time network code. No build script fetches anything (Assets): the validation crates’checkpointsandreferencestay off, and their suites run when asked (Validation). bunsenwith no default features. A user who writesdefault-features = falseand adds back only what they use. The tests run this way with only the test support (testingandaudit) turned on, so a test that needs a default feature carries acfggate for it. The library is also checked with no features at all.bunsenwithcachebut notfetch. The disk cache must compile without the network code.bunsenwithtrainbut notreflection. The group optimizers must compile without the reflection API they are usually paired with.- Each published crate on its own. One
cargo checkper manifest, which is whatcargo publishdoes. Several-pflags in one command would unify again.
The API docs get the same treatment, because a doc build unifies features
too: an intra-doc link can resolve in the workspace build and break for
bunsen alone, which is how docs.rs builds it. CI builds the workspace
docs, then bunsen alone with the feature list docs.rs uses, then bunsen
with its default features. A broken link then fails the PR, not the docs.rs
build after a release.
Running the checks locally
The IDE run configurations in .idea/runConfigurations/ are the local form
of the merge bar: a chain of clippy-fix, format and doc lint, then the
workspace tests, with or without a backend. STYLE.md’s
IDE run configurations
chapter describes the tiers and the rules for adding one. Without the IDE,
CONTRIBUTING.md lists the commands.
Neither runs every configuration above. A change to a feature list, or to a published crate’s dependencies, is worth checking in isolation before you push.
Commits
Commit subjects, and the titles of squash-merged PRs, follow
Conventional Commits. This is not
style for its own sake: release-plz reads the prefixes to write each
crate’s changelog and to choose the version bump (Releasing).
CONTRIBUTING.md has the
prefixes and what each one does.
Where to talk
CONTRIBUTING.md says when to open an
issue before a pull request.
The project’s Discord is linked from the
README.
Testing and backends
This page covers how bunsen’s tests choose a device, how they
keep an accelerator’s memory in check, and how they compare numbers that no
two backends compute identically. The helpers are in
bunsen::support::testing, behind the testing
feature.
Two test devices
bunsen’s tests take their device from one of two functions rather than naming a burn backend:
cpu_deviceis burn’sFlex, a CPU backend. Tests of logic, shapes and plumbing use it: it starts at once and needs no hardware.performance_deviceis the accelerator, chosen by a backend feature on bunsen (cuda,metal,vulkan,wgpu, in that order of preference), or byBURN_DEVICEin the environment. Tests that load a real model or exercise a real kernel use it, and so do the GPU benchmarks.
A test that trains calls .autodiff() on the device before it builds its
module and inputs.
The silent CPU fallback
When no backend feature reaches bunsen, performance_device() is the CPU.
Nothing fails. The tests compile, run and pass, having measured the CPU. A
plain cargo test says nothing about a GPU, and an audit of cpu_device()
against performance_device() compares the CPU with itself.
Always test with a backend feature, such as --features wgpu. A crate
whose own backend features should move performance_device() must forward
them to bunsen (wgpu = ["bunsen/wgpu"]); enabling only burn/wgpu leaves
it on the CPU. performance_device
documents the selection order and the fallback, and STYLE.md’s
Backend selection
has the rule.
The fallback matters in the other direction too. A defect in a GPU kernel that the CPU backend doesn’t share looks fixed on a CPU-only run, so a test that pins such a defect is gated on the backend features (Upstream bug reproductions).
Slow tests: gpu-tests
Some tests are too slow to be worth running without an accelerator, such as
loading a full checkpoint and stepping it against a reference. They compile
only under the gpu-tests feature, which is orthogonal to the backend
features: gpu-tests says whether the slow tests are built, and a backend
feature says which accelerator runs them. Pass both. Gate such a test on
feature = "gpu-tests", never on “some backend feature is on”, which would
leave no way to have one without the other
(GPU tests).
Inputs that agree across backends
Tensor::random depends on the backend’s generator and on global seeding.
seeded_tensor draws on the host
from a seeded generator and uploads the result, so every backend sees the
same values. Use it wherever two runs will be compared: across backends, in
an audit, or against a stored fixture.
Accelerator memory
cargo test runs every test in a binary in one process, so they share one
accelerator client and one cubecl memory pool. The pool keeps the pages it
has allocated, which is right within one model and wrong across a suite of
tests that each load their own: the pool only grows, until the card is full.
The failure is an out-of-memory error in whichever test was running at the
time, not in the one that allocated. Page sizes differ by backend, so a
suite that fits on wgpu can still run out on Vulkan.
A test that loads a model binds a
DeviceMemoryGuard at its
top, which hands the pool’s free pages back when the test ends. Its docs
give the two binding rules that decide whether it reclaims anything. The
guard limits what a suite accumulates over time, not what concurrent tests
hold at once, so heavy tests also run #[serial].
Comparing numbers
Two backends rarely compute a float result bit for bit alike: they reduce in
different orders, and some accelerator kernels trade precision for speed. A
test that runs on whichever backend a developer builds therefore compares
computed values within a tolerance.
support::testing states the rule
and has the assertions that apply it.
Set a tolerance from measurement, not by guessing. Run on each backend you support, look at the drift, and leave headroom over the worst. A real defect is usually far larger than any backend’s drift (Validation).
An elementwise tolerance is not always the right test. A decoder is judged
by the token it picks, and across tens of thousands of logits a tolerance
can pass while the argmax differs, so check the choice separately. Across a
whole transcript, compare text rather than token ids: one flipped token
cascades through the rest of the decode while the text barely moves.
kits::speech::testing::wer has the word error
rate that bunsen’s speech tests are judged by.
Untrained toy models
The Whisper driver and decoder unit tests run on tiny models with random weights, not on a checkpoint. An untrained model’s logits are full of near-ties, which flip between runs and backends, and on the CPU backend its forward pass varies from call to call by more than a near-tie. A test that needs a particular token sequence can’t get it from the model.
Such a test scripts the decode instead. A test-only
LogitFilter
masks every logit except the scripted token for the current position, so
the decode follows the script whatever the model computes. The test is then
about what it set out to test, such as the stream driver’s scheduling, seek
and emission, and not about an untrained model’s numerics. A test that
wants the model’s own choice seeds the model, so that a near-tie ranks the
same way on every run.
Test modules
Every #[cfg(test)] mod tests opens with use super::*;, so its imports
track the parent’s
(Test modules).
Audit probes and baselines
An audit records what a computation produced at named checkpoints, then
checks that another run produces the same thing. This page is about when to
reach for one and how to make it trustworthy.
bunsen::audit documents the probes, the harnesses and the
stream format, starting with a quick start.
When an audit beats a unit test
A unit test asserts what a value should be, so its author has to know the right answer. For a lot of numerical code nobody can write it down: a softmax over seeded noise, the fourth block of an encoder, a simulation after a thousand steps. An audit asserts instead that a value has not changed from a run you trust. That suits three jobs:
- Two backends agree. Run the same code on a reference backend and a target, and compare every checkpoint.
- A refactor changed nothing. Record before the change, verify after it.
- A result holds over time. Store a run as a baseline, and verify later runs against it.
An audit doesn’t say the trusted run was right. Pair it with something that does: a unit test of the cases you can derive by hand, or a validation against an independent implementation.
Writing a body
The code under test is an AuditBody, often a
closure, that a harness runs twice, each time on a device it supplies. It
takes an
AuditProbe and calls a checkpoint wherever an
intermediate value is worth pinning down. Three choices decide whether the
audit means anything:
- Inputs. Make them with
seeded_tensor, notTensor::random, or the two runs start from different data. - Exact or approximate. Check exactly what was uploaded, copied or rearranged, and check within a tolerance what was computed (choosing a checkpoint). The tolerance is recorded with the event, so a verifying run can’t quietly loosen it.
- Order. Checkpoints match by position, not by label, so keep the sequence deterministic: no checkpoint inside a loop whose trip count depends on the backend (how events match).
Checkpoints return errors rather than panicking. Stop the body at the first
Err: the first divergence is the one worth reading, and later checkpoints
only repeat it.
Across backends
audit_across runs a body on a reference
device, recording, then on a target device, verifying, all in memory. The
usual pair is cpu_device as the
reference and
performance_device as the
target. Build with a backend feature: without one, performance_device() is
the CPU as well, and the audit compares the CPU with itself
(the silent CPU fallback).
Baselines
audit_baseline compares a run with a
stream stored on disk. Baselines are per backend: a CPU baseline never
verifies a GPU run. Use audit_across to compare backends, and a baseline to
catch change over time.
The library never chooses where baselines live. The call site does, and a repository writes one constructor for its default location (where baselines live). Keep them under the build directory to keep them out of git, or in the source tree to check them in.
BaselineMode says what a run does
with a stored baseline. The default records a missing baseline and verifies
an existing one, which suits a developer’s machine. Use Record to accept an
intended change, and Verify in CI, so that a missing baseline is an error
rather than silently becoming the new truth
(record or verify).
Shapes and values
Audits are one half of how bunsen checks itself. The other half is shape contracts. A contract checks, on every call, that a tensor has the shape its docs promise, and catches a wrong reshape at the boundary where it happens. An audit checks that the values in a correctly shaped tensor are the ones a trusted run produced.
Validation against reference implementations
A kit that ports a published model makes a claim: it computes what the
original computes. This page describes how bunsen tests that claim. The two
validation crates are the worked examples, and their own docs carry the
details and the commands:
whisper-model-validation
and
silero-model-validation.
Why unit tests are not enough
bunsen’s Whisper and Silero kits are transliterations, written by reading the reference. Their unit tests check the code against itself, so a misreading that the code and its tests share passes: weights that load scrambled, or a ReLU where the reference uses GELU, leave a unit suite green. Validation pins a kit to something with independent provenance.
A reference that runs inside burn
The reference is the upstream model’s ONNX export, converted to Rust by
burn_onnx::ModelGen. Both implementations then run inside burn, on the same
backend, so a disagreement is a bunsen bug and not a difference between
frameworks. The export has to be the same model as the checkpoint bunsen
loads. Whisper’s is a conversion of OpenAI’s base checkpoint, so the two
agree only if bunsen’s loader and its forward pass are both right.
The reference lives with the validation crate, or with the
bundled-asset crate that supplies it,
and never in bunsen. It exists to be disagreed with, and shipping it would
put a second implementation of the model on the public surface.
Staged, then composed
There are two kinds of test, because each catches what the other lets through.
Staged tests feed each stage synthetic input and compare it with the same stage of the reference, on identical weights. An error can’t be inherited from upstream, so a failure names the stage that is wrong. A decoder’s logits and its argmax are checked separately: across tens of thousands of classes an elementwise tolerance can pass while the predicted token differs, and the token is what a decoder is judged on.
Composition tests run the whole model on real input and judge the
result the way a user would. Whisper transcribes real speech and is scored
by word error rate, against a ground-truth transcript and against
openai-whisper’s own decode of the same clip. Silero runs a real
recording through its streaming context and pins the per-chunk
probabilities. Every stage can agree within tolerance while the composition
diverges, because a greedy decode turns a small numerical difference into a
different word.
Tolerances from measured drift
The binding constraint is the backend, not the implementations. Two correct implementations, several blocks deep, drift apart by as much as the backend’s arithmetic does, and that differs by backend: CUDA’s reduced-precision matmul drifts an order of magnitude further than wgpu. So a tolerance is measured on each backend and set with headroom over the worst. It is still far tighter than the error a real defect causes: a scrambled weight or a wrong activation is off by 100% or more (Tolerance).
Fixtures generated once
Some references are not Rust and won’t be: librosa’s mel filterbanks,
openai-whisper’s decodes. bunsen’s tests never call them. A script under
tools/ runs the
reference once and writes its outputs into a testdata/ directory, and the
outputs are committed. The Rust tests read the files. Nothing shells out to
Python, and the reference is not a build or test dependency.
Regenerating a fixture is a deliberate manual step, never part of CI. Each
fixture script’s docstring pins the tool versions it was run with and says
how to set up its environment. The scripts run the reference on the CPU,
because a fixture only has to be correct, and a CPU run is deterministic. The audio the
tests read is collected in one dev crate, bunsen-test-audio, whose
README
records where each clip came from and under what licence; a fixture that is a
model’s output on a clip stays in the testdata/ of that model’s validation
crate.
Data is pinned the way models are: cargo catalog reads a dataset’s listing
at a pinned revision and lists the digests a shard set
verifies against.
Running validation
The validation crates are a Cargo workspace of their own, under
validation/, so no command in the main workspace builds them: run them from
validation/, or with --manifest-path validation/Cargo.toml, as the
cargo make tasks below do.
Every suite takes the same features, and none implies another:
checkpoints compiles the tests against the checkpoints, which fetch them at
run time through bunsen’s pinned rows into the weights cache; reference
fetches the ONNX reference at build time, with the bundle the conversion is
cross-checked with, and compiles the checks against them; gpu-tests
compiles the tests that run a model on a backend, and a backend feature says
which. Without them only the fixture-integrity checks run. A profile chooses
which models’ tests run (cargo make validate; the validation README’s
“Choosing what to validate”).
cargo make check-validation runs those, with clippy and the formatting
check, over the whole workspace with its default features. Pull-request CI
builds none of it: of the validation workspace it checks only that its
lockfile agrees with the root’s.
checkpoints alone compiles the checks that need no reference graph and no
backend: Silero’s recorded probabilities held to upstream’s model, and
Whisper’s fixtures against its vocabulary. They run on the CPU, as
cargo make validate-cpu. The checks of the bundles (the Whisper kit’s
pretrained pathway on the bundled base.pt, Silero’s bundled cache) run
under reference, where the bundle is: bundling is for verification.
validation.yml runs the stream drivers on the smallest models, on the CPU
(the ci profile, cargo make validate-ci): each driver held to its model’s
own one-shot decode, over about 0.6 GB of checkpoints it caches. How a model
behaves against its reference is the validate targets’, run by hand. It runs
only when asked: from the Actions tab, or for a pull request with the
validate label, then on every push while the label stays.
cargo make validate-<model> (silero, whisper, parakeet, qwen3-asr,
qwen3, sortformer, voxtral, nanochat, or all) runs a model’s whole suite, optimized, with debug assertions (the validate cargo profile), on
VALIDATION_BACKEND (default wgpu). The
README
has the command. Without a backend feature the suite still passes, having
measured the CPU (Testing and backends).
Validating a new kit
A kit that claims parity with an upstream implementation gets a crate under
validation/models/. Its reference and the checkpoint it is compared on
come through a bind-{model}-onnx crate under validation/onnx/, digest-pinned
(Assets, bundling and the network), and the crate tests in
both layers: staged on synthetic input, composed on real input with a
measured tolerance. The workspace
lists the validation crates there are.
Upstream bug reproductions
bunsen works around some defects in burn and its ecosystem. This page
explains how each one is recorded, so that its workaround is removed when
the defect is fixed rather than left behind to become a bug of its own. The
reproductions live in
crates/dev/burn_bug_repro,
whose crate doc is the reference.
Two tests per defect
Each defect gets a module, and the module carries two kinds of test:
| Test | Asserts | Fails when | Runs by default |
|---|---|---|---|
| the reproduction | the correct semantics | the bug is present | no, it is #[ignore]d |
| the behaviour pin | the current, wrong, behaviour | the bug is fixed | yes |
The reproduction is what you would send upstream. It says what should happen, and it fails today, so it is ignored to keep the suite green.
The behaviour pin is the half that protects bunsen. It asserts that the defect is still there. When a dependency update fixes it, the pin fails, and its message says what to do next: which workaround to remove, and which reproduction to un-ignore. Without the pin, an upstream fix would arrive silently, and the workaround would go on running against data that no longer needs it.
A pin names its workaround
A pin’s failure message is written for whoever next updates the dependency: it names the workaround the defect justified and says what to do with it. Some workarounds turn into bugs once the defect is fixed. A repair that undoes damage, applied to data that is no longer damaged, does damage of its own, and its pin asks for the repair’s removal.
Others are harmless after a fix. unfold on the CubeCL backends truncates an
outer stride, and bunsen avoids it by trimming an input to the span its
windows cover. The trim changes nothing once the defect is gone, so the pin
in the unfold module asks for a re-check rather than a removal. Write the
message for the workaround you have.
Writing a reproduction
- Public API only. Rest the reproduction on burn’s public API, so that taking it upstream means swapping the test helpers, not rewriting the test. A test of bunsen’s own workaround can sit in the same module; it just doesn’t travel with the reproduction.
- Document the defect in the module. The existing modules each say what the expected semantics are, what goes wrong, why it is easy to miss, its scope, and how to recover from it.
- Mind the CPU fallback. A kernel defect that the CPU backend doesn’t share can’t be seen on a CPU-only run, where a pin would report a fix that hasn’t happened. Gate such a pin on the backend features. A defect in a reader or a store is backend-independent and needs no gate (Testing and backends).
- Run it with a backend, in release mode. The crate doc has the command.
Why a separate crate
A reproduction is a statement about somebody else’s code: it carries a fixture, it wants a real accelerator to say anything, and its whole purpose is to stop being true. None of that belongs on a published library’s public surface.
Assets, bundling and the network
bunsen’s kits and their validation need files too large to commit:
checkpoints, reference exports, vocabularies. This page explains how the
workspace gets them without every build reaching the network, and why the
rules are what they are. The rules themselves are in STYLE.md’s
Network access
and
Fetched assets live in OUT_DIR;
the features that carry them are listed in
bunsen::data.
Build time and run time
There are two switches, and neither implies the other:
reference: the build may reach the network. A build script fetches an asset (an ONNX export, and the bundle of checkpoints its conversion is cross-checked with), and the crate compiles against it. It is off by default, so a plaincargo build --workspacenever fetches; and the crates that offer it are in the validation workspace (validation/), which no command in the main workspace builds.referenceis a conventional name rather than a bunsen feature: a crate that offers it turns on the per-asset features of the crates that own the assets.fetch: the program may reach the network at run time, to bring a pretrained model or a dataset shard into the disk cache (pretrained models, shard sets).
A validation test that needs a checkpoint fetches it, through fetch: the
validation crates’ checkpoints loads it by its pinned row, into the
weights cache, so a model is fetched once and shared. A program that loads
models by name wants fetch too.
Digest pins
Every fetched asset is pinned to a SHA-256, written beside its URL in the build script and re-verified on every build. A file that changes upstream is a build error, not a silently different model.
The build scripts fetch through the bunsen-fetch crate’s Asset, and
bunsen’s disk cache fetches through the same crate at run time: one
implementation of the streamed, hashed, renamed-into-place transfer, and one
statement of the resource cache layout, so what a build lays out is what the
cache reads.
An environment variable can point the build at a local file instead:
WHISPER_BASE_PT and its siblings, listed in the Whisper validation
README.
An override skips the pin, so use it for a copy you already trust.
Why OUT_DIR
OUT_DIR is the one directory a build script may write to. cargo publish
builds the packaged crate and fails if the build touched anything else in
the package, so an asset cache beside the manifest would make the crate
unpublishable. A crate unpacked from crates.io must not write into the
registry either. The cost is that cargo clean discards the assets along
with everything else.
The bundled crates
Shipping a model with a build doesn’t need a special kind of source. It
needs a cache directory that is already full
(bundling).
Every bundled crate hosts nothing: its build script fetches the files, pins
each one, and lays them out in OUT_DIR as a resource cache. A cache rooted
there finds them offline without knowing they were bundled.
Each is a crate of the validation workspace, validation/onnx/bind-{model}-onnx,
and none is published:
bind-whisper-onnxfetches Whisper’sbasecheckpoint, the vocabularies and the ONNX reference, forwhisper-model-validation.bind-silero-onnxfetches upstream’s 16 kHz Silero VAD checkpoint and its ONNX graph, from which the reference model is generated, forsilero-model-validation.bind-parakeet-onnxandbind-qwen3-asr-onnxfetch the ONNX exports of the base models, for their validation crates.bind-sortformer-onnxfetches ONNX exports of NVIDIA’sNemotron-3-Diarization(which its build script rewrites whereburn-onnxcannot import it) and of streaming Sortformer v2.1, for its validation crate.bind-qwen3-onnxfetches an onnxruntime-genai export ofQwen3-0.6B, for its validation crate. Such an export’s attention, rotary and RMS-norm ops are onnxruntime’s own, andrewrite-genai-onnxrewrites them to standard ONNX beforeburn-onnximports the graph.bind-voxtral-onnxfetches the onnxruntime-genai export of Mistral’sVoxtral-Mini-4B-Realtime-2602(its audio encoder, decoder and token embedding, 19 GB), rewritten the same way, for its validation crate.
The validation crates converted to validation/models.yml (Qwen3, nanochat,
Qwen3-ASR, Parakeet, Sortformer, Voxtral) fetch no checkpoint at build time: their
tests load each through bunsen’s own pinned rows, at run time, into the
weights cache, and a bind crate fetches only its ONNX reference.
Only the validation crates depend on them, through their reference
features, so no other build reaches the network. bunsen’s own tests
read no fetched asset: where a test needs what a real model does, it replays
a committed recording of it, and the validation crate checks the recording
against the model.
A deployment does the same thing at install time: fill the runtime cache
ahead of time, and the program never needs fetch.
How CI caches them
CI caches compiled units, not target/, so cargo runs every build script on
every run, and a build script’s fetch is not a compiled unit. A cache over an
OUT_DIR path would go stale as soon as the hash in that path changes, which
every toolchain or lockfile update does.
So assets are cached by digest instead. BUNSEN_ASSET_CACHE names a
directory every build script keeps what it fetches in, as <sha256>, and
takes a pinned file from before fetching it, verified as any asset is. Its
paths never move. The pull-request jobs fetch nothing at all; validation.yml,
which runs only when asked (from the Actions tab, or for a pull request with
the validate label), builds no ONNX reference: it runs the stream drivers on
the smallest models, whose checkpoints the tests fetch into the weights cache
(about 0.6 GB), which it caches under a key that hashes the rows’ pins. The
model checks run by hand.
Locally, set BUNSEN_ASSET_CACHE to keep assets across cargo clean and
toolchain updates, or point the override variables at copies you already
have.
Benchmarks
This page lists where bunsen measures performance, and the two things that make a measurement honest: a real backend, and knowing whether a number is cold or warm. It quotes no numbers; they depend on the hardware, and the benchmarks print their own.
What there is
The criterion benches live in
crates/public/bunsen/benches:
| Bench | Measures | Runs on |
|---|---|---|
contracts | shape-contract unpacks, asserts and periodic asserts (cost) | the host |
drop_block | 2D DropBlock over a small image batch | the CPU backend, always |
math | maybe_iroot against a floating-point reference | the host |
lbm | the D2Q9 lattice-Boltzmann collision, streaming and update steps, in f32 and f64 | performance_device() |
whisper_decode | the Whisper encoder and decode loop at base.en’s shapes, with random weights, cold and warm | performance_device() |
Outside the benches:
silero-benchruns a mono WAV file through Silero VAD’s streaming context onperformance_device(), prints the per-chunk speech probabilities, and optionally checks them against an expected JSON file.conway’sbenchmarksubcommand reports the sustained steps per second of the 2D or 3D Game of Life on the device--deviceselects. It measures the tensor kernels behind the simulation kits.bunsen-tool’stranscribelogs, at-v, each file’s audio length, transcription time and realtime factor, and the totals over the set. Its README runs it over a speech dataset.
Cold and warm
The CubeCL backends autotune their kernels, and the tuning is keyed on shapes. The first call at a new shape runs the tuner; later calls at that shape use what it found. A cold call and a warm one can differ by more than the optimization you are about to try, so measure both before deciding what to optimize, and know which one a number is.
- Criterion warms up before it measures, so its numbers are warm.
whisper_decodetimes each case’s first call once and prints it ascold. conway benchmarkleaves a warmup fraction of its steps out of the timing.bunsen-toolsizes every push to the stream driver’s grain, so the front end and the autotuned kernels behind it see one shape, not a drift of remainders.- A benchmark whose shapes change every iteration measures the tuner, not the kernel.
Always pass a backend
A benchmark on
performance_device
measures whatever bunsen’s backend feature selected, and without one that is
the CPU. It doesn’t fail; it reports CPU numbers
(Testing and backends). Pass the
backend explicitly: --features wgpu, or another backend, for bunsen’s own
benches, and --features bunsen/wgpu for a binary that reaches
performance_device() through bunsen, such as silero-bench. The examples and
bunsen-tool, conway among them, pick their device at run time with
--device; a backend is selectable only when the binary was built with its
feature, and without one auto is the CPU. The examples’ READMEs and the
whisper_decode bench’s docs give exact commands.
Benches build optimized already. Run the binaries with --release too: the
work is inside burn’s kernels, and an unoptimized build measures the wrong
thing.
Writing documentation
bunsen has two kinds of documentation, rustdoc and this book, and each fact belongs in exactly one of them. This page covers the book’s side, for anyone writing it: how the book links into the API, how code in the book stays correct, and how to build the book. STYLE.md’s rustdoc chapter has the rules for rustdoc, including which facts belong there.
rustdoc is the reference
rustdoc documents every interface and every lifecycle; the book explains what rustdoc can’t hold, names each concept, and links to it. When a book page needs a fact that rustdoc doesn’t have, the fix is in rustdoc. STYLE.md’s rustdoc is the reference is the rule, including what the book never restates.
Module docs must render
A private module’s //! never reaches the API docs, so prose written there
is invisible. STYLE.md’s
Module docs must render
says where that prose goes instead, and CI enforces it with
tools/check_hidden_module_docs.py.
Linking into the API
API links in the book are rustdoc intra-doc paths, not URLs:
| To link | Write |
|---|---|
| an item | [`ShapeContract`](bunsen::contracts::ShapeContract) |
| a module | [`bunsen::ops`] |
| a section of a page | [the ops/blocks rule](bunsen::ops#ops-and-blocks) |
| a method | [`try_init`](bunsen::burner::module::ModuleInit::try_init) |
| a macro | [`shape_contract!`](bunsen::contracts#macros-and-methods), the section of its module’s page that lists it (see below) |
| another published crate | [`bunsen_firehose`] |
Macros are the one exception to linking the item itself. rustdoc can’t
resolve a path to a macro_rules! macro that another crate re-exports
(bunsen::contracts::shape_contract! reports “no item named bunsen in
scope”), so a book link to a bunsen macro goes to the module section that
documents it.
mdbook-rustdoc-links resolves them at build time with rustdoc’s own
resolver, so a link in the book is exactly as valid as the same link in a
doc comment. Renaming or moving an item, method or field leaves the link
unresolved, and that fails the book build in CI, in the same PR as the
rename.
Only what docs.rs shows resolves. bunsen is built with the feature list
in its [package.metadata.docs.rs], and the other published crates with
their defaults (docs.rs may build one with more), so an item behind a
feature that docs.rs doesn’t build can’t be linked. The crates/dev crates,
the validation workspace’s and the examples are not in that build. Link
them, and other repository files, as GitHub URLs, and keep those few.
The base URL the links point at is chosen per build:
- Local builds link to
/api, a symlink frombook/src/apitotarget/doc, and include the API docs in the book’s output, so a local book reads against the API at HEAD, offline. - Release builds, selected when
CIis set, link to docs.rs, pinned to each crate’s version fromCargo.lock. That is why a book for readers is built only from a release (Releasing). MDBOOK_PREPROCESSOR__RUSTDOC_LINKS__BASE_URLoverrides both.
Links between chapters are relative .md paths. mdbook-linkcheck2 checks
that the file exists, but not the #anchor.
Square brackets in prose are read as links, and an unresolved one fails the
build. Escape a stray bracket (\[x\]) or put it in a code span.
Code in the book
Every Rust block in the book is compiled, or it is plainly a sketch:
- Runnable code that names bunsen items is pulled in from compiled code
with an mdbook include,
{{#include path:anchor}}, fromcrates/dev/book-snippetsor an example. The included region sits between// ANCHOR: nameand// ANCHOR_END: namein a test or amain, socargo testruns it, and CI builds, lints and formats it like any other workspace member. Prefer including code an example already has over writing a new snippet. - A sketch that names no bunsen items may use a
textorrust,ignorefence, and the prose around it says it is a sketch. - The book never copies a rustdoc example. It links to the doctest.
Shapes, math and diagrams
- Tensor shapes are one code span in square brackets, with the
dimension arithmetic inside, such as
[batch, h_wins*size, w_wins*size, channels]. This is STYLE.md’s shape notation, the same in rustdoc and the book, and it reads like the shape contract that checks the shape. The code span also keeps the brackets away from the link resolver. - Math is KaTeX, between dollar signs. Book-wide macros, such as
\RR,\NNand\ZZfor the number sets, are defined inbook/katex-macros.txt. Add a macro there rather than repeating a definition on a page. - Diagrams are mermaid, or
textfences. Prefer atextdiagram when the same picture may belong in rustdoc.
Building the book
The book’s tasks are in Makefile.toml. Each installs the pinned mdbook
tools on first use, at the versions CI uses:
| Task | What it does |
|---|---|
cargo make book | builds the book against the local API docs; an unresolved API link is a warning |
cargo make book-check | the same build CI runs: an unresolved API link is an error |
cargo make book-serve | serves the book locally, rebuilding as you edit |
cargo make book-release | the publishing build: API links pinned to this release on docs.rs |
Run book-check before pushing a change that touches the book or renames
anything public. The build runs cargo doc itself, so the first run is
slow. The release workflow makes the book-release build and publishes
it (Releasing); run it locally only to preview that.
Writing a page
Open each page with a sentence or two on what it covers. Say what a thing is for and when to reach for it, and stop when the why is told: one good paragraph and a link beat a list of features. Every API noun is a link.
Releasing
Releases are automated by release-plz. The
process, and what a maintainer does at each step, is in
CONTRIBUTING.md,
the canonical guide. This page only says how the pieces fit.
Versions
Nobody bumps a version or runs cargo publish by hand. release-plz keeps a
release PR open against main, carrying the next version and the
changelogs it wrote from the commit history, which is why commits follow
Conventional Commits (Development setup). Merging that
PR publishes the release. The published crates share one version and move
together.
bunsen’s version is its own semantic version, and it is not tied to burn’s.
A version bump says something about bunsen’s API, and nothing about which
burn release it builds against. release-plz runs cargo-semver-checks, so
an API break gets a breaking bump even when its commit didn’t say so.
The book
The release workflow publishes the book after every release, to GitHub
Pages. The build points every API link at docs.rs, pinned to the version
just released, so it is built from the release, not from main, and the
pinned links are dead until docs.rs has built that version. CI builds and
checks the book on every pull request, but only a release publishes it.
CONTRIBUTING.md’s release section says how to republish by hand, and
Writing documentation covers the other book
tasks.
License
bunsen is distributed under the terms of both the MIT license and the
Apache License (Version 2.0). See
LICENSE-APACHE
and
LICENSE-MIT
for details.
Opening a pull request is assumed to signal agreement with these licensing terms.