"""CPU-only epoch coverage, exact loss accounting and conservative stop rules. These are training-only convergence diagnostics, never held-out success claims. The new budget is independent of the parent's exhausted optimizer schedule. """ from __future__ import annotations import math import random from collections import Counter PROBE_TOLERANCES = { "control_accuracy": ("higher", 0.02), "background_only_false_motion_rate": ("lower", 0.05), "missed_motion_rate": ("lower", 0.02), "joint_mae_radians": ("lower_relative", 0.10), } def _budget(min_epochs, max_epochs): if (not isinstance(min_epochs, int) or not isinstance(max_epochs, int) or not 6 <= min_epochs <= max_epochs <= 20): raise ValueError("New stage requires at least six epochs and at most twenty") def _positive_integer(value, name): if isinstance(value, bool) or not isinstance(value, int) or value <= 0: raise ValueError(f"{name} must be a positive integer") return value def plan_epochs(selection, *, batch_size=16, seed=26100701, min_epochs=6, max_epochs=20): """Every new epoch consumes all fixed 300 sessions exactly once, with tails. Source groups are length-sorted; only group order is shuffled independently per epoch. This neither resamples classes nor changes the loss weighting. """ _budget(min_epochs, max_epochs) _positive_integer(batch_size, "batch_size") rows = selection["sessions"] ids = selection["session_ids"] if (selection.get("split", "train") != "train" or len(rows) != 300 or len(ids) != 300 or len(set(ids)) != 300 or [r["session_id"] for r in rows] != list(ids)): raise ValueError("Expected exactly 300 aligned, unique, train-only sessions") classes = Counter(r["session_type"] for r in rows) if len(classes) != 6 or set(classes.values()) != {50}: raise ValueError("Expected six classes, fifty sessions per class") lengths = [_positive_integer(r["dense_steps"], "dense_steps") for r in rows] semantic = [_positive_integer(r["semantic_steps"], "semantic_steps") for r in rows] if any(r.get("split", "train") != "train" for r in rows): raise ValueError("Held-out sessions cannot enter this training stage") indices = sorted(range(len(rows)), key=lambda i: (lengths[i], ids[i])) groups = [indices[i:i + batch_size] for i in range(0, len(indices), batch_size)] epochs = [] for epoch in range(1, max_epochs + 1): epoch_seed = int(seed) + epoch * 1_000_003 ordered = [list(group) for group in groups] random.Random(epoch_seed).shuffle(ordered) steps = [max(lengths[i] for i in group) for group in ordered] epochs.append({"epoch": epoch, "seed": epoch_seed, "source_indices": ordered, "group_steps": steps, "source_count": len(rows), "optimizer_updates": sum(steps), "action_samples": sum(lengths), "control_samples": sum(semantic), "class_counts": dict(sorted(classes.items()))}) return {"schema": 1, "evaluation_split": "train_only", "batch_size": batch_size, "seed": int(seed), "min_epochs": min_epochs, "max_epochs": max_epochs, "epochs": epochs, "max_optimizer_updates": sum(e["optimizer_updates"] for e in epochs), "policy": "complete original sources once each epoch; length groups; epoch-shuffled group order; no loss reweighting"} class EpochLossAccumulator: """Accumulate actual active-example sums, not batch or logged-row means. The driver must call add for EVERY optimizer event, not just persisted log rows, and supply actual active source/window counts (not batch capacity). control_samples is zero on action-only updates, so absent CE is permitted. """ def __init__(self): self.action_sum = 0.0 self.action_samples = 0.0 self.control_sum = 0.0 self.control_samples = 0.0 self.optimizer_updates = 0 self.control_updates = 0 def add(self, *, action_loss, action_samples, control_ce=None, control_samples=0): values = (action_loss, action_samples, control_samples) if any(not math.isfinite(float(value)) for value in values): raise FloatingPointError("Nonfinite action loss or sample count") action_loss, action_samples, control_samples = map(float, values) if action_loss < 0 or action_samples <= 0 or control_samples < 0: raise ValueError("Loss must be nonnegative and active action count positive") if control_samples > action_samples + 1e-6: raise ValueError("Control count cannot exceed active action-example count") if control_samples: if control_ce is None or not math.isfinite(float(control_ce)): raise FloatingPointError("Semantic update requires finite control CE") if float(control_ce) < 0: raise ValueError("Control CE must be nonnegative") elif control_ce is not None and not math.isfinite(float(control_ce)): raise FloatingPointError("Nonfinite supplied control CE") self.action_sum += action_loss * action_samples self.action_samples += action_samples if control_samples: self.control_sum += float(control_ce) * control_samples self.control_samples += control_samples self.control_updates += 1 self.optimizer_updates += 1 def summary(self): if self.action_samples <= 0 or self.control_samples <= 0: raise ValueError("A complete epoch must contain action and control supervision") return {"action_loss": self.action_sum / self.action_samples, "control_ce": self.control_sum / self.control_samples, "action_loss_sum": self.action_sum, "action_samples": self.action_samples, "control_ce_sum": self.control_sum, "control_samples": self.control_samples, "optimizer_updates": self.optimizer_updates, "control_updates": self.control_updates} def _probe_regressions(current, reference, tolerances): reasons = [] for key, (direction, tolerance) in tolerances.items(): value, anchor = current[key], reference[key] if value is None or anchor is None: reasons.append(f"{key}: unavailable") continue value, anchor = float(value), float(anchor) if not math.isfinite(value) or not math.isfinite(anchor): reasons.append(f"{key}: nonfinite") continue if direction == "higher": bad = value < anchor - tolerance elif direction == "lower": bad = value > anchor + tolerance elif direction == "lower_relative": bad = value > anchor + tolerance * max(abs(anchor), 1e-6) else: raise ValueError(f"Unknown metric direction {direction}") if bad: reasons.append(f"{key}: {value:.8g} versus {anchor:.8g}") return reasons def assess_progress(epoch_records, *, baseline_probe, min_epochs=6, max_epochs=20, patience=3, relative_tolerance=0.01, denominator_floor=1e-6, probe_tolerances=None): """Return continue/stop_plateau/stop_budget/stop_regression/stop_divergence. Plateau requires three consecutive non-worsening <1% adjacent-epoch drops for BOTH losses and no material fixed-panel regression against the anchor or each previous epoch. One worse probe does not stop training; two do. A hard budget exit explicitly does NOT assert convergence. """ _budget(min_epochs, max_epochs) _positive_integer(patience, "patience") if not 0 < relative_tolerance < 1 or not math.isfinite(relative_tolerance): raise ValueError("Relative tolerance must be finite and between zero and one") if not 0 < denominator_floor or not math.isfinite(denominator_floor): raise ValueError("A positive finite denominator floor is required") tolerances = PROBE_TOLERANCES if probe_tolerances is None else probe_tolerances records = list(epoch_records) output = {"action": "continue", "stop": False, "converged": False, "completed_epochs": len(records), "evaluation_split": "train_only", "reason": "More complete epochs or stable evidence needed"} if not records: return output def stopped(action, reason): return {**output, "action": action, "stop": True, "converged": action == "stop_plateau", "reason": reason} loss_keys = ("control_ce", "action_loss") for index, record in enumerate(records, 1): if record.get("epoch") != index or not record.get("complete") or record.get("source_count") != 300: raise ValueError("Only consecutive, complete, 300-source epochs may be assessed") if any(not math.isfinite(float(record[key])) for key in loss_keys): return stopped("stop_nonfinite", f"Nonfinite loss in epoch {index}") if any(float(record[key]) < 0 for key in loss_keys): raise ValueError("Loss cannot be negative") probe = record.get("probe") if probe is not None and any(probe.get(key) is not None and not math.isfinite(float(probe[key])) for key in tolerances): return stopped("stop_nonfinite", f"Nonfinite fixed-panel metric in epoch {index}") # Both consecutive losses must exceed twice a prior best by a meaningful # absolute margin; tiny near-zero stochastic variations are not divergence. if len(records) >= 3: for key in loss_keys: prior_best = min(float(r[key]) for r in records[:-2]) boundary = max(2 * prior_best, prior_best + 0.1) if all(float(r[key]) > boundary for r in records[-2:]): return stopped("stop_divergence", f"Two consecutive {key} values exceed prior best by >2x and >0.1") def regressions(record, anchor): if record.get("probe") is None or anchor is None: return ["fixed60 panel unavailable"] return _probe_regressions(record["probe"], anchor, tolerances) if (len(records) >= 2 and baseline_probe is not None and all(r.get("probe") is not None for r in records[-2:])): bad = [regressions(r, baseline_probe) for r in records[-2:]] # Missing support is insufficient to call either improvement or # regression, and must not accidentally stop an otherwise valid run. genuine = [[reason for reason in row if not reason.endswith("unavailable")] for row in bad] if all(genuine): return stopped("stop_regression", "Two consecutive fixed60 checks regressed: " + "; ".join(genuine[-1])) if len(records) >= min_epochs and len(records) >= patience + 1: window = records[-patience - 1:] changes = {key: [(float(a[key]) - float(b[key])) / max(abs(float(a[key])), denominator_floor) for a, b in zip(window, window[1:])] for key in loss_keys} output["recent_relative_improvements"] = changes losses_flat = all(0 <= value < relative_tolerance for values in changes.values() for value in values) probes_ok = all(not regressions(r, baseline_probe) for r in window) probes_ok = probes_ok and all(not regressions(b, a.get("probe")) for a, b in zip(window, window[1:])) if losses_flat and probes_ok: return stopped("stop_plateau", "Both weighted epoch losses plateaued and fixed60 checks did not materially regress") if len(records) >= max_epochs: return stopped("stop_budget", "Hard epoch budget reached; convergence is not asserted") return output