Skip to main content

gras/engine/
run_spec.rs

1//! The one bundle a caller hands the engine to start a race — one variant per run mode (see
2//! [`RunSpec`]).
3
4use crate::engine::config::RaceConfig;
5use crate::trainer::{RlStep, TabularStep};
6use crate::utils::fitness::Fitness;
7
8/// Start-a-race spec: the entire `new` argument surface. `fitness`
9/// ranking signal; the loss lives on your `trainer`.
10pub struct TabularSpec<T = Box<dyn TabularStep>> {
11    /// Dataset directory the engine loads.
12    pub data_dir: std::path::PathBuf,
13    /// The one `RaceConfig` (no training knobs — those live on the trainer).
14    pub config: RaceConfig,
15    /// Ranking signal (engine-computed for tabular runs).
16    pub fitness: Fitness,
17    /// Your training scheme, self-contained and auto-boxed.
18    pub trainer: T,
19    /// `None` = random seed (recorded in `engine.json`).
20    pub seed: Option<u64>,
21    /// `None` = `results/<run_id>` with a timestamp id.
22    pub run_dir: Option<std::path::PathBuf>,
23}
24
25/// RL spec: the run learns from an ENVIRONMENT the trainer drives, not a dataset;
26/// the only ranking input is the `StepReport.fitness` the trainer reports.
27pub struct RLSpec<T = Box<dyn RlStep>> {
28    /// The one `RaceConfig`.
29    pub config: RaceConfig,
30    /// MUST be `Fitness::reported(..)` — validated at engine construction.
31    pub fitness: Fitness,
32    /// Your environment-driving training scheme, auto-boxed.
33    pub trainer: T,
34    /// `None` = random seed (recorded in `engine.json`).
35    pub seed: Option<u64>,
36    /// `None` = `results/<run_id>` with a timestamp id.
37    pub run_dir: Option<std::path::PathBuf>,
38}
39
40/// Start-a-race spec — one variant per run mode, each self-contained,
41/// compiler enforces exactly each mode's requirement set.
42pub enum RunSpec<TT = Box<dyn TabularStep>, TR = Box<dyn RlStep>> {
43    /// Supervised tabular run: `data_dir` + engine-computed fitness.
44    Tabular(TabularSpec<TT>),
45    /// Environment/RL run: no dataset, `Fitness::reported`, env-driving trainer.
46    RL(RLSpec<TR>),
47}
48
49impl RunSpec<Box<dyn TabularStep>, Box<dyn RlStep>> {
50    /// Convenience constructor for the Tabular variant — path fields coerce via
51    /// `Into<PathBuf>`; `run_dir: None` uses `results/<timestamp>`.
52    pub fn tabular<P: Into<std::path::PathBuf>>(
53        data_dir: impl Into<std::path::PathBuf>,
54        mut config: RaceConfig,
55        fitness: Fitness,
56        trainer: impl TabularStep + 'static,
57        seed: Option<u64>,
58        run_dir: Option<P>,
59    ) -> Self {
60        // The spec variant DECIDES the mode arm: stamp the Tabular arm, replacing
61        // whatever placeholder the builder carried.
62        config.mode_specific = crate::engine::config::ModeConfig::Tabular;
63        Self::Tabular(TabularSpec {
64            data_dir: data_dir.into(),
65            config,
66            fitness,
67            trainer: Box::new(trainer),
68            seed,
69            run_dir: run_dir.map(|p| p.into()),
70        })
71    }
72
73    /// Convenience constructor for the RL variant: no `data_dir`, and `fitness`
74    /// MUST be [`Fitness::reported`] (a `Computed` scorer has nothing to score).
75    pub fn rl(
76        mut config: RaceConfig,
77        fitness: Fitness,
78        trainer: impl RlStep + 'static,
79        seed: Option<u64>,
80        run_dir: Option<std::path::PathBuf>,
81    ) -> Self {
82        // The spec variant DECIDES the mode arm (see `tabular`).
83        config.mode_specific = crate::engine::config::ModeConfig::Rl;
84        Self::RL(RLSpec {
85            config,
86            fitness,
87            trainer: Box::new(trainer),
88            seed,
89            run_dir,
90        })
91    }
92}
93
94// Deliberately no engine-side "default trainer": a run without a trainer is a type error,
95// stays true now that one reference scheme ships (`trainer::TabularTrainer`) — a spec still names
96
97/// Stream shape request — what the trainer wants the shared batch stream to look
98/// like (returned from `TabularStep::stream_shape`); the engine applies
99#[derive(Clone, Copy, Debug)]
100pub struct StreamShape {
101    /// Rows per shared train batch.
102    pub batch_size: usize,
103    /// Rows per shared eval batch.
104    pub eval_batch_size: usize,
105}
106
107impl StreamShape {
108    /// No override — use the engine's default stream shape (batch_size
109    /// the trainer's default + eval_batch_size == batch_size).
110    pub fn none() -> Self {
111        Self {
112            batch_size: 16,
113            eval_batch_size: 16,
114        }
115    }
116
117    /// Override the train batch size for the shared stream.
118    pub fn with_batch_size(mut self, n: usize) -> Self {
119        self.batch_size = n;
120        self
121    }
122
123    /// Override the eval batch size for the shared stream.
124    pub fn with_eval_batch_size(mut self, n: usize) -> Self {
125        self.eval_batch_size = n;
126        self
127    }
128
129    /// Convenience for the common case: same size for train + eval.
130    pub fn uniform(n: usize) -> Self {
131        Self {
132            batch_size: n,
133            eval_batch_size: n,
134        }
135    }
136}