Struct TransformerTrainer 

pub struct TransformerTrainer {
    pub metrics: MetricsTracker,
    /* private fields */
}

Transformer training state

Fields

metrics: MetricsTracker

Metrics tracker

Implementations

impl TransformerTrainer

pub fn new(config: TransformerTrainConfig) -> Self

Create a new transformer trainer

pub fn with_model(model: Transformer, config: TransformerTrainConfig) -> Self

Create trainer from existing model

pub fn forward_single( &self, input_ids: &[u32], target_ids: &[u32], ) -> (f32, Tensor, Tensor)

Forward pass on a single batch item

Returns (loss_value, loss_tensor, logits) When LoRA is active, routes through forward_with_lora so only LoRA adapter gradients are accumulated.

pub fn train_batch(&mut self, batch: &LMBatch) -> f32

Process a batch (forward + backward + optimizer step)

Returns average loss for the batch

pub fn train_epoch(&mut self, batches: &[LMBatch]) -> f32

Train for one epoch over batches

pub fn train_epoch_with_callback<F>( &mut self, batches: &[LMBatch], on_batch: F, ) -> f32

where F: FnMut(usize, f32, &Self),

Train for one epoch with a per-step callback.

The callback receives (batch_index, batch_loss, &self) after each batch. Use this for progress logging, checkpointing, or early stopping.

Stops early if max_steps is set and the step count reaches it. Returns (avg_loss, reached_max_steps).

pub fn reached_max_steps(&self) -> bool

Returns true if max_steps has been reached.

pub fn step(&self) -> usize

Get current step count

pub fn model(&self) -> &Transformer

Get reference to model

pub fn model_mut(&mut self) -> &mut Transformer

Get mutable reference to model

pub fn current_lr(&self) -> f32

Get current learning rate (with warmup applied)

pub fn grad_scaler_stats(&self) -> (f32, usize, usize)

Get gradient scaler stats

pub fn is_mixed_precision(&self) -> bool

Check if using mixed precision

pub fn is_checkpointing(&self) -> bool

Check if using gradient checkpointing

pub fn is_lora(&self) -> bool

Check if LoRA training is active

pub fn lora_layers(&self) -> Option<&[LoRALayer]>

Get reference to LoRA layers (for checkpoint saving)

pub fn lora_layers_mut(&mut self) -> Option<&mut Vec<LoRALayer>>

Get mutable reference to LoRA layers

pub fn save_lora_adapter( &self, output_dir: impl AsRef<Path>, base_model_name: Option<&str>, ) -> Result<()>

Save LoRA adapter in PEFT-compatible format (ENT-LoRA-003)

Saves only LoRA A/B weights as adapter_model.safetensors + adapter_config.json. Adapter checkpoint is typically <1% of full model size.

Arguments

• output_dir - Directory to save adapter files
• base_model_name - Optional HuggingFace model ID for adapter_config.json

Errors

Returns error if not in LoRA mode or I/O fails.

pub fn save( &self, path: impl AsRef<Path>, name: &str, architecture: &str, ) -> Result<()>

Save model weights to a SafeTensors file

This persists the trained transformer weights to disk. Call this after training completes to preserve the learned parameters.

Arguments

• path - Output file path (should end in .safetensors)
• name - Model name for metadata
• architecture - Model architecture description (e.g., “Qwen2ForCausalLM”)

Errors

Returns an error if the file cannot be written.

pub fn save_apr( &self, path: impl AsRef<Path>, name: &str, architecture: &str, ) -> Result<()>

Save model weights in the sovereign APR format.

Mirror of CudaTransformerTrainer::save_apr for the CPU path. APR is the row-major atomic single-file format shared across training and inference (per aprender-train CLAUDE.md LAYOUT-002 mandate), so training checkpoints emitted by PretrainLoop load directly in realizar / apr run with no re-transpose.

Arguments

• path - Output file path (should end in .apr)
• name - Model name for metadata
• architecture - Model architecture description (e.g., "LlamaForCausalLM")

pub fn optimizer_state_sha256(&self) -> String

sha256 over the AdamW optimizer state bytes (INV-TRAIN-003).

Hashes (t, m_buffers, v_buffers) in fixed order so two runs with matching hyperparameters, seed, and batch order produce the same digest (GATE-TRAIN-006 reproducibility).

Uninitialized buffers (before the first step) hash to the tag "none" so they still participate deterministically in the digest — missing m[i] is semantically distinct from an all-zeros m[i].