Linear algebra you can step through.
Contiguous row-major tensors, explicit shapes and strides, checked broadcasting, batched matmul, reductions, indexing, and backend-owned storage.
Tensor [batch, time, feature]
Tensor contract →
Version 0.6.1 · C++20 · Apache-2.0
Build the transformer stack.
See every layer.
An auditable decoder-only Transformer stack: Python owns training and research orchestration, while the C++20 runtime owns tensor math, autograd, models, Adam, serving primitives, accelerators, and programs compiled into attention.
0Python runtime dependencies
Debugfull suite green
4backend contracts
01
TokenizeUTF-8 → byte / BPE ids
[B,T]
02
Embedtoken + absolute position
[B,T,D]
03
Attendcausal multi-head attention
[B,H,T,T]
04
Differentiatereverse graph + custom VJPs
∂L/∂θ
05
UpdateAdam · clipped · paged
θₜ₊₁
Readable reference math×
Strict shape contracts×
Backend-neutral APIs×
Measured generalization×
Inspectable representations
The framework
One stack, separated by responsibility.
The readable CPU path defines the numerical contract. Python composes datasets, training loops, evaluation, and labs; C++ implements reusable computation, serving, compilation, and analysis primitives behind stable boundaries.
01DataByte/BPE tokenization
next-token batches 02CoreTensors · operations
autograd · NF4 03ModelAttention · FFN
decoder blocks 04TrainPython control loop
C++ loss · backward · Adam 05ServeGeneration
paged KV cache
next-token batches 02CoreTensors · operations
autograd · NF4 03ModelAttention · FFN
decoder blocks 04TrainPython control loop
C++ loss · backward · Adam 05ServeGeneration
paged KV cache
Reverse mode without magic.
Fresh operation graphs, reverse-topological traversal, gradient accumulation, finite-difference checks, custom VJPs, and activation checkpoint replay.
Follow backward →Every residual path exposed.
Pre-normalized blocks, materialized or exact memory-linear Flash attention, GELU/ReLU feed-forwards, and a causal language-model head.
Model anatomy →Choose the memory contract.
Full fine-tuning, low-rank adapters, or QLoRA with frozen blockwise NF4 weights, double-quantized scales, and bounded-page Adam state.
Packed-weight training →Compile finite programs into attention.
Cajal-lite compilation plus dense or sparse map import feeds configurable neural lowering and the generic task-neutral program-augmented model.
program→map→lower→composeObserve, intervene, verify.
Stable named traces and differentiable batch-roll/steering sites feed model-neutral PCA and paired causal analysis outside the model.
Analysis stage →
Quick start
From install to first gradient.
Use the dependency-free Python surface for training and labs, link focused native CMake targets for reusable primitives, or build the stack from source. Python calls the same C++ runtime through the stable C ABI.
- Python 3.10+ with no runtime packages
- C++20 and CMake 3.24+
- CPU everywhere; Metal in macOS builds
python3 -m pip install riftco-transformer
python3 -c \
"from riftco_transformer import Context; \
print(Context().backend)"git clone https://github.com/quangng2000/riftco-transformer.git
cd riftco-transformer
cmake --preset debug
cmake --build --preset debug
ctest --preset debugPYTHONPATH=python:. python3 -m \
labs.conditional_reverse.run \
--profile quick --variants F \
--backend cpu \
--output runs/conditional-reverse/quick.json
# Verify current flags with --help.Execution backends
One contract. Different hardware.
Backend identity belongs to tensor storage. Operations validate shapes and placement, then dispatch through focused storage, math, attention, quantized-linear, and optimizer capabilities.
Reference
Portable CPU
The complete readable oracle, available in every build.
- FP32 + packed NF4
- Materialized + Flash attention
- Paged decode + Adam
Native
Apple Metal
Persistent shared buffers and native compute kernels on compatible Macs.
- Matmul + neural operations
- Attention forward/VJPs
- NF4 + fused Adam update
Optional
NVIDIA CUDA
Toolkit 12+ source build with managed storage and native kernels.
- Source-integrated path
- Hardware acceptance pending
- Unavailable wheel stub
Experimental
Cloud TPU
Linux x86-64 PJRT/StableHLO adapter requiring external libtpu.
- Host-mirrored storage
- Fake-PJRT CI coverage
- Real-device validation pending
Honest boundary: accelerator selection does not imply every operation is device-resident or faster. Autograd scheduling, safety checks, and some reference paths remain host-controlled. Capability matrix →
Conditional-reversal lab
Can a program become a Transformer head?
The framework now exposes generic compilation, lowering, ProgramAugmentedModel execution, stable traces, interventions, and target-time-range loss through ABI 2.8 and riftco_transformer.programmed. The Python lab owns sparse F/P/T/I specifications, data, training, evaluation, analysis, and reports.
F frozen compiled
P reverse-only control
T trainable random
I no program
Current ABI 2.5 Metal run
seed 42 · paper F
100%held-out exact sequences
790Adam steps
2m 39sM4 Max runtime
95.80ppprogram resample
copy-hypothesis agreement60.62%
reverse-hypothesis agreement79.53%
Scope: one clean, source-disjoint, current Python-lab run. Program resampling was causal; PCA was descriptive. Selector values come from multiplicative basis masking on a 386-example balanced held-out subset. This is not a multi-seed paper reproduction or a hardware benchmark.
Reviewed run record ↗Composition
Link only what you use.
Exported targets encode the dependency direction, keeping the compiler and interpretation algorithms independent from the tensor runtime.
runtime
riftco_transformer::library
riftco_transformer::c_api · ABI 2.8
programming
riftco_transformer::compiler
riftco_transformer::lowering
riftco_transformer::programmed
Python composition + labs
riftco_transformer::analysis
riftco_transformer.programmed
labs/* · repository only
Documentation
Choose your intent. Follow it to the code.
Learn progressively, solve a focused task, understand a concept, or look up an exact interface. Every page remains connected to its maintained source.
01
Get started
Install, build, and run a verified first example.
02
Learn
Build understanding from tensors through the decoder stack.
03
How-to guides
Complete focused training, adaptation, and serving tasks.
04
Concepts
Understand the algorithms, contracts, and system boundaries.
05
Reference
Look up public APIs, configuration, commands, and terms.
06
Internals & backends
Trace ownership, dispatch, kernels, and extension seams.
07
Experiments
Read protocols, evidence, limitations, and interpretation results.
08
Contributing
Build, test, document, and extend the framework consistently.
Designed to stay honest
What it does not claim.
- No PyTorch or JAX underneath. Python is a typed
ctypessurface over this native runtime. - No production-scale serving claim. Continuous batching, shared-prefix caching, and async scheduling remain future work.
- No general lambda calculus. Cajal-lite is finite, first-order, and deliberately bounded.
- No broad generalization proof. The framework enforces leakage-safe evaluation; it cannot establish factuality, safety, or OOD robustness by itself.