"""Training-only observation statistics, with explicit auditable system provenance.""" import json from dataclasses import dataclass from pathlib import Path import numpy as np from .schema import FIELD_SPECS, NUM_FIELDS @dataclass class Normalization: mean: np.ndarray scale: np.ndarray training_system_ids: list[str] def __post_init__(self): self.mean, self.scale = np.asarray(self.mean, dtype=float), np.asarray(self.scale, dtype=float) if self.mean.shape != (NUM_FIELDS,) or self.scale.shape != (NUM_FIELDS,): raise ValueError("Normalization must match canonical vocabulary") if not np.isfinite(self.mean).all() or not np.isfinite(self.scale).all() or np.any(self.scale <= 0): raise ValueError("Normalization must have finite means and positive scales") @classmethod def fit(cls, episodes): episodes = list(episodes) if not episodes: raise ValueError("Normalization requires training episodes") if any(ep.split not in (None, "train") for ep in episodes): raise ValueError("Normalization fit accepts only training episodes") count, total, squares = np.zeros(NUM_FIELDS), np.zeros(NUM_FIELDS), np.zeros(NUM_FIELDS) for episode in episodes: mask = episode.observation_mask & np.isfinite(episode.values) observed = np.where(mask, episode.values, 0.0) count += mask.sum(0) total += observed.sum(0) squares += (observed**2).sum(0) mean = total / np.maximum(count, 1) scale = np.sqrt(np.maximum(squares / np.maximum(count, 1) - mean**2, 0)) scale[scale < 1e-6] = 1 return cls(mean, scale, sorted({ep.system_id for ep in episodes})) def transform(self, values, mask=None): transformed = (np.asarray(values) - self.mean) / self.scale return np.where(mask, transformed, 0) if mask is not None else transformed def inverse(self, values): return np.asarray(values) * self.scale + self.mean def save(self, path): data = { "version": 1, "field_names": [f.name for f in FIELD_SPECS], "mean": self.mean.tolist(), "scale": self.scale.tolist(), "training_system_ids": self.training_system_ids, "bounds": {f.name: [f.minimum, f.maximum] for f in FIELD_SPECS}, } Path(path).write_text(json.dumps(data, indent=2, sort_keys=True) + "\n") @classmethod def load(cls, path): data = json.loads(Path(path).read_text()) if data.get("version") != 1 or data["field_names"] != [f.name for f in FIELD_SPECS]: raise ValueError("Incompatible normalization version/vocabulary") return cls(data["mean"], data["scale"], data["training_system_ids"])