use std::path::{Path, PathBuf};
use crate::graph::topology::Topology;
use crate::state::RunHeader;
pub const DEFAULT_RESULTS_ROOT: &str = "results";
#[derive(Clone, Debug)]
pub struct SeedPick {
pub rank: usize,
pub source_run_id: String,
pub source_dir: PathBuf,
pub champion_hash: String,
pub champion_params: Option<i64>,
pub topology: Topology,
}
#[derive(Clone, Debug)]
pub struct SeedPlan {
pub source_run_id: String,
pub source_dir: PathBuf,
pub picks: Vec<SeedPick>,
}
impl SeedPlan {
pub fn champion(&self) -> &SeedPick {
&self.picks[0]
}
}
#[derive(Clone, Debug)]
pub enum SeedOutcome {
Seeded(Box<SeedPlan>),
Skipped(String),
}
impl SeedOutcome {
pub fn seeded(&self) -> Option<&SeedPlan> {
match self {
SeedOutcome::Seeded(p) => Some(p),
SeedOutcome::Skipped(_) => None,
}
}
}
#[derive(Clone, Debug, serde::Deserialize)]
struct EliteIndexEntry {
rank: usize,
hash: String,
}
pub fn resolve(
root: Option<&Path>,
exclude: Option<&Path>,
mode: &str,
input_dim: usize,
output_dim: usize,
trainer_name: Option<&str>,
) -> SeedOutcome {
resolve_plan(root, exclude, mode, input_dim, output_dim, trainer_name, 1)
}
pub fn resolve_plan(
root: Option<&Path>,
exclude: Option<&Path>,
mode: &str,
input_dim: usize,
output_dim: usize,
trainer_name: Option<&str>,
max_seeds: usize,
) -> SeedOutcome {
let explicit = root.is_some();
let root = root.unwrap_or(Path::new(DEFAULT_RESULTS_ROOT));
let dirs = run_dirs(root, exclude);
let Some(dir) = dirs.first() else {
return SeedOutcome::Skipped(if explicit {
format!("no previous run under {}", root.display())
} else {
format!(
"default folder `{}/` not found — no previous run to inherit from",
root.display()
)
});
};
let header = match read_header(dir) {
Ok(h) => h,
Err(why) => return SeedOutcome::Skipped(why),
};
let source_run_id = header.run_id.clone();
let src_mode = header.engine_mode.as_deref().unwrap_or("unknown");
if src_mode != mode {
return SeedOutcome::Skipped(format!(
"different experiment — newest run {source_run_id} is engine_mode {src_mode}, \
this run is {mode}"
));
}
if header.input_dim != input_dim || header.output_dim != output_dim {
return SeedOutcome::Skipped(format!(
"different experiment — newest run {source_run_id} is {}→{}, this run is \
{input_dim}→{output_dim}",
header.input_dim, header.output_dim
));
}
let src_trainer = header.trainer.as_ref().and_then(trainer_name_of);
if let (Some(a), Some(b)) = (src_trainer, trainer_name) {
if a != b {
return SeedOutcome::Skipped(format!(
"different experiment — newest run {source_run_id} was trained by `{a}`, \
this run by `{b}`"
));
}
}
let ranked: Vec<(usize, String)> = match read_champion_index(dir) {
Some(entries) if !entries.is_empty() => entries,
_ => {
return SeedOutcome::Skipped(format!(
"run {source_run_id} has no champions.json — its final table was not recorded"
));
}
};
let cap = max_seeds.max(1);
let mut picks: Vec<SeedPick> = Vec::new();
let mut first_failure: Option<String> = None;
for (rank, hash) in ranked.into_iter().take(cap) {
let short = &hash[..8.min(hash.len())];
let state_path = dir.join("nets").join(format!("{hash}.json"));
let topology = match crate::engine::population::run_topology_from_json_file(&state_path) {
Ok(t) => t,
Err(e) => {
let why = if rank == 1 {
format!("champion {short} of run {source_run_id}: {e}")
} else {
format!("champion #{rank} {short} of run {source_run_id}: {e}")
};
first_failure.get_or_insert(why);
continue;
}
};
let opts = &topology.options;
if opts.input_dim.is_some()
&& (opts.input_dim != Some(input_dim) || opts.output_dim != Some(output_dim))
{
first_failure.get_or_insert(format!(
"blueprint of rank {rank} ({short}) in run {source_run_id} is {:?}→{:?}, this run is {input_dim}→{output_dim}",
opts.input_dim, opts.output_dim
));
continue;
}
picks.push(SeedPick {
rank,
source_run_id: source_run_id.clone(),
source_dir: dir.clone(),
champion_hash: hash,
champion_params: None,
topology,
});
}
if picks.is_empty() {
return SeedOutcome::Skipped(
first_failure.unwrap_or_else(|| {
format!("run {source_run_id} has no loadable champion blueprint")
}),
);
}
SeedOutcome::Seeded(Box::new(SeedPlan {
source_run_id,
source_dir: dir.clone(),
picks,
}))
}
fn read_champion_index(dir: &Path) -> Option<Vec<(usize, String)>> {
let raw = std::fs::read_to_string(dir.join("champions.json")).ok()?;
let mut entries: Vec<EliteIndexEntry> = serde_json::from_str(&raw).ok()?;
entries.retain(|e| !e.hash.is_empty());
entries.sort_by_key(|e| e.rank.max(1));
let mut seen: std::collections::HashSet<String> = std::collections::HashSet::new();
let out: Vec<(usize, String)> = entries
.into_iter()
.filter(|e| seen.insert(e.hash.clone()))
.map(|e| (e.rank.max(1), e.hash))
.collect();
Some(out)
}
fn trainer_name_of(blob: &serde_json::Value) -> Option<&str> {
blob.get("trainer").and_then(|v| v.as_str())
}
fn read_header(dir: &Path) -> Result<RunHeader, String> {
let path = dir.join("engine.json");
let raw = std::fs::read_to_string(&path)
.map_err(|e| format!("{}: unreadable engine.json ({e})", dir.display()))?;
RunHeader::from_json(&raw)
.map_err(|e| format!("{}: unparsable engine.json ({e})", dir.display()))
}
fn run_dirs(root: &Path, exclude: Option<&Path>) -> Vec<PathBuf> {
let excluded = |p: &Path| exclude.map(|e| same_dir(p, e)).unwrap_or(false);
if root.join("engine.json").is_file() {
return if excluded(root) {
Vec::new()
} else {
vec![root.to_path_buf()]
};
}
let Ok(entries) = std::fs::read_dir(root) else {
return Vec::new();
};
let mut found: Vec<(u128, String, PathBuf)> = entries
.flatten()
.filter_map(|e| {
let path = e.path();
if !path.is_dir() || !path.join("engine.json").is_file() {
return None;
}
let name = e.file_name().to_string_lossy().to_string();
let key = run_id_key(&name)?;
Some((key, name, path))
})
.filter(|(_, _, path)| !excluded(path))
.collect();
found.sort_by(|a, b| b.0.cmp(&a.0).then_with(|| b.1.cmp(&a.1)));
found.into_iter().map(|(_, _, p)| p).collect()
}
fn same_dir(a: &Path, b: &Path) -> bool {
match (std::fs::canonicalize(a), std::fs::canonicalize(b)) {
(Ok(x), Ok(y)) => x == y,
_ => a == b,
}
}
fn run_id_key(name: &str) -> Option<u128> {
let digits: String = name.chars().take_while(|c| c.is_ascii_digit()).collect();
if digits.is_empty() {
return None;
}
digits.parse().ok()
}
#[cfg(test)]
mod tests {
use super::*;
fn tmp(name: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!("gras-seed-{}-{name}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).unwrap();
dir
}
fn toy_topology() -> Topology {
let opts = crate::graph::topology::TopologyOptions {
topology_seed: 7,
min_hidden_num_nodes: 1,
max_hidden_num_nodes: 1,
min_hidden_inputs_per_node: 1,
max_hidden_inputs_per_node: 1,
min_hidden_outputs_per_node: 1,
max_hidden_outputs_per_node: 1,
input_dim: Some(2),
output_dim: Some(2),
dropout_prob: 0.0,
feature_split: None,
weight_seed: None,
};
let mut topo = Topology::new(7, Some(opts));
topo.nodes.push(crate::graph::node::Node::new_input(0, 2));
topo.nodes
.push(crate::graph::node::Node::new_hidden(1, 2, 4));
topo.nodes
.push(crate::graph::node::Node::new_output(2, 4, 2));
let port = |node: usize, index: usize| crate::graph::topology::Port { node, index };
let conn = |from: (usize, usize), to: (usize, usize)| crate::graph::topology::Connection {
from: port(from.0, from.1),
to: port(to.0, to.1),
};
for to in 0..2 {
topo.connections.push(conn((0, to), (1, to)));
}
for to in 0..2 {
topo.connections.push(conn((1, to), (2, to)));
}
topo.refresh_labels();
topo.finalize();
topo
}
fn write_run(
dir: &Path,
run_id: &str,
mode: &str,
trainer: &str,
with_index: bool,
) -> Topology {
std::fs::create_dir_all(dir.join("nets")).unwrap();
let topo = toy_topology();
let hash = "abcd1234abcd1234";
let state = serde_json::json!({ "topology": topo.to_json().unwrap() });
std::fs::write(
dir.join("nets").join(format!("{hash}.json")),
state.to_string(),
)
.unwrap();
let header = serde_json::json!({
"run_id": run_id,
"engine_mode": mode,
"run_seed": 42,
"fitness_label": "mse",
"fitness_direction": "Minimize",
"input_dim": 2,
"output_dim": 2,
"config": { "mode": mode },
"trainer": { "trainer": trainer },
});
if with_index {
std::fs::write(
dir.join("champions.json"),
serde_json::json!([{ "rank": 1, "hash": hash, "fitness": 0.25, "params": 123 }])
.to_string(),
)
.unwrap();
}
std::fs::write(dir.join("engine.json"), header.to_string()).unwrap();
topo
}
#[test]
fn newest_run_id_prefix_wins_and_non_runs_are_ignored() {
let root = tmp("newest");
write_run(&root.join("1000"), "1000", "tabular", "toy", true);
write_run(
&root.join("2000_labelled"),
"2000_labelled",
"tabular",
"toy",
true,
);
std::fs::create_dir_all(root.join("notes")).unwrap();
std::fs::write(root.join("loose.json"), "{}").unwrap();
let out = resolve(Some(&root), None, "tabular", 2, 2, Some("toy"));
let plan = out.seeded().expect("newest run dir must be picked");
assert_eq!(plan.source_run_id, "2000_labelled");
assert_eq!(plan.picks.len(), 1, "a one-entry final table ⇒ one pick");
let pick = plan.champion();
assert_eq!(pick.rank, 1);
assert_eq!(pick.champion_hash, "abcd1234abcd1234");
assert_eq!(pick.champion_params, None);
}
#[test]
fn a_run_directory_is_used_as_it_is() {
let root = tmp("direct");
write_run(&root, "3000", "rl", "cartpole", true);
let out = resolve(Some(&root), None, "rl", 2, 2, Some("cartpole"));
assert_eq!(out.seeded().unwrap().source_run_id, "3000");
}
#[test]
fn incompatible_candidates_are_skipped() {
let root = tmp("incompat");
write_run(&root.join("1000"), "1000", "tabular", "toy", true);
assert!(
resolve(Some(&root), None, "rl", 2, 2, Some("toy"))
.seeded()
.is_none()
);
assert!(
resolve(Some(&root), None, "tabular", 4, 2, Some("toy"))
.seeded()
.is_none()
);
assert!(
resolve(Some(&root), None, "tabular", 2, 2, Some("other"))
.seeded()
.is_none()
);
assert!(
resolve(Some(&root), None, "tabular", 2, 2, Some("toy"))
.seeded()
.is_some()
);
}
#[test]
fn a_missing_trainer_name_skips_that_check() {
let root = tmp("no-trainer-name");
write_run(&root.join("1000"), "1000", "tabular", "toy", true);
assert!(
resolve(Some(&root), None, "tabular", 2, 2, None)
.seeded()
.is_some()
);
}
#[test]
fn a_source_without_a_final_table_is_skipped() {
let root = tmp("no-elite-index");
write_run(&root.join("1000"), "1000", "tabular", "toy", false);
let reason = match resolve(Some(&root), None, "tabular", 2, 2, Some("toy")) {
SeedOutcome::Skipped(r) => r,
SeedOutcome::Seeded(_) => panic!("a run with no champions.json must be skipped"),
};
assert!(reason.contains("no champions.json"), "{reason}");
}
#[test]
fn a_missing_champion_blueprint_is_skipped() {
let root = tmp("no-blueprint");
write_run(&root.join("1000"), "1000", "tabular", "toy", true);
std::fs::remove_file(root.join("1000/nets/abcd1234abcd1234.json")).unwrap();
let reason = match resolve(Some(&root), None, "tabular", 2, 2, Some("toy")) {
SeedOutcome::Skipped(r) => r,
SeedOutcome::Seeded(_) => panic!("a champion whose state file is gone must be skipped"),
};
assert!(reason.contains("run-topology"), "{reason}");
}
#[test]
fn empty_root_and_missing_root_are_skipped_not_panicked() {
let root = tmp("empty");
assert!(
resolve(Some(&root), None, "tabular", 2, 2, Some("toy"))
.seeded()
.is_none()
);
let missing = root.join("does-not-exist");
assert!(
resolve(Some(&missing), None, "tabular", 2, 2, Some("toy"))
.seeded()
.is_none()
);
}
#[test]
fn the_current_runs_own_directory_is_never_chosen() {
let root = tmp("self-exclude");
write_run(&root.join("1000"), "1000", "tabular", "toy", true);
let current = root.join("2000");
write_run(¤t, "2000", "tabular", "toy", false);
let out = resolve(Some(&root), Some(¤t), "tabular", 2, 2, Some("toy"));
assert_eq!(
out.seeded()
.expect("must fall back to the older run")
.source_run_id,
"1000",
"the current run must not be its own seed source"
);
let self_only = tmp("self-only");
write_run(&self_only, "3000", "tabular", "toy", true);
assert!(
resolve(
Some(&self_only),
Some(&self_only),
"tabular",
2,
2,
Some("toy")
)
.seeded()
.is_none()
);
}
#[test]
fn the_seeded_blueprint_is_the_champions_exact_topology() {
let root = tmp("exact");
let topo = write_run(&root.join("1000"), "1000", "tabular", "toy", true);
let out = resolve(Some(&root), None, "tabular", 2, 2, Some("toy"));
let pick = out.seeded().unwrap().champion().clone();
assert_eq!(
pick.topology.to_json().unwrap(),
topo.to_json().unwrap(),
"the import must reproduce the blueprint byte-for-byte (no re-finalize)"
);
assert_eq!(
pick.topology.options.topology_seed, topo.options.topology_seed,
"the stored init seed travels with the topology"
);
}
#[test]
fn elites_json_is_read_ranked_and_capped() {
let root = tmp("index-ranked");
let dir = root.join("1000");
write_run(&dir, "1000", "tabular", "toy", true);
let mut extra = Vec::new();
for (rank, hash, seed) in [
(2usize, "beef0001beef0001", 11u64),
(3, "beef0002beef0002", 12),
] {
let mut topo = toy_topology();
topo.options.topology_seed = seed as usize;
let state = serde_json::json!({ "topology": topo.to_json().unwrap() });
std::fs::write(
dir.join("nets").join(format!("{hash}.json")),
state.to_string(),
)
.unwrap();
extra.push((rank, hash));
}
let index = serde_json::json!([
{ "rank": 1, "hash": "abcd1234abcd1234", "fitness": 90.0 },
{ "rank": 2, "hash": extra[0].1, "fitness": 80.0 },
{ "rank": 3, "hash": extra[1].1, "fitness": 70.0 },
]);
std::fs::write(dir.join("champions.json"), index.to_string()).unwrap();
let out = resolve_plan(Some(&root), None, "tabular", 2, 2, Some("toy"), 10);
let plan = out.seeded().expect("the index must be used");
assert_eq!(plan.picks.len(), 3);
assert_eq!(
plan.picks.iter().map(|p| p.rank).collect::<Vec<_>>(),
vec![1, 2, 3]
);
assert_eq!(plan.champion().champion_hash, "abcd1234abcd1234");
assert_eq!(
plan.picks
.iter()
.map(|p| p.champion_hash.as_str())
.collect::<Vec<_>>(),
vec!["abcd1234abcd1234", extra[0].1, extra[1].1]
);
assert_eq!(
plan.picks[1].topology.options.topology_seed, 11,
"each rank brings its own blueprint"
);
let capped = resolve_plan(Some(&root), None, "tabular", 2, 2, Some("toy"), 2);
let plan = capped.seeded().unwrap();
assert_eq!(plan.picks.len(), 2);
assert_eq!(plan.champion().champion_hash, "abcd1234abcd1234");
assert_eq!(plan.picks[1].champion_hash, extra[0].1);
}
#[test]
fn a_missing_later_rank_is_dropped_but_the_rest_inherit() {
let root = tmp("index-partial");
let dir = root.join("1000");
write_run(&dir, "1000", "tabular", "toy", true);
let index = serde_json::json!([
{ "rank": 1, "hash": "abcd1234abcd1234" },
{ "rank": 2, "hash": "9999dead9999dead" },
]);
std::fs::write(dir.join("champions.json"), index.to_string()).unwrap();
let out = resolve_plan(Some(&root), None, "tabular", 2, 2, Some("toy"), 10);
let plan = out.seeded().expect("the champion still inherits");
assert_eq!(plan.picks.len(), 1, "the unloadable rank is dropped");
assert_eq!(plan.champion().champion_hash, "abcd1234abcd1234");
let index = serde_json::json!([{ "rank": 1, "hash": "9999dead9999dead" }]);
std::fs::write(dir.join("champions.json"), index.to_string()).unwrap();
let reason = match resolve_plan(Some(&root), None, "tabular", 2, 2, Some("toy"), 10) {
SeedOutcome::Skipped(r) => r,
SeedOutcome::Seeded(_) => panic!("a champion with no blueprint must be skipped"),
};
assert!(reason.contains("run-topology"), "{reason}");
}
}