nnscope 0.1.0__py3-none-any.whl

nnscope/__init__.py

@@ -0,0 +1,12 @@
+"""nnscope: watch your NumPy neural network learn.
+
+    import nnscope
+    scope = nnscope.Scope("my-mlp")
+    scope.log(step, model=model, loss=loss)
+"""
+__version__ = "0.1.0"
+
+from .adapters import LayerView, extract_layers  # noqa: E402
+from .scope import Scope  # noqa: E402
+
+__all__ = ["Scope", "extract_layers", "LayerView", "__version__"]

nnscope/adapters.py

@@ -0,0 +1,233 @@
+"""Turn "whatever the user has" into a uniform list of dense layers.
+
+nnscope never runs your network. It only *reads* arrays you already have: weights, biases, their gradients and
+(optionally) activations. This module finds them, either from explicit lists or by duck-typing common NumPy model
+layouts, and normalises every weight matrix to the ``(in_features, out_features)`` orientation used for ``x @ W``.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, List, Optional, Sequence
+
+import numpy as np
+
+WEIGHT_ATTRS = ("W", "weight", "weights", "kernel", "w")
+BIAS_ATTRS = ("b", "bias", "biases")
+WEIGHT_GRAD_ATTRS = ("dW", "grad_W", "W_grad", "dweight", "grad_weight", "weight_grad", "dw")
+BIAS_GRAD_ATTRS = ("db", "grad_b", "b_grad", "dbias", "grad_bias", "bias_grad")
+INPUT_CACHE_ATTRS = ("x", "input", "inputs", "a_prev", "x_cache", "cache_x")
+ACTIVATION_NAMES = {
+    "relu": "relu", "leakyrelu": "leaky_relu", "tanh": "tanh", "sigmoid": "sigmoid", "logistic": "sigmoid",
+    "softmax": "softmax", "elu": "elu", "gelu": "gelu", "softplus": "softplus", "sine": "sine", "sin": "sine",
+    "linear": "linear", "identity": "linear", "swish": "swish", "silu": "swish",
+}
+
+HELP = """nnscope could not find dense-layer weights. Pass them explicitly, for example
+
+    scope.log(step, weights=[W1, W2], biases=[b1, b2], grads=[dW1, dW2], loss=loss)
+
+or give a model object with a `.layers` list whose layers expose `W`/`b` (and `dW`/`db`),
+a `.params` dict like {"W1": ..., "b1": ...}, or a list of (W, b) pairs."""
+
+
+@dataclass
+class LayerView:
+    """One dense layer, normalised so that ``W.shape == (in_features, out_features)``."""
+
+    W: np.ndarray
+    b: Optional[np.ndarray] = None
+    dW: Optional[np.ndarray] = None
+    db: Optional[np.ndarray] = None
+    act: Optional[str] = None          # activation applied to this layer's output ("relu", "tanh", ...)
+    name: str = ""
+    source: Any = None                 # the original layer object, if any (used to find cached inputs)
+
+    @property
+    def in_features(self) -> int:
+        return int(self.W.shape[0])
+
+    @property
+    def out_features(self) -> int:
+        return int(self.W.shape[1])
+
+
+def _arr(x: Any) -> Optional[np.ndarray]:
+    return np.asarray(x) if isinstance(x, np.ndarray) or (x is not None and hasattr(x, "__array__")) else None
+
+
+def _first_attr(obj: Any, names: Sequence[str], ndim: Optional[int] = None) -> Optional[np.ndarray]:
+    for n in names:
+        v = getattr(obj, n, None)
+        a = _arr(v) if v is not None else None
+        if a is not None and a.dtype.kind in "fiu" and (ndim is None or a.ndim == ndim):
+            return a
+    return None
+
+
+def activation_name(obj: Any) -> Optional[str]:
+    """Recognise an activation layer by its class name (ReLU, Tanh, Sigmoid, ...)."""
+    key = re.sub(r"[^a-z]", "", type(obj).__name__.lower())
+    return ACTIVATION_NAMES.get(key)
+
+
+# ------------------------------------------------------------------ collection from different model layouts
+def _from_layer_objects(layers: Sequence[Any]) -> List[LayerView]:
+    views: List[LayerView] = []
+    for obj in layers:
+        if hasattr(obj, "layers") and not isinstance(obj, (list, tuple)):       # nested Sequential
+            views.extend(_from_layer_objects(list(obj.layers)))
+            continue
+        W = _first_attr(obj, WEIGHT_ATTRS, ndim=2)
+        if W is not None:
+            views.append(LayerView(
+                W=W, b=_first_attr(obj, BIAS_ATTRS), dW=_first_attr(obj, WEIGHT_GRAD_ATTRS, ndim=2),
+                db=_first_attr(obj, BIAS_GRAD_ATTRS), name=type(obj).__name__, source=obj))
+            continue
+        act = activation_name(obj)
+        if act and views and views[-1].act is None:
+            views[-1].act = act
+    return views
+
+
+_KEY = re.compile(r"^(?P<kind>[A-Za-z]+)[_.]?(?P<idx>\d+)$")
+
+
+def _from_dict(params: dict, grads: Optional[dict] = None) -> List[LayerView]:
+    """CS231n-style dicts: {"W1": ..., "b1": ..., "W2": ...} (+ an optional grads dict with the same keys)."""
+    layers: dict = {}
+    for key, val in params.items():
+        m = _KEY.match(str(key))
+        if not m:
+            continue
+        kind, idx = m.group("kind"), int(m.group("idx"))
+        slot = layers.setdefault(idx, {})
+        if kind in WEIGHT_ATTRS:
+            slot["W"], slot["kW"] = np.asarray(val), key
+        elif kind in BIAS_ATTRS:
+            slot["b"], slot["kb"] = np.asarray(val), key
+    views = []
+    for idx in sorted(layers):
+        slot = layers[idx]
+        if "W" not in slot or slot["W"].ndim != 2:
+            continue
+        dW = _arr(grads.get(slot["kW"])) if grads else None
+        db = _arr(grads.get(slot.get("kb"))) if grads and slot.get("kb") else None
+        views.append(LayerView(W=slot["W"], b=slot.get("b"), dW=dW, db=db, name=f"layer {idx}"))
+    return views
+
+
+def _from_sequence(items: Sequence[Any]) -> List[LayerView]:
+    """A list of arrays ([W1, b1, W2, b2] or [W1, W2]), of (W, b) pairs, or of layer objects."""
+    if items and not any(isinstance(it, (np.ndarray, tuple, list)) for it in items):
+        return _from_layer_objects(items)
+    views: List[LayerView] = []
+    for it in items:
+        if isinstance(it, (tuple, list)):
+            W = np.asarray(it[0])
+            b = np.asarray(it[1]) if len(it) > 1 and it[1] is not None else None
+            views.append(LayerView(W=W, b=b))
+        else:
+            a = np.asarray(it)
+            if a.ndim == 2:
+                views.append(LayerView(W=a))
+            elif a.ndim == 1 and views and views[-1].b is None:
+                views[-1].b = a
+    return views
+
+
+# ------------------------------------------------------------------ orientation
+def _chains(mats: List[np.ndarray], in_out: bool) -> bool:
+    if in_out:
+        return all(mats[k].shape[1] == mats[k + 1].shape[0] for k in range(len(mats) - 1))
+    return all(mats[k].shape[0] == mats[k + 1].shape[1] for k in range(len(mats) - 1))
+
+
+def detect_layout(views: List[LayerView]) -> str:
+    """Return "in_out" (x @ W, W is (in, out)) or "out_in" (W @ x, W is (out, in))."""
+    mats = [v.W for v in views]
+    if len(mats) >= 2:
+        io, oi = _chains(mats, True), _chains(mats, False)
+        if io and not oi:
+            return "in_out"
+        if oi and not io:
+            return "out_in"
+    votes = 0                                            # ambiguous → let the biases decide
+    for v in views:
+        if v.b is not None and v.W.shape[0] != v.W.shape[1]:
+            n = v.b.size
+            votes += (n == v.W.shape[1]) - (n == v.W.shape[0])
+    return "out_in" if votes < 0 else "in_out"
+
+
+def normalise(views: List[LayerView], layout: str = "auto") -> List[LayerView]:
+    if layout not in ("auto", "in_out", "out_in"):
+        raise ValueError('layout must be "auto", "in_out" or "out_in"')
+    if layout == "auto":
+        layout = detect_layout(views)
+    if layout == "out_in":
+        for v in views:
+            v.W = v.W.T
+            if v.dW is not None:
+                v.dW = v.dW.T
+    for k, v in enumerate(views):
+        if not v.name:
+            v.name = f"layer {k + 1}"
+        for attr in ("b", "db"):
+            a = getattr(v, attr)
+            if a is not None:
+                setattr(v, attr, np.asarray(a).reshape(-1))
+        if v.dW is not None and v.dW.shape != v.W.shape:
+            v.dW = v.dW.T if v.dW.T.shape == v.W.shape else None
+    return views
+
+
+# ------------------------------------------------------------------ public entry point
+def extract_layers(model: Any = None, *, weights: Optional[Sequence] = None, biases: Optional[Sequence] = None,
+                   grads: Any = None, bias_grads: Optional[Sequence] = None, layout: str = "auto") -> List[LayerView]:
+    """Collect dense layers from ``model`` or from explicit arrays. Raises ``TypeError`` with usage help if none are found."""
+    if weights is not None:
+        views = [LayerView(W=np.asarray(W)) for W in weights]
+        for k, v in enumerate(views):
+            if biases is not None and k < len(biases) and biases[k] is not None:
+                v.b = np.asarray(biases[k])
+            if isinstance(grads, (list, tuple)) and k < len(grads) and grads[k] is not None:
+                v.dW = np.asarray(grads[k])
+            if bias_grads is not None and k < len(bias_grads) and bias_grads[k] is not None:
+                v.db = np.asarray(bias_grads[k])
+    elif model is None:
+        raise TypeError(HELP)
+    elif hasattr(model, "layers") and not isinstance(model, dict):
+        views = _from_layer_objects(list(model.layers))
+    elif isinstance(getattr(model, "params", None), dict):
+        g = grads if isinstance(grads, dict) else getattr(model, "grads", None)
+        views = _from_dict(model.params, g if isinstance(g, dict) else None)
+    elif isinstance(model, dict):
+        views = _from_dict(model, grads if isinstance(grads, dict) else None)
+    elif isinstance(model, (list, tuple)):
+        views = _from_sequence(model)
+        if isinstance(grads, (list, tuple)):
+            for v, g in zip(views, grads):
+                v.dW = np.asarray(g) if g is not None else None
+    else:
+        raise TypeError(HELP)
+    views = [v for v in views if v.W.ndim == 2]
+    if not views:
+        raise TypeError(HELP)
+    return normalise(views, layout)
+
+
+def cached_activations(views: List[LayerView]) -> List[Optional[np.ndarray]]:
+    """Best-effort: the output of hidden layer k is the cached *input* of layer k+1 (e.g. HW-style ``Linear.x``).
+
+    Returns one entry per layer (the last one, the network output, is usually unknown → None).
+    """
+    out: List[Optional[np.ndarray]] = [None] * len(views)
+    for k in range(len(views) - 1):
+        nxt = views[k + 1].source
+        if nxt is None:
+            continue
+        x = _first_attr(nxt, INPUT_CACHE_ATTRS)
+        if x is not None and x.ndim == 2 and x.shape[1] == views[k].out_features:
+            out[k] = x
+    return out

nnscope/export.py

@@ -0,0 +1,168 @@
+"""Standalone HTML replay and static images (SVG without dependencies, PNG via matplotlib if installed)."""
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+from typing import Optional
+
+BLUE, ORANGE, MID = (8, 119, 189), (245, 147, 34), (232, 234, 235)
+BOOT_MARKER = "/*__NNSCOPE_BOOT__*/"
+
+
+def _template() -> str:
+    try:
+        from importlib.resources import files
+        return files("nnscope").joinpath("static/index.html").read_text(encoding="utf-8")
+    except (ImportError, AttributeError):                              # Python < 3.9 fallback
+        return (Path(__file__).parent / "static" / "index.html").read_text(encoding="utf-8")
+
+
+def render_page(data: Optional[dict], live: bool) -> str:
+    boot = {"live": live, "data": data}
+    payload = json.dumps(boot, separators=(",", ":")).replace("</", "<\\/")
+    return _template().replace(BOOT_MARKER, f"window.NNSCOPE = {payload};", 1)
+
+
+def save_html(data: dict, path: str) -> str:
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(render_page(data, live=False), encoding="utf-8")
+    return str(p)
+
+
+# ------------------------------------------------------------------ static snapshot image
+def _color(v: float) -> str:
+    t = max(-1.0, min(1.0, v))
+    c = BLUE if t >= 0 else ORANGE
+    a = abs(t)
+    return "#%02x%02x%02x" % tuple(int(MID[i] + (c[i] - MID[i]) * a) for i in range(3))
+
+
+def _pick_snapshot(data: dict, step: Optional[int]) -> Optional[dict]:
+    snaps = data.get("snapshots") or []
+    if not snaps:
+        return None
+    if step is None:
+        return snaps[-1]
+    return min(snaps, key=lambda s: abs(s["step"] - step))
+
+
+def _layout(structure: dict, x0: float, x1: float, y0: float, y1: float):
+    layers = structure["layers"]
+    cols = [layers[0]["shown_in"]] + [l["shown_out"] for l in layers]
+    xs = [x0 + (x1 - x0) * c / max(1, len(cols) - 1) for c in range(len(cols))]
+    pos = []
+    for c, shown in enumerate(cols):
+        n = len(shown)
+        gap = min(24.0, (y1 - y0) / max(n, 1))
+        top = (y0 + y1) / 2 - gap * (n - 1) / 2
+        pos.append([(xs[c], top + gap * j) for j in range(n)])
+    return pos, xs
+
+
+def _loss_series(data: dict):
+    series = {}
+    for r in data.get("records", []):
+        for k, v in r["scalars"].items():
+            if v is not None and math.isfinite(v):
+                series.setdefault(k, []).append((r["step"], v))
+    return series
+
+
+def snapshot_svg(data: dict, step: Optional[int] = None) -> str:
+    structure, snap = data.get("structure"), _pick_snapshot(data, step)
+    if structure is None or snap is None:
+        raise ValueError("nothing to draw yet: call scope.log(...) at least once")
+    W, H = 1100, 480
+    out = [f'<svg xmlns="http://www.w3.org/2000/svg" width="{W}" height="{H}" viewBox="0 0 {W} {H}" '
+           'font-family="Helvetica, Arial, sans-serif" font-size="12">',
+           f'<rect width="{W}" height="{H}" fill="#ffffff"/>',
+           f'<text x="24" y="28" font-size="16" fill="#222">{data.get("name", "run")} — step {snap["step"]}</text>']
+    pos, xs = _layout(structure, 70, 650, 70, H - 50)
+    for l, Wl in enumerate(snap["W"]):
+        m = max((abs(v) for row in Wl for v in row), default=1.0) or 1.0
+        for i, row in enumerate(Wl):
+            for j, w in enumerate(row):
+                (xa, ya), (xb, yb) = pos[l][i], pos[l + 1][j]
+                xm = (xa + xb) / 2
+                out.append(f'<path d="M{xa:.1f},{ya:.1f} C{xm:.1f},{ya:.1f} {xm:.1f},{yb:.1f} {xb:.1f},{yb:.1f}" fill="none" '
+                           f'stroke="{_color(1 if w >= 0 else -1)}" stroke-opacity="{0.15 + 0.85 * abs(w) / m:.2f}" '
+                           f'stroke-width="{0.3 + 3.5 * abs(w) / m:.2f}"/>')
+    for c, col in enumerate(pos):
+        node = snap["nodes"][c - 1] if c > 0 and c - 1 < len(snap["nodes"]) else None
+        for j, (x, y) in enumerate(col):
+            v = node["mean"][j] if node else 0.0
+            out.append(f'<circle cx="{x:.1f}" cy="{y:.1f}" r="6.5" fill="{_color(v)}" stroke="#555" stroke-width="0.8"/>')
+        layer = structure["layers"][max(c - 1, 0)]
+        n = layer["in"] if c == 0 else layer["out"]
+        shown = len(col)
+        label = ("input" if c == 0 else (layer.get("act") or "linear")) + f" · {n}"
+        out.append(f'<text x="{xs[c]:.1f}" y="56" text-anchor="middle" fill="#555">{label}</text>')
+        if shown < n:
+            out.append(f'<text x="{xs[c]:.1f}" y="{H - 28}" text-anchor="middle" fill="#999">+{n - shown} not drawn</text>')
+    # loss chart
+    cx0, cy0, cw, ch = 720, 70, 350, 330
+    out.append(f'<rect x="{cx0}" y="{cy0}" width="{cw}" height="{ch}" fill="#fafafa" stroke="#ddd"/>')
+    series = _loss_series(data)
+    vals = [v for s in series.values() for _, v in s]
+    if vals:
+        use_log = min(vals) > 0 and max(vals) / min(vals) > 100
+        f = (lambda v: math.log10(v)) if use_log else (lambda v: v)
+        lo, hi = min(f(v) for v in vals), max(f(v) for v in vals)
+        hi = hi if hi > lo else lo + 1
+        steps = [s for ser in series.values() for s, _ in ser]
+        s0, s1 = min(steps), max(steps) if max(steps) > min(steps) else min(steps) + 1
+        palette = ["#222222", "#f59322", "#0877bd", "#2ca02c", "#9467bd", "#8c564b"]
+        for k, (name, ser) in enumerate(series.items()):
+            pts = " ".join(f"{cx0 + cw * (s - s0) / (s1 - s0):.1f},{cy0 + ch - ch * (f(v) - lo) / (hi - lo):.1f}" for s, v in ser)
+            col = palette[k % len(palette)]
+            out.append(f'<polyline points="{pts}" fill="none" stroke="{col}" stroke-width="1.8"/>')
+            out.append(f'<text x="{cx0 + 8}" y="{cy0 + 18 + 16 * k}" fill="{col}">{name}</text>')
+        out.append(f'<text x="{cx0}" y="{cy0 + ch + 18}" fill="#777">step {s0} … {s1}{" (log scale)" if use_log else ""}</text>')
+    out.append(f'<text x="{cx0}" y="{cy0 - 10}" fill="#555">loss &amp; metrics</text>')
+    out.append("</svg>")
+    return "\n".join(out)
+
+
+def snapshot_image(data: dict, path: str, step: Optional[int] = None) -> str:
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    if p.suffix.lower() == ".svg":
+        p.write_text(snapshot_svg(data, step), encoding="utf-8")
+        return str(p)
+    if p.suffix.lower() != ".png":
+        raise ValueError("snapshot path must end in .svg or .png")
+    try:
+        import matplotlib
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+        from matplotlib.patches import PathPatch
+        from matplotlib.path import Path as MPath
+    except ImportError:
+        raise ImportError("PNG snapshots need matplotlib: pip install 'nnscope[png]' (or save as .svg)") from None
+    structure, snap = data.get("structure"), _pick_snapshot(data, step)
+    if structure is None or snap is None:
+        raise ValueError("nothing to draw yet: call scope.log(...) at least once")
+    fig, (ax, bx) = plt.subplots(1, 2, figsize=(13, 5.4), gridspec_kw={"width_ratios": [1.7, 1]})
+    pos, xs = _layout(structure, 0.0, 1.0, 0.0, 1.0)
+    for l, Wl in enumerate(snap["W"]):
+        m = max((abs(v) for row in Wl for v in row), default=1.0) or 1.0
+        for i, row in enumerate(Wl):
+            for j, w in enumerate(row):
+                (xa, ya), (xb, yb) = pos[l][i], pos[l + 1][j]
+                xm = (xa + xb) / 2
+                path = MPath([(xa, ya), (xm, ya), (xm, yb), (xb, yb)], [MPath.MOVETO, MPath.CURVE4, MPath.CURVE4, MPath.CURVE4])
+                ax.add_patch(PathPatch(path, fill=False, lw=0.3 + 2.5 * abs(w) / m, alpha=0.15 + 0.85 * abs(w) / m,
+                                       color=_color(1 if w >= 0 else -1)))
+    for c, col in enumerate(pos):
+        node = snap["nodes"][c - 1] if c > 0 and c - 1 < len(snap["nodes"]) else None
+        ax.scatter([x for x, _ in col], [y for _, y in col], s=45, zorder=3, edgecolors="#555",
+                   c=[_color(node["mean"][j] if node else 0.0) for j in range(len(col))])
+    ax.set_xlim(-0.05, 1.05); ax.set_ylim(1.05, -0.05); ax.axis("off")
+    ax.set_title(f"{data.get('name', 'run')} — step {snap['step']}")
+    for name, ser in _loss_series(data).items():
+        bx.plot([s for s, _ in ser], [v for _, v in ser], label=name)
+    bx.set_xlabel("step"); bx.set_title("loss & metrics"); bx.grid(alpha=0.3); bx.legend()
+    fig.tight_layout(); fig.savefig(p, dpi=150); plt.close(fig)
+    return str(p)

nnscope/insights.py

@@ -0,0 +1,102 @@
+"""Plain-language diagnostics: turn the logged numbers into hints a student can act on.
+
+Each rule fires once when its condition appears and re-arms after the condition clears, so the feed reads like a
+training diary ("step 120: layer 2 has 12 of 16 dead ReLUs") rather than a stream of repeats.
+"""
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+import numpy as np
+
+
+def _fmt_ratio(x: float) -> str:
+    return f"{x:,.0f}" if x >= 10 else f"{x:.1f}"
+
+
+class InsightEngine:
+    def __init__(self, patience: int = 3, warmup: int = 5):
+        self.patience = patience            # a condition must hold for this many logs in a row before it is reported
+        self.warmup = warmup                # rules about learning speed wait this many logs (early steps are special)
+        self.active: Dict[str, int] = {}    # key → consecutive logs the condition held
+        self.clear: Dict[str, int] = {}     # key → consecutive logs it has been clear (re-arm needs several)
+        self.reported: set = set()
+        self.best_test: Optional[tuple] = None   # (loss, step, train_loss at that step)
+        self.n = 0
+
+    def _check(self, key: str, cond: bool, step, level: str, panel: str, message: str, out: List[dict], immediate=False,
+               clear: Optional[bool] = None):
+        """Report `key` once when `cond` holds; re-arm only after `clear` (default: not cond) held for 3×patience logs.
+
+        The separate clear condition and the re-arm delay (hysteresis) stop a value hovering at a threshold from
+        re-firing the same hint over and over.
+        """
+        if not cond:
+            self.active.pop(key, None)
+            is_clear = (not cond) if clear is None else clear
+            self.clear[key] = self.clear.get(key, 0) + 1 if is_clear else 0
+            if self.clear[key] >= 3 * self.patience:
+                self.reported.discard(key)
+            return
+        self.clear[key] = 0
+        self.active[key] = self.active.get(key, 0) + 1
+        if key not in self.reported and (immediate or self.active[key] >= self.patience):
+            self.reported.add(key)
+            out.append({"step": step, "level": level, "kind": key.split(":")[0], "panel": panel, "message": message})
+
+    def update(self, record: dict, structure: dict) -> List[dict]:
+        out: List[dict] = []
+        self.n += 1
+        step, layers, scalars = record["step"], record["layers"], record["scalars"]
+        names = [f"layer {k + 1}" for k in range(len(layers))]
+
+        loss = scalars.get("loss")
+        self._check("nan", loss is not None and not np.isfinite(loss), step, "error", "loss",
+                    "The loss is NaN/inf: training diverged. Lower the learning rate or check for log(0) / division by zero.",
+                    out, immediate=True)
+
+        g = [l.get("g_mean_abs") for l in layers]
+        if len(g) >= 2 and all(v is not None for v in g) and g[-1] and g[-1] > 0:
+            ratio = g[-1] / max(g[0], 1e-30)
+            self._check("vanishing", ratio > 1e3, step, "warn", "health", clear=ratio < 3e2, message=
+                        f"Vanishing gradients: layer 1 receives {_fmt_ratio(ratio)}× smaller gradients than layer {len(g)}. "
+                        "Early layers barely learn. Saturating activations (sigmoid/tanh) or poor initialisation are the "
+                        "usual causes; try ReLU/tanh or He/Xavier init.", out=out)
+            self._check("exploding", max(v for v in g) > 1e2, step, "warn", "health",
+                        "Exploding gradients: mean |∂L/∂W| is above 100. Expect unstable jumps in the loss; lower the learning "
+                        "rate or clip gradients.", out)
+
+        ratios = [l.get("update_ratio") for l in layers if l.get("update_ratio") is not None]
+        if ratios and self.n > self.warmup:
+            med = float(np.median(ratios))
+            self._check("lr_high", med > 0.1, step, "warn", "health", clear=med < 0.03, message=
+                        f"Weights keep changing by ~{med:.0%} between logs (update ratio ‖ΔW‖/‖W‖). Per single SGD step a "
+                        "healthy ratio is about 0.1%, so even when logging once per epoch this is high: the learning rate is "
+                        "probably too large (watch for a noisy or rising loss).", out=out)
+            self._check("lr_low", med < 1e-6, step, "info", "health",
+                        f"Weights barely move (update ratio {med:.1e}). The learning rate may be too small, or training has converged.",
+                        out)
+
+        for k, l in enumerate(layers):
+            act = (structure["layers"][k].get("act") if k < len(structure["layers"]) else None) or "unit"
+            n, dead = structure["layers"][k]["out"], l.get("dead")
+            kind = l.get("dead_kind") or "dead"
+            if dead is None or n <= 1:
+                continue
+            word = "dead" if kind == "dead" else "saturated"
+            self._check(f"{word}:{k}", dead / n >= 0.5, step, "warn", "activations",
+                        f"{dead} of {n} {act} units in {names[k]} are {word} on the logged batch "
+                        + ("(never positive → zero gradient forever). Lower the learning rate, use He init or LeakyReLU."
+                           if word == "dead" else "(stuck near ±1 → gradient ≈ 0). Inputs to this layer are too large; "
+                           "normalise inputs or use smaller initial weights."), out)
+
+        test_key = next((k for k in scalars if ("test" in k or "val" in k) and "loss" in k), None)
+        if test_key and loss is not None and scalars[test_key] is not None and np.isfinite(scalars[test_key]):
+            t = scalars[test_key]
+            if self.best_test is None or t < self.best_test[0]:
+                self.best_test = (t, step, loss)
+            b_loss, b_step, b_train = self.best_test
+            self._check("overfit", t > 1.15 * b_loss and loss < 0.9 * b_train, step, "warn", "loss",
+                        f"Overfitting: {test_key} has risen {t / b_loss - 1:.0%} above its minimum at step {b_step} while the "
+                        "training loss keeps falling. Early stopping at that step, more data, or weight decay would help.", out)
+        return out