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}