1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
//! RL engine — the environment-driven race resume.
//!
//! One of the 2026-09-24 engine-split slices (TODO.md) out of what was the
//! single `race_engine.rs` monolith. This file holds the RL-specific
//! constructor (`resume_rl`). Everything else — the struct, the step loop,
//! evolution, artifacts — lives in [`crate::engine::core::CoreEngine`] and is
//! shared with the tabular engine.
use super::config::RaceConfig;
use super::core::{CoreEngine, RlVolume, StepEvolve, assert_trainer_blob_matches};
use crate::engine::fitness::Fitness;
use crate::state::{
RaceState, RunHeader,
};
use flodl::tensor::Result;
use std::collections::HashMap;
/// The environment-driven (RL) engine — the public handle for
/// `RunSpec::rl` runs. Wraps [`CoreEngine`]; derefs to it, so every shared
/// method is reachable directly.
pub struct RlEngine(pub(crate) CoreEngine);
impl std::ops::Deref for RlEngine {
type Target = CoreEngine;
fn deref(&self) -> &Self::Target {
&self.0
}
}
impl std::ops::DerefMut for RlEngine {
fn deref_mut(&mut self) -> &mut Self::Target {
&mut self.0
}
}
impl RlEngine {
/// Build an RL run from its spec (the `RunSpec::rl` variant IS the mode —
/// no config declaration needed or possible).
pub fn from_spec(
spec: crate::engine::run_spec::RunSpec<
Box<dyn crate::trainer::TabularStep>,
Box<dyn crate::trainer::RlStep>,
>,
) -> Result<Self> {
Ok(Self(CoreEngine::from_spec(spec)?))
}
/// Build an RL run from an [`RLSpec`] DIRECTLY — no enum wrapping.
///
/// The typed-spec path: keep your spec in a variable (or a const panel /
/// config file), tweak it, feed it here. Equivalent to
/// `RlEngine::from_spec(RunSpec::rl(..))` minus the enum round-trip; the
/// trainer is auto-boxed, so a concrete `CartPoleTrainer` goes straight
/// in.
///
/// ```ignore
/// let spec = RLSpec {
/// config: builder,
/// fitness: Fitness::reported(Direction::Maximize, "turns"),
/// trainer, // impl RlStep + 'static
/// seed: Some(42),
/// run_dir: None,
/// };
/// let mut engine = RlEngine::from_rl_spec(spec)?;
/// engine.run()?;
/// ```
pub fn from_rl_spec<T: crate::trainer::RlStep + 'static>(
spec: crate::engine::run_spec::RLSpec<T>,
) -> Result<Self> {
let crate::engine::run_spec::RLSpec {
config,
fitness,
trainer,
seed,
run_dir,
} = spec;
Ok(Self(CoreEngine::from_spec(
crate::engine::run_spec::RunSpec::rl(config, fitness, trainer, seed, run_dir),
)?))
}
/// Resume an **RL** run (no dataset) from its run directory, reusing the
/// persisted identity — the environment-driven sibling of [`crate::engine::TabularEngine::resume`].
///
/// Same contract as the tabular flavor: the seed, the net frontier and the
/// checkpoint ledger come from disk; the trainer must be the same scheme
/// the run started with; the stop criteria are **config, not state**, so
/// this is how you keep training a stopped race under a new bar
/// (`--max-target-fitness 250` on a run that stopped at `MaxSteps`).
///
/// Each live net is rebuilt from its blueprint + weight seed and replayed
/// through `0..recorded_step` with metric-parity asserts. That replay is
/// only possible when the trainer's own step is deterministic from
/// `(run_seed, net_seed, step)` — true for a pure-Rust env like CartPole
/// (match starts are seeded per net/step/match), NOT true for a scripted
/// subprocess whose world draws its own randomness (kagiculture): there the
/// parity assert fails loudly, which is the correct outcome — an RL run
/// that cannot be replayed cannot be resumed, and silently continuing with
/// wrong weights would be worse.
pub fn resume(
run_dir: std::path::PathBuf,
config: RaceConfig,
fitness: Fitness,
trainer: impl crate::trainer::RlStep + 'static,
) -> Result<Self> {
Self::resume_with(
run_dir,
config,
fitness,
Box::new(crate::trainer::ModeAdapter::rl(Box::new(trainer)))
as Box<dyn crate::trainer::EngineTrainer>,
)
}
fn resume_with(
run_dir: std::path::PathBuf,
config: RaceConfig,
fitness: Fitness,
trainer: Box<dyn crate::trainer::EngineTrainer>,
) -> Result<Self> {
let header = crate::state::load_engine_json(&run_dir)?;
// Counter snapshot before `header` moves (see the tabular flavor).
let persisted_counters = RunHeader {
culls: header.culls,
run_elapsed_secs: header.run_elapsed_secs,
children_born_at_clock: header.children_born_at_clock.clone(),
..header.clone()
};
assert_trainer_blob_matches(&header.trainer, trainer.as_ref(), "resume_rl")?;
// The persisted run must itself be RL: its frontier was trained with
// no dataset, so replaying it as tabular (or vice versa) is a bug.
// `engine_mode` is the root discriminator; legacy headers derive it
// from `config.mode` on load (same vocabulary).
if header.engine_mode.as_deref() != Some("rl") {
return Err(crate::utils::error::EngineError::InvalidOptions(format!(
"resume_rl: {} was recorded as mode \"{}\", not \"rl\" — use RaceEngine::resume with its data_dir",
run_dir.display(),
header.config.mode
))
.into());
}
let metrics = config.metrics.clone();
let run_seed = header.run_seed;
let log_level = config.log_level;
let meta_ctx = crate::engine::config::RunMetaCtx {
input_dim: header.input_dim,
output_dim: header.output_dim,
batch_size: None, // RL has no shared stream, so no batch size to record
dropout_prob: header.topology_options.dropout_prob,
fitness_label: header.fitness_label.0.clone(),
direction: format!("{:?}", header.fitness_direction).to_lowercase(),
pop_size: config.pop_size,
run_seed,
};
let mut engine = CoreEngine {
run_dir: run_dir.clone(),
header,
config,
meta_ctx,
stream: None,
dataset: None,
fitness,
metrics,
state: RaceState::new(),
history_csv_buffer: String::new(),
networks: HashMap::new(),
optimizers: HashMap::new(),
rolling_fitness: HashMap::new(),
rolling_train: HashMap::new(),
rolling_eval: HashMap::new(),
started_at_wall: std::time::Instant::now(),
elapsed_base_secs: 0,
step_started_at_wall: std::time::Instant::now(),
culls: 0,
children_born_at_clock: HashMap::new(),
step_evolve: StepEvolve::default(),
step_rl: RlVolume::default(),
total_challenged_turns: 0,
total_train_turns: 0,
expected_challenged_turns: 0.0,
step_challenged_inputs: 0,
total_challenged_inputs: 0,
expected_challenged_inputs: 0.0,
champions: Vec::new(),
checkpoints: Vec::new(),
frozen_crown: std::collections::HashSet::new(),
pruner_solo_active: false,
minimal_prev_means: None,
log_level,
interrupt_flag: None,
trainer,
};
engine.load_live_frontier()?;
// Counter restore — same contract as the tabular flavor above.
engine.culls = persisted_counters.culls;
engine.children_born_at_clock = persisted_counters.children_born_at_clock;
engine.elapsed_base_secs = persisted_counters.run_elapsed_secs;
Ok(Self(engine))
}
}