Struct ClassifyTrainer 

pub struct ClassifyTrainer { /* private fields */ }

Production training loop for classification fine-tuning.

Wraps ClassifyPipeline with:

• Epoch management with per-epoch shuffling
• Validation on a disjoint, frozen split
• Warmup + cosine decay LR scheduling
• Periodic checkpointing (SafeTensors + metadata JSON)
• Early stopping with configurable patience

Implementations

impl ClassifyTrainer

pub fn new( pipeline: ClassifyPipeline, corpus: Vec<SafetySample>, config: TrainingConfig, ) -> Result<Self>

Create a new trainer by splitting corpus into train/val sets.

Arguments

• pipeline - Initialized ClassifyPipeline
• corpus - Full dataset of labeled samples
• config - Training configuration

Errors

Returns error if corpus is empty, val_split is out of (0.0, 0.5], or epochs is 0.

pub fn set_monitor_writer(&mut self, writer: TrainingStateWriter)

Attach a monitor writer for live TUI updates.

When set, training emits per-batch metrics to the experiment directory via atomic JSON writes, enabling apr monitor <dir> from another shell.

pub fn train(&mut self) -> TrainResult

Run the full training loop.

For each epoch:

1. Shuffle training data (deterministic, seed varies per epoch)
2. Process batches via pipeline.train_batch()
3. Compute validation metrics (forward-only)
4. Step LR scheduler
5. Record metrics
6. Save checkpoint if save_every or new best val_loss
7. Check early stopping

pub fn save_checkpoint( &mut self, path: &Path, epoch: usize, metrics: &EpochMetrics, ) -> Result<()>

Save checkpoint with metadata JSON and SafeTensors model weights.

When GPU training is active, downloads GPU-updated transformer weights to CPU before saving so checkpoints include all trained parameters.

Creates: {path}/metadata.json and {path}/model.safetensors

Contract (C-CKPT-001)

• Precondition: path is a writable directory (or will be created)
• Postcondition: Checkpoint contains all trained parameters including GPU-updated transformer block weights (if GPU training active)
• Invariant: CPU model state is consistent with GPU state after save

pub fn resume_from_apr_checkpoint(&mut self, apr_path: &Path) -> Result<usize>

Resume training state from an APR checkpoint (F-CKPT-006).

Loads model weights (classifier + LoRA) and optimizer state (__training__.* tensors) from a .ckpt.apr or model.apr file.

Returns the epoch number stored in the checkpoint so the training loop can resume from the next epoch.

Errors

Returns error if checkpoint is invalid or tensors are missing.

pub fn split_dataset( data: &[SafetySample], val_ratio: f32, seed: u64, ) -> (Vec<SafetySample>, Vec<SafetySample>)

Split dataset into disjoint train/val sets.

F-LOOP-008: Guarantees zero overlap between train and val. F-LOOP-009: Val set is deterministic given the same seed.

Arguments

• data - Full dataset
• val_ratio - Fraction for validation (0.0, 0.5]
• seed - Random seed for deterministic shuffling

pub fn train_data(&self) -> &[SafetySample]

Get a reference to the training data.

pub fn val_data(&self) -> &[SafetySample]

Get a reference to the validation data.

pub fn config(&self) -> &TrainingConfig

Get a reference to the training config.

pub fn pipeline_mut(&mut self) -> &mut ClassifyPipeline

Get a mutable reference to the underlying pipeline.

pub fn run_worker(&mut self) -> Result<TrainResult>

Run as a distributed worker node.

Connects to the coordinator, then enters a loop:

1. Receive shard assignment (or shutdown)
2. Compute forward/backward on assigned shard
3. Collect LoRA gradients and send to coordinator
4. Receive averaged gradients and apply optimizer step

Contract: F-DP-001 (Weight Consistency)

After applying averaged gradients, worker weights match coordinator weights.

Errors

Returns error on connection failure or protocol violation.

pub fn evaluate( &mut self, data: &[SafetySample], label_names: &[String], ) -> ClassifyEvalReport

Evaluate the model on a dataset, returning structured per-class metrics.

Runs forward-only on every sample, collects predictions, and computes precision/recall/F1/confusion matrix via ConfusionMatrix and MultiClassMetrics.

Arguments

• data - Labeled samples to evaluate on
• label_names - Human-readable class names (length must match num_classes)

Trait Implementations

impl Debug for ClassifyTrainer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.