use crate::graph::network::Network;
use crate::utils::tabular_data::Dataset;
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct StepReport {
pub train_loss: f32,
pub eval_loss: Option<f32>,
pub fitness: f32,
pub informative: Vec<f32>,
#[serde(default)]
pub challenged_inputs: usize,
#[serde(default)]
pub challenged_turns: usize,
#[serde(default)]
pub rl: Option<RlStepMeta>,
}
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct TabularStepReport {
pub train_loss: f32,
pub eval_loss: Option<f32>,
pub fitness: f32,
pub informative: Vec<f32>,
#[serde(default)]
pub challenged_inputs: usize,
}
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct RlStepReport {
pub train_loss: f32,
pub fitness: f32,
pub informative: Vec<f32>,
#[serde(default)]
pub challenged_turns: usize,
pub rl: Option<RlStepMeta>,
}
impl From<TabularStepReport> for StepReport {
fn from(r: TabularStepReport) -> Self {
StepReport {
train_loss: r.train_loss,
eval_loss: r.eval_loss,
fitness: r.fitness,
informative: r.informative,
challenged_inputs: r.challenged_inputs,
challenged_turns: 0, rl: None, }
}
}
impl From<RlStepReport> for StepReport {
fn from(r: RlStepReport) -> Self {
StepReport {
train_loss: r.train_loss,
eval_loss: None, fitness: r.fitness,
informative: r.informative,
challenged_inputs: 0, challenged_turns: r.challenged_turns,
rl: r.rl,
}
}
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct RlStepMeta {
pub matches: usize,
#[serde(default)]
pub train_turns: usize,
#[serde(default)]
pub eval_turns: usize,
}
impl RlStepMeta {
pub fn turns(&self) -> usize {
self.train_turns + self.eval_turns
}
}
#[derive(Clone, Copy, Debug)]
pub struct StepEnv {
pub step: usize,
pub run_seed: u64,
pub pop_size: usize,
pub live_count: usize,
pub checkpoint_every: usize,
pub smoothing_window: usize,
pub max_steps: Option<usize>,
}
impl StepEnv {
pub fn progress(&self) -> Option<f32> {
crate::engine::config::run_progress(self.step, self.max_steps)
}
}
pub struct RunData<'a> {
pub dataset: &'a Dataset,
pub stream: &'a crate::trainer::stream::BatchStream,
}
impl RunData<'_> {
pub fn train_batch(&self, step: u64) -> flodl::tensor::Result<(flodl::Tensor, flodl::Tensor)> {
self.stream.train_batch(self.dataset, step)
}
pub fn eval_batch(&self, step: u64) -> flodl::tensor::Result<(flodl::Tensor, flodl::Tensor)> {
self.stream.eval_batch(self.dataset, step)
}
}
pub struct TabularContext<'a> {
pub data: RunData<'a>,
pub fitness: &'a crate::engine::fitness::Fitness,
pub metrics: &'a [crate::engine::fitness::Metric],
pub env: StepEnv,
pub net_hash: &'a str,
pub net_seed: u64,
pub challenged: bool,
pub challenge_prob: f32,
}
pub struct RlContext<'a> {
pub fitness: &'a crate::engine::fitness::Fitness,
pub metrics: &'a [crate::engine::fitness::Metric],
pub env: StepEnv,
pub net_hash: &'a str,
pub net_seed: u64,
pub challenged: bool,
}
#[derive(Clone, Copy, Debug)]
pub struct StreamShape {
pub batch_size: usize,
pub eval_batch_size: usize,
}
impl StreamShape {
pub fn none() -> Self {
Self {
batch_size: 16,
eval_batch_size: 16,
}
}
pub fn uniform(n: usize) -> Self {
Self {
batch_size: n,
eval_batch_size: n,
}
}
}
pub trait StepTrainer: Send {
fn make_optimizer(&self, net: &Network) -> Box<dyn flodl::nn::optim::Optimizer>;
fn describe(&self) -> Option<serde_json::Value> {
None
}
fn holdout_score(&mut self, _net: &mut Network, _game_i: usize) -> flodl::tensor::Result<f32> {
unimplemented!(
"holdout_score is not implemented for this trainer — implement it (one fresh \
game, same units as the reported fitness) to use engine.guardrail()"
)
}
fn holdout_matches(&self) -> Option<usize> {
None
}
}
pub trait TabularStep: StepTrainer {
fn loss(&self) -> crate::trainer::LossFn<'_>;
fn scheduled_lr(&self, _step: usize) -> Option<f64> {
None
}
fn stream_shape(&self) -> Option<StreamShape> {
None
}
fn train_step(
&mut self,
net: &mut Network,
optimizer: &mut dyn flodl::nn::optim::Optimizer,
step: usize,
ctx: &TabularContext<'_>,
) -> flodl::tensor::Result<TabularStepReport>;
}
pub trait RlStep: StepTrainer {
fn train_step(
&mut self,
net: &mut Network,
optimizer: &mut dyn flodl::nn::optim::Optimizer,
step: usize,
ctx: &RlContext<'_>,
) -> flodl::tensor::Result<RlStepReport>;
fn pop_phase(&mut self, _nets: &mut [(String, &mut Network)], _step: usize) {}
}
pub trait EngineTrainer: Send {
fn make_optimizer(&self, net: &Network) -> Box<dyn flodl::nn::optim::Optimizer>;
fn describe(&self) -> Option<serde_json::Value>;
fn pop_phase(&mut self, nets: &mut [(String, &mut Network)], step: usize);
#[allow(clippy::too_many_arguments)]
fn train_step(
&mut self,
net: &mut Network,
optimizer: &mut dyn flodl::nn::optim::Optimizer,
step: usize,
data: Option<&RunData<'_>>,
fitness: &crate::engine::fitness::Fitness,
metrics: &[crate::engine::fitness::Metric],
env: StepEnv,
net_hash: &str,
net_seed: u64,
challenged: bool,
challenge_prob: f32,
) -> flodl::tensor::Result<StepReport>;
fn holdout_score(&mut self, net: &mut Network, game_i: usize) -> flodl::tensor::Result<f32> {
let _ = (net, game_i);
unimplemented!(
"holdout_score is not implemented for this trainer — implement it (one fresh \
game, same units as the reported fitness) to use engine.guardrail()"
)
}
fn holdout_matches(&self) -> Option<usize> {
None
}
fn is_rl(&self) -> bool;
fn tabular_loss(&self) -> Option<super::LossFn<'_>>;
fn stream_shape(&self) -> Option<StreamShape> {
None
}
}
pub struct ModeAdapter<T: Send + 'static> {
inner: T,
}
impl ModeAdapter<Box<dyn TabularStep>> {
pub fn tabular(inner: Box<dyn TabularStep>) -> Self {
Self { inner }
}
}
impl ModeAdapter<Box<dyn RlStep>> {
pub fn rl(inner: Box<dyn RlStep>) -> Self {
Self { inner }
}
}
impl EngineTrainer for ModeAdapter<Box<dyn TabularStep>> {
fn make_optimizer(&self, net: &Network) -> Box<dyn flodl::nn::optim::Optimizer> {
self.inner.make_optimizer(net)
}
fn describe(&self) -> Option<serde_json::Value> {
self.inner.describe()
}
fn pop_phase(&mut self, _nets: &mut [(String, &mut Network)], _step: usize) {}
fn train_step(
&mut self,
net: &mut Network,
optimizer: &mut dyn flodl::nn::optim::Optimizer,
step: usize,
data: Option<&RunData<'_>>,
fitness: &crate::engine::fitness::Fitness,
metrics: &[crate::engine::fitness::Metric],
env: StepEnv,
net_hash: &str,
net_seed: u64,
challenged: bool,
challenge_prob: f32,
) -> flodl::tensor::Result<StepReport> {
let data =
data.expect("Tabular step without data — engine construction invariant violated");
let ctx = TabularContext {
data: RunData {
dataset: data.dataset,
stream: data.stream,
},
fitness,
metrics,
env,
net_hash,
net_seed,
challenged,
challenge_prob,
};
Ok(self.inner.train_step(net, optimizer, step, &ctx)?.into())
}
fn holdout_score(&mut self, net: &mut Network, game_i: usize) -> flodl::tensor::Result<f32> {
self.inner.holdout_score(net, game_i)
}
fn holdout_matches(&self) -> Option<usize> {
self.inner.holdout_matches()
}
fn is_rl(&self) -> bool {
false
}
fn tabular_loss(&self) -> Option<super::LossFn<'_>> {
Some(self.inner.loss())
}
fn stream_shape(&self) -> Option<StreamShape> {
self.inner.stream_shape()
}
}
impl EngineTrainer for ModeAdapter<Box<dyn RlStep>> {
fn make_optimizer(&self, net: &Network) -> Box<dyn flodl::nn::optim::Optimizer> {
self.inner.make_optimizer(net)
}
fn describe(&self) -> Option<serde_json::Value> {
self.inner.describe()
}
fn pop_phase(&mut self, nets: &mut [(String, &mut Network)], step: usize) {
self.inner.pop_phase(nets, step)
}
fn train_step(
&mut self,
net: &mut Network,
optimizer: &mut dyn flodl::nn::optim::Optimizer,
step: usize,
_data: Option<&RunData<'_>>,
fitness: &crate::engine::fitness::Fitness,
metrics: &[crate::engine::fitness::Metric],
env: StepEnv,
net_hash: &str,
net_seed: u64,
challenged: bool,
_challenge_prob: f32,
) -> flodl::tensor::Result<StepReport> {
let ctx = RlContext {
fitness,
metrics,
env,
net_hash,
net_seed,
challenged,
};
Ok(self.inner.train_step(net, optimizer, step, &ctx)?.into())
}
fn holdout_score(&mut self, net: &mut Network, game_i: usize) -> flodl::tensor::Result<f32> {
self.inner.holdout_score(net, game_i)
}
fn holdout_matches(&self) -> Option<usize> {
self.inner.holdout_matches()
}
fn is_rl(&self) -> bool {
true
}
fn tabular_loss(&self) -> Option<super::LossFn<'_>> {
None
}
}
impl StepTrainer for Box<dyn StepTrainer> {
fn make_optimizer(&self, net: &Network) -> Box<dyn flodl::nn::optim::Optimizer> {
self.as_ref().make_optimizer(net)
}
fn describe(&self) -> Option<serde_json::Value> {
self.as_ref().describe()
}
fn holdout_score(&mut self, net: &mut Network, game_i: usize) -> flodl::tensor::Result<f32> {
self.as_mut().holdout_score(net, game_i)
}
fn holdout_matches(&self) -> Option<usize> {
self.as_ref().holdout_matches()
}
}
impl TabularStep for Box<dyn TabularStep> {
fn loss(&self) -> crate::trainer::LossFn<'_> {
self.as_ref().loss()
}
fn scheduled_lr(&self, step: usize) -> Option<f64> {
self.as_ref().scheduled_lr(step)
}
fn stream_shape(&self) -> Option<StreamShape> {
self.as_ref().stream_shape()
}
fn train_step(
&mut self,
net: &mut Network,
optimizer: &mut dyn flodl::nn::optim::Optimizer,
step: usize,
ctx: &TabularContext<'_>,
) -> flodl::tensor::Result<TabularStepReport> {
self.as_mut().train_step(net, optimizer, step, ctx)
}
}
impl RlStep for Box<dyn RlStep> {
fn train_step(
&mut self,
net: &mut Network,
optimizer: &mut dyn flodl::nn::optim::Optimizer,
step: usize,
ctx: &RlContext<'_>,
) -> flodl::tensor::Result<RlStepReport> {
self.as_mut().train_step(net, optimizer, step, ctx)
}
fn pop_phase(&mut self, nets: &mut [(String, &mut Network)], step: usize) {
self.as_mut().pop_phase(nets, step)
}
}
impl StepTrainer for Box<dyn TabularStep> {
fn make_optimizer(&self, net: &Network) -> Box<dyn flodl::nn::optim::Optimizer> {
self.as_ref().make_optimizer(net)
}
fn describe(&self) -> Option<serde_json::Value> {
self.as_ref().describe()
}
fn holdout_score(&mut self, net: &mut Network, game_i: usize) -> flodl::tensor::Result<f32> {
self.as_mut().holdout_score(net, game_i)
}
fn holdout_matches(&self) -> Option<usize> {
self.as_ref().holdout_matches()
}
}
impl StepTrainer for Box<dyn RlStep> {
fn make_optimizer(&self, net: &Network) -> Box<dyn flodl::nn::optim::Optimizer> {
self.as_ref().make_optimizer(net)
}
fn describe(&self) -> Option<serde_json::Value> {
self.as_ref().describe()
}
fn holdout_score(&mut self, net: &mut Network, game_i: usize) -> flodl::tensor::Result<f32> {
self.as_mut().holdout_score(net, game_i)
}
fn holdout_matches(&self) -> Option<usize> {
self.as_ref().holdout_matches()
}
}
pub trait IntoBoxedTrainer {
fn into_boxed(self) -> Box<dyn StepTrainer>;
}
impl<T: StepTrainer + 'static> IntoBoxedTrainer for T {
fn into_boxed(self) -> Box<dyn StepTrainer> {
Box::new(self)
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::graph::node::Node;
use crate::graph::topology::Topology;
use flodl::Device;
use flodl::Module;
struct SentinelRl;
impl StepTrainer for SentinelRl {
fn make_optimizer(&self, net: &Network) -> Box<dyn flodl::nn::optim::Optimizer> {
Box::new(flodl::nn::Adam::new(&net.parameters(), 1e-3_f64))
}
fn holdout_score(
&mut self,
_net: &mut Network,
game_i: usize,
) -> flodl::tensor::Result<f32> {
Ok(100.0 + game_i as f32)
}
fn holdout_matches(&self) -> Option<usize> {
Some(3)
}
}
impl RlStep for SentinelRl {
fn train_step(
&mut self,
_net: &mut Network,
_optimizer: &mut dyn flodl::nn::optim::Optimizer,
_step: usize,
_ctx: &RlContext<'_>,
) -> flodl::tensor::Result<RlStepReport> {
unimplemented!("the guardrail dispatch test never trains")
}
}
#[test]
fn step_env_progress_reads_the_run_clock() {
let env = StepEnv {
step: 25,
run_seed: 1,
pop_size: 2,
live_count: 2,
checkpoint_every: 10,
smoothing_window: 5,
max_steps: Some(100),
};
assert_eq!(env.progress(), Some(0.25));
assert_eq!(StepEnv { step: 400, ..env }.progress(), Some(1.0));
assert_eq!(
StepEnv {
max_steps: None,
..env
}
.progress(),
None
);
}
fn tiny_net() -> Network {
let mut graph = Topology::new(0, None);
graph.nodes.push(Node::new_input(0, 2));
graph.nodes.push(Node::new_hidden(1, 3, 2));
graph.nodes.push(Node::new_output(2, 2, 1));
graph.refresh_labels();
graph.finalize();
Network::build(&graph, Device::CPU).unwrap()
}
#[test]
fn guardrail_forwarding_survives_boxing_rl() {
let mut net = tiny_net();
let mut adapter = ModeAdapter::rl(Box::new(SentinelRl));
assert_eq!(
EngineTrainer::holdout_score(&mut adapter, &mut net, 1).unwrap(),
101.0,
"the boxed trainer's override must run, not the trait default"
);
assert_eq!(EngineTrainer::holdout_matches(&adapter), Some(3));
}
#[test]
fn guardrail_forwarding_survives_boxing_tabular() {
let trainer = crate::trainer::TabularTrainer::new(
|_pred, _y| -> flodl::tensor::Result<flodl::Variable> {
unimplemented!("the guardrail dispatch test never trains")
},
)
.with_holdout_scorer(
|_net, game_i| -> flodl::tensor::Result<f32> { Ok(7.0 + game_i as f32) },
5,
);
let mut adapter = ModeAdapter::tabular(Box::new(trainer));
let mut net = tiny_net();
assert_eq!(
EngineTrainer::holdout_score(&mut adapter, &mut net, 2).unwrap(),
9.0,
"the installed scorer must run through the tabular adapter"
);
assert_eq!(EngineTrainer::holdout_matches(&adapter), Some(5));
}
}