Struct TrainingRun 

pub struct TrainingRun {
    pub metadata: RunMetadata,
    /* private fields */
}

Manages the on-disk artefacts for a single training run.

Directory layout:

runs/<name>/<version>/<YYYYMMDD_HHMMSS>/
    metadata.json          ← name, version, step counts, timestamps
    config.json            ← serialized hyperparams (written by caller)
    checkpoints/
        step_<N>.mpk       ← periodic checkpoints
        latest.mpk         ← symlink-equivalent: overwritten each checkpoint
        best.mpk           ← best eval-reward checkpoint
    train_episodes.jsonl   ← one EpisodeRecord per line (training)
    eval_episodes.jsonl    ← one tagged EpisodeRecord per line (eval)

TrainingRun is not generic over the neural network backend. It manages directories and JSON; the caller (e.g. DqnTrainer) handles actual network serialization by using the paths returned by the checkpoint methods.

Usage

// Start a new run
let run = TrainingRun::create("cartpole", "v1")?;
run.write_config(&(&config, &encoder, &mapper))?;

// During training
run.log_train_episode(&episode_record)?;
run.update_metadata(total_steps, total_episodes)?;
// (save network to run.checkpoint_path(step) yourself)

// Resume
let run = TrainingRun::resume("runs/cartpole/v1")?; // picks latest

Fields

metadata: RunMetadata

Loaded/created metadata.

Implementations

impl TrainingRun

pub fn create( name: impl Into<String>, version: impl Into<String>, ) -> Result<Self>

Create a brand-new run directory under runs/<name>/<version>/<timestamp>/.

Returns an error if the directory cannot be created or metadata cannot be written.

pub fn resume(base_path: impl AsRef<Path>) -> Result<Self>

Resume the most recent run found under base_path.

base_path can be:

• An exact run directory (runs/cartpole/v1/20260322_120000) – used directly.
• A name/version directory (runs/cartpole/v1) – picks the lexicographically latest subdirectory (timestamps sort correctly).
• A name directory (runs/cartpole) – picks latest version, then latest run.

Returns an error if no run is found or metadata.json is missing/corrupt.

pub fn dir(&self) -> &Path

The root directory of this run.

pub fn write_config<T: Serialize>(&self, config: &T) -> Result<()>

Write an arbitrary serialisable value to config.json.

Typically called once after create with a tuple of (&config, &encoder, &action_mapper).

pub fn checkpoint_path(&self, step: usize) -> PathBuf

Path for a numbered checkpoint: checkpoints/step_<N>.mpk.

Pass this to DqnAgent::save (or network.save_file).

pub fn latest_checkpoint_path(&self) -> PathBuf

Path for the rolling “latest” checkpoint: checkpoints/latest.mpk.

Overwrite this on every checkpoint save so users can always resume from the most recent state without knowing the step number.

pub fn best_checkpoint_path(&self) -> PathBuf

Path for the best-eval-reward checkpoint: checkpoints/best.mpk.

pub fn prune_checkpoints(&self, keep: usize) -> Result<()>

Delete old numbered checkpoints, keeping the keep most recent.

latest.mpk and best.mpk are never deleted.

pub fn log_train_episode(&self, record: &EpisodeRecord) -> Result<()>

Append an episode record to train_episodes.jsonl.

pub fn log_eval_episode( &self, record: &EpisodeRecord, total_steps: usize, ) -> Result<()>

Append an episode record (tagged with total_steps_at_eval) to eval_episodes.jsonl.

pub fn update_metadata( &mut self, total_steps: usize, total_episodes: usize, ) -> Result<()>

Update step/episode counts and last_updated timestamp, then flush to disk.