Realm

The NLP tutorial suite

Source-owned OA v0.12.0 SDK tutorial. Recorded results qualify the named device and driver.

Experimental

Status: Experimental. The recorded GPU results qualify the named device and driver; they do not establish cross-device numerical equivalence.

Sixteen tutorials that are really one advanced example: the same corpus, recipe, and training loop run across a matrix of three tokenizers and five model architectures. Start with — it is the introductory walkthrough; the other entries explore tokenizers and architectures; the Empyrealm row also changes the model topology.

The shared base

Every entry runs the identical workload, defined once in sdk/rs/lib/ml/nlp.rs:

KnobValue
Corpus192-char Hamlet excerpt ×3 = 576 characters
Context16 tokens per sequence
Recipe300 steps · batch 64 · AdamW(lr=0.01; Mamba-3/Empyrealm: 0.003)
Taskdense next-token prediction at every position
Self-testloss regime, accuracy floor, exact reference generation

The loop is one prepare/record pair per step driven by oa::ml::ItTraining, with GradientTape → backward → AdamW inside the record closure. Because the step shape never changes, each run is a single captured GPU program replayed 299 times — the run's own diagnostics line reports it (19 nodes · 1 recording · 299 cache hits for the RNN row). Char and Byte metrics stream to var/log/nlp/<timer_name>/events.jsonl, and every tutorial ends by proving .oam checkpoint round-trip: identical optimizer step count, accuracy, and greedy generation.

Shared helpers: _byte_common.rs and _bpe_common.rs drive the 11 Byte/BPE entries through a Tutorial descriptor; the Char entries are standalone with the same structure. The Python suite mirrors this through its own _nlp_common.py — see its suite root.

The three tokenizers — the first axis

TokenizerVocabRandom baselineNotes
char_*27 (a-z + space)ln(27) = 3.296simplest; accuracy comparable within Char only
byte_*256 (packed U8)ln(256) = 5.545raw bytes, one token per byte
bpe_*320 (256 + 64 merges)ln(320) = 5.768learned merges, ~2.4–2.8× fewer positions

Loss and accuracy are not comparable across tokenizers — different vocab sizes shift both scales. BPE rows correctly reach ~0.02 loss / 98.8% accuracy because merges collapse the corpus into short, predictable token runs. The comparable signal is inside each row group.

The five architectures — the second axis

ArchSkeletonCharacter
*_rnnEmbedding → Elman RNN(64) → Linearcheapest step; sequential scan
*_gruEmbedding → GRU(64) → Lineargated recurrence; slowest per step
*_transformer+pos Embedding → TransformerBlock → LN → Linearcausal attention; fastest non-recurrent
*_moe/char_moe_transformerattention → sparse MoE (E=4, K=2, DFF=16)routed experts; widest program (62 nodes)
*_mamba3Embedding → Mamba-3(32, state=32, expand=2) + residual → Linearselective state-space recurrence
byte_empyrealmEmpyrealm hybrid stack (Mamba-3/attention)fidelity topology — same Mamba-3 providers, different module shape; 184-node program

The matrix

15 public cells + the Empyrealm fidelity row = 16 executable entries:

Measured: 16/16, Surface Laptop 5 (ADL GT2)

Condensed from the surface-laptop-5-2026-11-15 benchmark report — serial pass on an idle GPU, canonical recipe per entry:

EntryLoss init→finalAccNodesWall ms/stepToken/sGPU msGap
char_rnn3.311→0.18692.5%194.75215.5K4.0714%
char_gru3.293→0.18392.8%1913.2277.5K12.247%
char_transformer4.041→0.20092.4%445.95172.2K4.9417%
char_moe_transformer3.514→0.19092.6%628.41121.8K7.1815%
char_mamba33.303→0.19593.0%3410.6995.8K9.3313%
byte_rnn5.569→0.19192.2%197.98128.3K6.9813%
byte_gru5.618→0.17892.7%1915.0867.9K14.017%
byte_transformer5.657→0.20192.9%467.85130.5K6.8113%
byte_moe5.687→0.19992.6%649.86103.9K8.9010%
byte_mamba35.539→0.21493.0%3411.6887.7K10.748%
byte_empyrealm5.667→0.18292.9%18440.2025.5K38.684%
bpe_rnn5.774→0.02198.8%198.40121.9K6.9218%
bpe_gru5.766→0.02198.8%1914.7969.2K13.807%
bpe_transformer5.871→0.02198.9%447.51136.3K6.4015%
bpe_moe5.844→0.02098.8%6210.4398.2K9.2911%
bpe_mamba35.775→0.02098.9%3412.2383.7K11.109%

Reading: GRU is the slowest family (recurrent serialization, 13–15 ms/step); RNN and Transformer are fastest (~5–8 ms); byte_empyrealm is the structural outlier at 184 nodes — the fidelity topology, not the shared Mamba-3 providers, sets its cost. The wall−GPU gap column is the per-step host/submission boundary, tracked as OA-CC-02. Full table with p50/p95 and byte-rate columns lives in the benchmark report.

Run

Every tutorial page displays its own asset/training-curve.png, generated by that Rust entry with the canonical 300-step recipe. Each page includes the command to regenerate its image from the repository root.

# one entry
cargo run --release -p sdk --example tu_nlp_char_rnn
# all sixteen
for e in char_rnn char_gru char_transformer char_moe_transformer char_mamba3 \
byte_rnn byte_gru byte_transformer byte_moe byte_mamba3 byte_empyrealm \
bpe_rnn bpe_gru bpe_transformer bpe_moe bpe_mamba3; do
cargo run --release -p sdk --example tu_nlp_$e || break
done

Every entry accepts --steps and --plot. Char entries additionally accept --batch and --lr. Use --plot out.png to render the loss curve through oa::plot. The Python suite runs the same matrix via run_nlp_suite.py — see .