Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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:

  1. track the burn release cycle, so dependent code doesn’t have to;
  2. give one dependency surface for common building blocks, instead of a tangle of single-purpose crates;
  3. centralize testing, documentation and validation, so contributed components can be trusted across projects.

How to read this book

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).

CrateWhat it is
bunsenThe library: contracts, ops, blocks, kits, the pretrained-model machinery, audits. Most users depend on this alone. See the bunsen crate.
bunsen-contracts-macrosThe proc macro behind shape_contract!. Never a direct dependency; bunsen re-exports it.
bunsen-firehoseA column-oriented data-processing pipeline that feeds burn’s Batcher. Independent of bunsen. See Firehose.
bunsen-firehose-imageImage operators for firehose: loading, augmentation, conversion to tensor data.
bunsen-arrow-dataloadersPreview. Parquet shards to tokenized training batches, for language-model training. See Datasets.
bunsen-appShared 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-toolA 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

CrateRole
burn_bug_reproReproductions of defects in burn and its ecosystem, each paired with a pin on today’s behaviour. See Upstream bug reproductions.
silero-benchA benchmark CLI for Silero VAD. See Benchmarks.
bunsen-test-audioThe 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

CrateRole
rewrite-genai-onnxRewrites 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

CrateValidates
gemma-model-validationGemma 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-validationnanochat 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-validationParakeet TDT against an independent implementation generated from NeMo’s own ONNX export, stage by stage.
qwen3-asr-model-validationQwen3-ASR against an implementation generated from an ONNX export, and against transformers’ own decode of real speech.
qwen3-model-validationQwen3 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-validationSilero VAD against the ONNX graph it was transliterated from, and against a committed golden trace.
sortformer-model-validationSortformer 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-validationVoxtral Realtime against an implementation generated from the published ONNX export, and against transformers’ own greedy decodes of real speech.
whisper-model-validationWhisper 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:

LayerContents
kits, simsWhole models, with their configs, pretrained indexes and runtime drivers; simulations.
blockstorch.nn-like components: module roots and tree parts.
opsOperations: free functions, and Module/Config types that hold cached tables or stream state.
foundationburner (burn extensions), contracts (shape checks), errors, rust_ext (Rust helpers), support, zspace.
burnThe 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.

ModuleWhat it is for
kitsComplete domain implementations: image models (images), language models (language), speech (speech), and the shared token seam (tokens). See Kits.
simsSimulations written as tensor programs: Conway’s Game of Life (conway) and a lattice-Boltzmann fluid (lbm).
blocksReusable Module components: conv blocks, image layers, recurrent cells, transformer parts.
opsTensor operations, including the signal-processing front ends and attention ops.
burnerExtensions to burn’s module machinery: the config lifecycle (ModuleInit, ToStructureConfig), reflection, grouped optimizers, tensor extension traits, PyTorch-load repairs.
contractsRuntime tensor-shape contracts. See Shape contracts.
dataThe disk cache, resources, the catalog, model loading, formats and dataset shard sets. See Data: from files to models.
auditAudit probes: record a stream of tensor checkpoints from one run and verify another against it. See Audit probes and baselines.
errorsBunsenError and its kinds, context frames and typed causes; BunsenResult; the try_x / x convention; and, with testing, the ErrorMatcher test matchers.
rust_extRust-language extensions with no tensor or burn dependency: CloneBox / CloneRef, array and range helpers, and LocationDesc, a serializable source location.
supportShared utilities, including the test backends and devices in support::testing.
zspaceInteger-lattice index and shape helpers.
preludeThe traits most code needs in scope, for one glob import.
publicRe-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 blocks or ops once 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, speech and sims: the model kits; the speech kits among them (speech recognition, diarization, voice activity), which turn on kits and audio; and the simulations. All three are default.
  • reflection: the XML/XPath module reflection behind parameter groups.
  • train: the grouped optimizers and other burn/train integration.
  • audio and tokenizer: audio file decoding, and turning token ids into text, for the speech kits.
  • testing and audit: the test support in support::testing and the audit probes.
  • store: reading checkpoints through burn-store, in every format bunsen knows: burnpacks, PyTorch .pt state dicts, safetensors, NeMo’s .nemo archives 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. indicatif adds a progress bar.
  • Build-time network: a build script may fetch assets. No bunsen feature does; only the validation crates’ reference turns on the bind crates’ fetches of the ONNX references and their bundles, digest-pinned. Their checkpoints tests fetch at run time, through fetch.

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:

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 resnet50 or openai/base.en and 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 in bunsen::data::pretrained. A kit contributes tables and a ConstructInit hook, 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:

  1. 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 Meta trait.
  2. An example under examples/ that runs it end to end.
  3. Names: a prefab map, then pretrained rows and a ConstructInit hook, and a default_{kit}_factory(), once there are weights to load.
  4. A validation crate under validation/models/, once the kit claims parity with an upstream implementation.
  5. Promotion: a layer that a second kit needs moves out to blocks or ops.

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.

ExampleWhat it shows
train-chatTrains a NanoChat GPT from scratch on streamed dataset shards, with nanochat’s Muon + AdamW parameter groups.
resnet_finetuneFine-tunes a pretrained ResNet for multi-label classification, with model surgery: a new head, a swapped activation, DropBlock and stochastic depth.
resnet_tinyTrains a ResNet from scratch on CINIC-10 through a firehose pipeline, loading a checkpoint into a modified prefab.
swin_tinyTrains a Swin Transformer V2 on CINIC-10, sharing resnet_tiny’s data pipeline.
conwayConway’s Game of Life in 2D and 3D, on any backend: an interactive view and a benchmark.
lbm2d_visA 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:

  • FooStructureConfig is the unrolled tree, with one field per sub-module config, and it implements ModuleInit. 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 bare FooConfig, 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 gets ModuleInit from that trait’s blanket impl. If a policy also implements ModuleInit itself, the compiler rejects it (E0119). That is deliberate: policy.init(&device) and policy.to_structure().init(&device) run the same code, so they cannot drift apart (init for free). Per-policy logic, including validation, goes in try_to_structure.
  • FooMeta is 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:

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

  • init needs the module type. ModuleInit is generic over the module it builds, so where nothing else pins that type, config.init(&device) needs a binding such as let 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 init must 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 in try_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, Illegal or Internal. is_bug is true. Escalate it. A script panics. A long-running service logs the report and fails the one request or graph, not the process. Illegal means the calling code broke a documented rule. Internal means bunsen broke its own, and is worth an issue.
  • Retry, Unavailable. is_retryable is 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. The LookupError cause 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, {:#}, or Debug) 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 Illegal back. The rule that broke is the input’s fault, so re-mark it with as_policy.
  • You passed a name your own code chose, and got a Lookup back. That is a bug on your side, so re-mark it with as_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:

  1. If the code has to change, the kind is Illegal, or Internal when the code at fault is bunsen’s own.
  2. If the request or its settings have to change, the kind is Policy.
  3. Otherwise the world disagrees: Lookup (a key did not resolve), Unavailable (not now), or InvalidResource (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 # Errors or # Panics) is Illegal when 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 the Rule.
  • 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 gives InvalidResource, a request gives Policy, and the program’s own text gives Illegal.
  • A foreign error stays the cause. Do not format it into the message. An io::Error goes through sys_at, which also names the path. There is deliberately no From<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. find walks 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 Unavailable failure, 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 a Retry-After header asked.
  • A Lookup failure means the URL is missing or forbidden. The loop moves to the next mirror.
  • A download whose digest does not match the pin is InvalidResource to 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 Policy or Sys, 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 From impl builds the error with from_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 implements Detailed.
  • It is public, #[non_exhaustive], and documented in the # Errors sections 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. BunsenError is Clone, shared behind an Arc, 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:

  1. Unpack the inputs at the top of the function. You needed the dimensions anyway, and the check comes with them.
  2. Do the work in terms of the unpacked names.
  3. 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:

StrategyDebug buildsRelease buildsUse when
assert_shape_contract! / unpack_shape_contract!every callevery callThe path is cold or runs once per batch, or you want the failure in production.
assert_shape_contract_periodically!sampledsampledThe path is hot, but you still want some coverage in production.
Either, under #[cfg(debug_assertions)]as aboveremovedThe 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

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 as Module roots or as parts of a module tree.
  • Ops are operation-focused. They may use the Module and Config machinery, 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:

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:

  1. A port of a known layer from a paper or a reference library, kept in burn form so that every kit can use it. DropBlock2d and DropPath are the DropBlock and stochastic-depth regularizers, the latter after timm’s.
  2. A part shared by kits. A layer that a second kit needs moves out of the first one. ConvBlock1d and ConvSeq1d serve both Whisper and Silero VAD, and TransformerMlp serves 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, and TokenEmbedding (with an optional scale) serves Gemma and NanoChat.
  3. A gap in burn. burn ships a sequence-level Lstm. FusedLstm is 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: BunsenActivationConfig keeps burn’s kinds under burn’s names, and adds Silu, Pow and Chain (NanoChat’s relu(x)² is Chain([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 CausalSelfAttention block (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’s RotarySet (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:

ModuleWhat it holdsChapter
cachethe disk cache: where files land, digests, links, downloadsResources and the cache
resourcespinned files, the places they come from, the resource cache, the Hub clientResources and the cache
catalogwhat there is to build, as data: a layered catalog of contracts, builds, resources, tags and presetsThe catalog
formatsreading the files: safetensors, PyTorch, MLX, the Phonon formatsFormats
buildsa name to a model: providers, the factory, the kit’s hookLoading builds
pretrainedthe kits’ prefabs, geometries by nameLoading builds
datasetsdataset shard setsDatasets

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 as parquet-shards, is data::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):

  1. the family’s config, serialized;
  2. the set’s common patch;
  3. the default presets, except where the selection names another member of the same axis;
  4. the selected presets, as one layer: two that set the same path are an error, so their order never matters;
  5. 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 by Prefabs.
  • A build, a ResolvedBuild, is what the catalog says one model is: its name and aliases, its tags and presets, the geometry it states, and the resources its contract’s slots are bound to.
  • A resource, a Resource, is one file (Resources and the cache).

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

Providers

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

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

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

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

Deferred models and the kit’s hook

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

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

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:

  1. A config, which builds the module.
  2. 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).
  3. 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:

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::Agreement is not implemented yet: building a driver under it fails with an Unsupported error.
  • The interval trigger drafts only while the voice-activity gate says speech is in progress, and that gate runs only under endpoint (DecodeTriggers), so a driver with interval and without endpoint fails 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_head and 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

  1. Build an XmlModuleTree over the live module.
  2. Select each group’s ParamIds with a query, by structure.
  3. Gather every parameter that no group claimed into a remnant group, and check that no group is empty.
  4. Wrap each set in an OptimizerGroup with its optimizer (any burn optimizer, such as AdamWConfig::new().build()) and, if it needs them, a learning-rate rule (LrSelector) and a gradient clipping.
  5. Plan the module and the groups with GroupOptimizerPlan::try_new.
  6. Build burn’s ModuleOptimizer with plan.optimizer() and its ModuleLrScheduler with plan.lr_scheduler(schedule), and hand both to a Learner, 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 rustfmt for formatting. The repository’s rustfmt.toml uses unstable options; stable rustfmt silently ignores them and reformats the whole tree.
  • ALSA headers on Linux. bunsen-tool asr live captures audio through cpal, 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:

JobChecks
Formatnightly rustfmt, in check mode.
Clippythe whole workspace, with warnings as errors.
Bookthe book builds, and every API link in it resolves (Writing documentation).
CIthe 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’ checkpoints and reference stay off, and their suites run when asked (Validation).
  • bunsen with no default features. A user who writes default-features = false and adds back only what they use. The tests run this way with only the test support (testing and audit) turned on, so a test that needs a default feature carries a cfg gate for it. The library is also checked with no features at all.
  • bunsen with cache but not fetch. The disk cache must compile without the network code.
  • bunsen with train but not reflection. The group optimizers must compile without the reflection API they are usually paired with.
  • Each published crate on its own. One cargo check per manifest, which is what cargo publish does. Several -p flags 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_device is burn’s Flex, a CPU backend. Tests of logic, shapes and plumbing use it: it starts at once and needs no hardware.
  • performance_device is the accelerator, chosen by a backend feature on bunsen (cuda, metal, vulkan, wgpu, in that order of preference), or by BURN_DEVICE in 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, not Tensor::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:

TestAssertsFails whenRuns by default
the reproductionthe correct semanticsthe bug is presentno, it is #[ignore]d
the behaviour pinthe current, wrong, behaviourthe bug is fixedyes

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 plain cargo build --workspace never fetches; and the crates that offer it are in the validation workspace (validation/), which no command in the main workspace builds. reference is 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-onnx fetches Whisper’s base checkpoint, the vocabularies and the ONNX reference, for whisper-model-validation.
  • bind-silero-onnx fetches upstream’s 16 kHz Silero VAD checkpoint and its ONNX graph, from which the reference model is generated, for silero-model-validation.
  • bind-parakeet-onnx and bind-qwen3-asr-onnx fetch the ONNX exports of the base models, for their validation crates.
  • bind-sortformer-onnx fetches ONNX exports of NVIDIA’s Nemotron-3-Diarization (which its build script rewrites where burn-onnx cannot import it) and of streaming Sortformer v2.1, for its validation crate.
  • bind-qwen3-onnx fetches an onnxruntime-genai export of Qwen3-0.6B, for its validation crate. Such an export’s attention, rotary and RMS-norm ops are onnxruntime’s own, and rewrite-genai-onnx rewrites them to standard ONNX before burn-onnx imports the graph.
  • bind-voxtral-onnx fetches the onnxruntime-genai export of Mistral’s Voxtral-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:

BenchMeasuresRuns on
contractsshape-contract unpacks, asserts and periodic asserts (cost)the host
drop_block2D DropBlock over a small image batchthe CPU backend, always
mathmaybe_iroot against a floating-point referencethe host
lbmthe D2Q9 lattice-Boltzmann collision, streaming and update steps, in f32 and f64performance_device()
whisper_decodethe Whisper encoder and decode loop at base.en’s shapes, with random weights, cold and warmperformance_device()

Outside the benches:

  • silero-bench runs a mono WAV file through Silero VAD’s streaming context on performance_device(), prints the per-chunk speech probabilities, and optionally checks them against an expected JSON file.
  • conway’s benchmark subcommand reports the sustained steps per second of the 2D or 3D Game of Life on the device --device selects. It measures the tensor kernels behind the simulation kits.
  • bunsen-tool’s transcribe logs, 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_decode times each case’s first call once and prints it as cold.
  • conway benchmark leaves a warmup fraction of its steps out of the timing.
  • bunsen-tool sizes 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 linkWrite
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 from book/src/api to target/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 CI is set, link to docs.rs, pinned to each crate’s version from Cargo.lock. That is why a book for readers is built only from a release (Releasing).
  • MDBOOK_PREPROCESSOR__RUSTDOC_LINKS__BASE_URL overrides 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}}, from crates/dev/book-snippets or an example. The included region sits between // ANCHOR: name and // ANCHOR_END: name in a test or a main, so cargo test runs 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 text or rust,ignore fence, 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, \NN and \ZZ for the number sets, are defined in book/katex-macros.txt. Add a macro there rather than repeating a definition on a page.
  • Diagrams are mermaid, or text fences. Prefer a text diagram 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:

TaskWhat it does
cargo make bookbuilds the book against the local API docs; an unresolved API link is a warning
cargo make book-checkthe same build CI runs: an unresolved API link is an error
cargo make book-serveserves the book locally, rebuilding as you edit
cargo make book-releasethe 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.