In short: every example is three Bazel targets, a library with the logic, a main.cc that parses
positional arguments and prints, and a GoogleTest that checks the example's headline claim (the CNN beats the MLP
with fewer parameters, only the LSTM learns the adding problem, Q-learning takes the cliff edge and SARSA the safe
path). Twenty-eight are teaching demos, one per /ml-models concept, from an MLP to DPO, a U-Net diffusion model and a
model server; they build on autograd, nn, losses and optim, or on
linalg alone for the closed-form ones. Four are tools for the runtime and the inference stack:
rml-chat, rml-graph-run and the two exact-output export checks. Together they hold 156 tests.
The rule behind the layout is in rml's own guidance: examples are entry points that parse flags and print, and all
the logic they call lives in a library so it can be unit-tested
(architecture.md L30–31,
AGENTS.md L148–149). The README's quick start lists a
bazel run line for each demo (README.md L32–245), which
the tables below cite.
Anatomy of an example
examples/mlp as the pattern
(BUILD.bazel L11–47). Libraries are named <name>_lib, except
rl's gridworld and rml_chat's chat_lib.
main.cc stays a few lines: it fills an options struct from positional arguments (for the MLP only a
seed), calls one function and prints its result struct
(main.cc L1–20). Every random draw goes through
rml/random's Philox generator, which every example but the four tools depends on, so the same options give the
same numbers, which is what lets a test assert a trained model's accuracy. All targets use the
rml_cc_* macros, so the warning flags and -Werror apply to examples as to the library
(see Build and testing). The binary is named after the directory except for the tools,
whose binaries are rml-chat, rml-graph-run, tiny-net and
tiny-models.
Every example
Grouped roughly as /ml-models orders its areas. "Built from" lists the rml modules the example's library depends on; "Tests" links its test file.
Networks and architectures
| Example | What it does | Built from | Concept | Tests |
|---|---|---|---|---|
mlp//examples/mlp | MLP on synthetic 8×8 digits; the README quotes about 99% test accuracy in a few seconds. (mlp.h L4–10, README L34) | autograd, core, data, losses, nn, optim, random | training loop | 2 |
cnn//examples/cnn | A CNN next to an MLP on glyphs at random positions: shared filters and pooling generalize where the MLP cannot. (cnn.h L4–12, README L40–41) | autograd, core, data, losses, nn, optim, random | cnns | 2 |
rnn//examples/rnn | A vanilla RNN next to an LSTM on the 50-step adding problem; only the LSTM learns the long memory. (rnn.h L4–13, README L47–48) | autograd, core, data, losses, nn, optim, random | rnns and lstms | 2 |
vit//examples/vit | A Vision Transformer on the CNN's glyphs, cut into 3×3 patches, with and without position embeddings. (vit.h L4–15, README L54–55) | autograd, core, data, losses, nn, optim, random | vision transformer | 4 |
ssm//examples/ssm | A diagonal linear state-space model on the adding problem at 200 steps, its scan checked against the convolution view. (ssm.h L4–20, README L61–62) | autograd, core, data, losses, nn, optim, random | state space models | 4 |
gnn//examples/gnn | A graph convolutional network labelling nodes from ten labels per class, next to an MLP on the node features alone. (gnn.h L4–13, README L177–178) | autograd, core, losses, nn, optim, random | graph neural networks | 5 |
encoder//examples/encoder | An encoder-only transformer pretrained by masked-token prediction on palindromes, next to the same network under a causal mask. (encoder.h L4–14, README L68–70) | autograd, core, data, losses, nn, optim, random | encoder only | 3 |
char_gpt//examples/char_gpt | A ~10M-parameter character-level GPT trained on a short original text (TinyCorpus), then sampled. (char_gpt.h L4–8, README L232) | autograd, core, losses, nn, optim, random | decoder only llm | 5 |
Training and adaptation
| Example | What it does | Built from | Concept | Tests |
|---|---|---|---|---|
finetune//examples/finetune | The pretrained encoder fine-tuned with about a thousand labels, next to a linear probe and training from scratch. (finetune.h L4–21, README L76–78) | autograd, core, data, losses, nn, optim, random | fine tuning | 2 |
distillation//examples/distillation | A student with 1/160 of a teacher's parameters, distilled on soft targets next to the same student on hard labels. (distillation.h L4–34, README L147–149) | autograd, core, losses, nn, optim, random | distillation | 3 |
dpo//examples/dpo | Direct preference optimization of a small language model toward a larger digit sum, at two values of beta. (dpo.h L4–17, README L84–86) | autograd, core, data, losses, nn, optim, random | preference optimization | 5 |
distributed//examples/distributed | Data-parallel SGD over simulated workers averaging gradients by ring all-reduce; batch scaling and local SGD. (distributed.h L4–36, README L162–164) | core, random | distributed training | 5 |
Generative models
| Example | What it does | Built from | Concept | Tests |
|---|---|---|---|---|
vae//examples/vae | A VAE with a 2-D latent on 8×8 bars images, printing what the decoder draws across the latent plane. (vae.h L4–12, README L184–185) | autograd, core, data, losses, nn, optim, random | variational autoencoders | 3 |
diffusion//examples/diffusion | DDPM on eight Gaussians on a ring. (diffusion.h L4–15, README L191) | autograd, core, data, losses, nn, optim, random | diffusion models | 6 |
diffusion_unet//examples/diffusion_unet | Diffusion on 12×12 glyph images with a time-conditioned U-Net, next to the same network without skips (about 13 minutes). (diffusion_unet.h L4–26, README L197–199) | autograd, core, data, losses, nn, optim, random | diffusion unet | 6 |
flow_matching//examples/flow_matching | Flow matching on the same ring, comparing how many Euler steps the sampler needs. (flow_matching.h L4–14, README L205) | autograd, core, data, losses, nn, optim, random | flow matching | 6 |
gan//examples/gan | A GAN on the same ring, whose samples sharpen and begin to collapse onto a few modes. (gan.h L4–13, README L211–212) | autograd, core, losses, nn, optim, random | gans | 4 |
Retrieval, ranking and multimodal
| Example | What it does | Built from | Concept | Tests |
|---|---|---|---|---|
rag//examples/rag | A dense retriever plus a transformer reader, next to the same reader closed-book, on held-out and edited facts. (rag.h L4–38, README L218–220) | autograd, core, data, losses, nn, optim, random, retrieval | retrieval augmented generation | 4 |
two_tower//examples/two_tower | Two-tower retrieval on synthetic clicks with and without the logQ correction, cold items, and an IVF index over item embeddings. (two_tower.h L4–40, README L114–116) | autograd, core, losses, nn, optim, random, retrieval | two tower models | 3 |
collaborative_filtering//examples/collaborative_filtering | Held-out ratings from the global mean, ridge biases, item-item kNN and ALS matrix factorization. (collaborative_filtering.h L4–36, README L100–101) | core, linalg, random | collaborative filtering | 5 |
learning_to_rank//examples/learning_to_rank | One linear scorer trained pointwise, pairwise (RankNet) and listwise (LambdaRank), scored by NDCG. (learning_to_rank.h L4–36, README L107–108) | core, linalg, random | learning to rank | 6 |
multimodal//examples/multimodal | CLIP-style contrastive image and caption encoders labelling unseen shape, size and position combinations zero-shot. (multimodal.h L4–34, README L138–141) | autograd, core, losses, nn, optim, random | multimodal models | 5 |
Classical, causal and production
| Example | What it does | Built from | Concept | Tests |
|---|---|---|---|---|
time_series//examples/time_series | Naive, seasonal naive, Holt-Winters and seasonal autoregression forecasts under a rolling-origin backtest. (time_series.h L4–34, README L92–94) | classical, core, random | time series | 8 |
online_learning//examples/online_learning | Logistic regression learned online through a concept change: frozen batch, decaying and constant SGD, FTRL-proximal. (online_learning.h L4–41, README L122–124) | core, linalg, random | online learning | 5 |
causal_inference//examples/causal_inference | A treatment effect from confounded data by difference in means, regression adjustment, IPW and AIPW, next to a randomized trial. (causal_inference.h L4–42, README L130–132) | core, linalg, random | causal inference | 6 |
drift//examples/drift | Covariate and concept drift on a deployed classifier: feature PSI, KS tests, score PSI and week-late accuracy. (drift.h L4–35, README L155–156) | core, random | monitoring and drift | 9 |
serving//examples/serving | A simulated model server: dynamic batching under Poisson load, then static against continuous batching for generation. (serving.h L4–46, README L170–171) | core, random | model serving | 10 |
rl//examples/rl | Value iteration, Q-learning and SARSA on cliff walking. (gridworld.h L4–18, README L226) | random | reinforcement learning | 4 |
Runtime and inference-stack tools
| Example | What it does | Built from | Deep dive | Tests |
|---|---|---|---|---|
rml_chat//examples/rml_chat:rml-chat | rml-chat: chat with a GGUF file or Hugging Face directory, optionally with a draft model for speculative decoding. (chat.h L4–6, README L238–240) | core, io, llm | Generation | 11 |
graph_run//examples/graph_run:rml-graph-run | rml-graph-run: load an exported rml-graph model, feed it inputs, time it and check it against stored outputs. (graph_run.h L4–5) | core, graph, io | Executing a graph | 7 |
tiny_net//examples/tiny_net:tiny-net | One Dense–ReLU–Dense net exported from PyTorch, JAX and TensorFlow and run with outputs checked bit for bit. (tiny_net.h L1–8) | core, graph | Exporters and the model zoo | 3 |
tiny_models//examples/tiny_models:tiny-models | A CNN, an LSTM and a transformer block from all three frameworks, each with an exact expected output. (tiny_models.h L1–10) | core, graph | Exporters and the model zoo | 3 |
What the examples exercise
| Library part | Examples that use it | Note |
|---|---|---|
autograd + nn + losses + optim | 19 | Every neural demo; see Autograd, Neural network layers and Losses and optimizers. |
data | 13 | Only TensorDataset and DataLoader; nothing calls the preprocessing or split helpers (see Data and metrics). |
linalg without autograd | 4 | causal_inference, collaborative_filtering, learning_to_rank and online_learning fit their models with Cholesky solves (least squares, ridge, Newton steps) instead of gradient descent. |
retrieval | 2 | rag (cosine similarity) and two_tower (similarity plus the IVF index); see Retrieval. |
classical | 1 | time_series fits its seasonal autoregression with LinearRegression. |
llm, io | 1 | rml_chat. |
graph | 3 | graph_run, tiny_net and tiny_models. |
Plain C++ and random only | 4 | distributed (with core's thread pool), drift, serving and rl implement their small models by hand. |
metrics, quant | 0 | No example depends on them directly; examples compute their own accuracy, NDCG and errors. |
The counts are of each example library's direct dependencies in its BUILD.bazel at the pin. Most
/ml-models concept pages that are not examples are implemented as library modules instead, from the layers on
Neural network layers to the estimators on Classical models.
The four tools
The tool examples follow the same library, binary and test split but serve the runtime rather than a lesson, and each has its own deep dive:
rml-chatloads a GGUF file or Hugging Face directory with its tokenizer and chat template and holds a conversation, optionally with a draft model for speculative decoding (chat.h L4–6). Its 11 tests run against the toy GGUF models inrml/llm/testdata/models. See Generation.rml-graph-runloads an exported rml-graph model, feeds it inputs, times it and compares its outputs with stored references (graph_run.h L4–5), reading the golden fixtures in//rml/graph:testdata. See Executing a graph.tiny-netandtiny-modelsrun models thattools/make_tiny_net.pyandtools/make_tiny_models.pydefine in PyTorch, JAX and TensorFlow and export, with weights chosen so every op is exact in f32 and the output can be compared bit for bit whatever the summation order, fusion or threading (tiny_net.h L1–8, tiny_models.h L1–10). Their exports are committed under each directory'stestdata/. See Exporters and the model zoo.
Tests
Each teaching example's test does two things: checks its building blocks against something exact (a hand-computed value, finite differences, a closed form), then trains the example with a fixed seed and asserts the result its header promises. A few of those headline tests:
| Test | Asserts |
|---|---|
BeatsTheMlpWithFewerParameters | The CNN outscores the MLP on glyphs at random positions with fewer weights. |
OnlyTheLstmLearnsALongMemory | The LSTM beats predicting the mean on the adding problem; the vanilla RNN does not. |
EqualsTheConvolutionView | The step-by-step scan equals the convolution with (1, a, a², …). |
OnlyTheEncoderRecoversTheFirstHalf | The bidirectional encoder fills masked positions whose mirror lies ahead; the causal one cannot. |
SkipsDenoiseBetterAtLowNoise | The U-Net with skips beats the same network without them when the noise is small. |
QLearningTakesTheCliffEdgeAndSarsaTheSafePath | The two learners' greedy paths differ as Sutton and Barto's Example 6.6 says. |
EachObjectiveWinsTheMetricItOptimizes | Listwise (LambdaRank) wins NDCG@5 by more than 0.05; pairwise (RankNet) wins pairwise accuracy. |
ConceptDriftIsSeenOnlyByAccuracy | Under a concept change the three input and score monitors raise at most two alarms each, while the accuracy monitor fires within two days of the late labels arriving. |
GreedyRepliesMatchTheModelAlone | Speculative decoding with a draft gives the same greedy reply as the target alone. |
MatchesTheExactOutput | Every export of every tiny model reproduces its exact expected output bit for bit. |
The 156 tests are spread over the 32 test files linked in the tables above, from 2 (mlp,
cnn, rnn, finetune) to 11 (rml_chat). Ten examples mark their test
size = "large", all of them training demos; every one runs in CI with the rest of
bazel test //... (ci.yml L37).