# Rustral

Overview

Rustral is a 24-crate Rust neural network framework for auditable, backend-agnostic NLP research. It is designed around three commitments unusual in the deep learning framework landscape. First, no hidden global state: every forward pass receives an explicit ForwardCtx carrying backend, training/inference mode, run ID, shape policy, and optional profiler — there is no silent model.train()/model.eval() toggle or global tensor registry. Second, backend-independent model definitions: layers written against Backend and TensorOps traits run unchanged on a reference CPU backend with ndarray and SIMD, an optimized Candle backend with CUDA and Metal, and an experimental WGPU backend with native WGSL compute shaders. Third, reproducibility by construction: every benchmark, NLP training run, and LLM inference run emits a schema-validated JSON manifest recording machine metadata, git SHA, dataset checksums, hyperparameters, and raw timing distributions with 95% confidence intervals, validated in CI. The workspace ships with 700+ tests enforcing these contracts. Rustral also includes a systematic cross-framework operator benchmark and proposes Cross-Backend Consistency Regularization as a technique for keeping model behavior stable across backends.

Problem

Mainstream deep learning frameworks hide global state (silent train/eval toggles, global tensor registries), couple model definitions to specific backends, and make reproducibility an afterthought. This makes NLP research audits painful and cross-framework benchmarking unreliable.

Approach

Every forward pass receives an explicit ForwardCtx carrying backend, training/inference mode, run ID, shape policy, and optional profiler — no silent model.train()/model.eval() toggle or global tensor registry. Layers written against Backend and TensorOps traits run unchanged on a reference CPU backend (ndarray + SIMD), an optimized Candle backend (CUDA/Metal), and an experimental WGPU backend with native WGSL compute shaders. Every benchmark, training run, and inference run emits a schema-validated JSON manifest recording machine metadata, git SHA, dataset checksums, hyperparameters, and raw timing distributions with 95% confidence intervals, validated in CI.

Impact

• * 24-crate workspace with 700+ tests enforcing the no-hidden-state and reproducibility contracts.
• * Three interchangeable backends (ndarray/SIMD CPU, Candle CUDA/Metal, WGPU) running the same model definitions unchanged.
• * Schema-validated JSON manifests with machine metadata, git SHA, dataset checksums, and timing distributions make every run independently reproducible.
• * Cross-framework operator benchmarking and a proposed Cross-Backend Consistency Regularization technique.