refactor(analyzer): drop unused training code from shotnet.py

Nothing in this repository trains ShotNet; the loader, batcher, collate,
loss, gate metrics and the two augmentations were dead weight that read as
a live training path. The poolcoach-rl history keeps them for a retrain.
Gate: shotnet.py 862 -> 449 lines; checkpoint shotnet_20260812_c4b still
loads and the worker boots in 7.3s; shots 6 and 10 re-analysed on CPU give
EVERY field identical to before the trim; pytest 160 passed, 7 skipped.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/poolcoach_cv/shotnet.py

@@ -5,9 +5,8 @@ trajectory.
 The inverse of the RL action space: the observation sequence of ONE shot
 {ball positions in table coordinates, a visibility mask, timestamps} ->
 (V0, phi, a, b), exactly the four dimensions of ``cue.set_state``. Trained
-PURELY on synthetic data (the pilot noise model is the contract), and the
-loader here reads the npz shards WITHOUT pooltool so it can run in the CV
-environment.
+PURELY on synthetic data (the pilot noise model is the contract), and
+inference here needs no pooltool so it can run in the CV environment.
 
 Architecture: a small transformer encoder, a learned **shot token** at the
 head of the sequence from which the outputs are read, and **RoPE on real
@@ -35,27 +34,23 @@ Output heads:
   - optional aux heads: ``v0_ball``/``phi_ball`` (labels the dataset already
     carries); the gate is still scored on the cue V0.
 
-The validation split takes about 2% off TRAIN by seed
-(``val_split_indices``); the 5k held-out set is TEST and must not be touched
-while training or tuning.
-
-Two things exist on the **training path only** (see
-``ShardDataset.set_train_mode``): ``SlotDropoutConfig``, which thins the
-target-ball detections on the fly to cover the density range of real clips,
-and ``TargetReweight``, which pulls the loss weight towards the slice whose
-first contact is at least 0.3s. Neither changes the architecture, the ruler
-or the mapping by one line.
+This module holds the INFERENCE path only. The training code that produced
+``models/shotnet_20260812_c4b`` (the shard loader, the bucketing batcher,
+the collate function, the loss and the gate metrics, plus the slot-dropout
+and target-reweight augmentations) lived here after the port but nothing in
+this repository ran it, so it was removed; it is still in the poolcoach-rl
+history if a retrain is ever needed. ``ShotNetConfig`` is unchanged, so the
+existing checkpoints keep loading.
 
 The spin classification constants (A_SIDE_MIN/B_STUN_MAX) are copied from
-the evaluation harness that owns the ground truth; here they only serve the
-validation metrics and the mapping from a predicted (a, b) to a class.
+the evaluation harness that owns the ground truth; here they serve the
+mapping from a predicted (a, b) to a class.
 """
 
 from __future__ import annotations
 
 import math
-from dataclasses import dataclass, field
-from pathlib import Path
+from dataclasses import dataclass
 
 import numpy as np
 import torch
@@ -130,102 +125,6 @@ def featurize_shot(shot: dict, w: float = TABLE_W_M, l: float = TABLE_L_M,
     return feats, np.asarray(shot["t"], dtype=np.float32)
 
 
-LABEL_KEYS = ("label_v0", "label_phi", "label_a", "label_b", "identifiable",
-              "v0_ball", "phi_ball", "fps", "upconvert", "scratch")
-
-
-# ------------------- augmentation: "sparse target-ball detections"
-# The diagnosis was MEASURED, not guessed: the earlier checkpoint collapsed
-# on real clips because of the DISTRIBUTION of target-ball detection
-# density, not the architecture or the input path -- synthetic training sits
-# at 95-96% visibility (about 5.3 non-cue detections per frame) while one
-# real shot had 1.01 and another 3.09. The augmentation below thins the
-# detections inside the training loader itself (on the fly, with no new
-# dataset written to disk) so the training range covers the measured real
-# range.
-#
-# The dropout produces a mask of 0 EXACTLY like a ball missing from a frame
-# (featurize_shot multiplies coordinates by vis, and the delta block
-# multiplies the two frames' vis together). It touches neither img_diff nor
-# the timestamps nor any other feature.
-
-@dataclass
-class SlotDropoutConfig:
-    """Target-ball slot dropout, with one keep rate per shot.
-
-    ``p_apply``: the fraction of shots that get augmented; the rest pass
-    through the loader BIT IDENTICAL to before (which keeps the synthetic
-    95-96% visibility region in the training distribution -- that region is
-    also the top of the range).
-    ``keep_min``/``keep_max``: the keep rate is ~ U(min, max), applied as an
-    independent Bernoulli per (frame, non-cue slot) cell. The default range
-    [0.10, 0.95] plus the un-augmented branch covers the whole measured real
-    range: one real shot at about 15% per-ball visibility, another at about
-    50%, and the original synthetic data at 95-96%.
-    The ``cue`` slot is NEVER dropped further: the cue track on real clips is
-    already good (coverage 0.90-0.97) and the noise at the start of a shot is
-    part of the pilot contract.
-    """
-
-    p_apply: float = 0.75
-    keep_min: float = 0.10
-    keep_max: float = 0.95
-    seed: int = 20260812
-
-
-def apply_slot_dropout(shot: dict, cfg: SlotDropoutConfig,
-                       rng: np.random.Generator) -> tuple[dict, float]:
-    """Thin ONE shot's target-ball detections -> (a new shot, the keep rate
-    used; 1.0 means no augmentation).
-
-    It does NOT modify in place: ``ShardDataset.raw_shot``'s ``covered`` is a
-    view into the shard array held in RAM, and writing over it would corrupt
-    the dataset for every later epoch.
-    """
-    cov = shot["covered"]
-    tgt = np.flatnonzero(np.asarray(shot["ball_ids"]) != 0)
-    if tgt.size == 0 or rng.random() >= cfg.p_apply:
-        return shot, 1.0
-    keep = float(rng.uniform(cfg.keep_min, cfg.keep_max))
-    cov = np.array(cov, dtype=bool, copy=True)
-    cov[:, tgt] &= rng.random((cov.shape[0], tgt.size)) < keep
-    out = dict(shot)
-    out["covered"] = cov
-    return out, keep
-
-
-# The target-matched slice -- COPIED from the evaluation harness
-# (T_FIRST_TARGET_S; src/ cannot import from the scripts side, same as
-# B_STUN_MAX above). This population matches the real pilot clips and is the
-# official ruler of the acceptance gate.
-T_FIRST_TARGET_S = 0.3
-
-
-@dataclass
-class TargetReweight:
-    """Reweighting towards the target slice: a shot whose first contact is at
-    or after ``t_first_s`` has its loss multiplied by ``weight``.
-
-    Loss weighting was chosen over oversampling deliberately: oversampling a
-    13.6% slice by a factor of 3 would lengthen the epoch by about 27% and
-    break the "identical step budget" condition, so the configs would no
-    longer be comparable with the baseline. The weight applies to EVERY head
-    (v0/phi/ab/ident) through a weighted mean, so the overall gradient scale
-    stays about 1 (an earlier lesson: an off-scale gradient kills a head).
-    """
-
-    weight: float = 3.0
-    t_first_s: float = T_FIRST_TARGET_S
-
-
-def t_first_contact_s(shot: dict) -> float:
-    """The cue's first contact after the strike: min(t_first_bb,
-    t_first_cush) -- NaN when the shot has no collision at all. The same
-    formula as the evaluation harness."""
-    vals = [float(v) for v in (shot["t_first_bb"], shot["t_first_cush"])
-            if not math.isnan(float(v))]
-    return min(vals) if vals else math.nan
-
 
 # ------------------------- sim to real: build a shot from the app's track
 # The sim-to-real input gap is the main risk here: the net trains with
@@ -366,194 +265,6 @@ def shot_from_track(rows: list[dict], others: list[dict] | None
             "n_frames": F, "n_balls": K + 1}
 
 
-# --------------------------------------------------------------- dataset
-
-class ShardDataset:
-    """Load a list of npz shards into RAM (ragged plus offsets, about 2.4 GB
-    for 150k shots) and hand back featurized shots. It needs no pooltool, and
-    nothing depends on torch until ``collate`` (so the loader tests run in
-    pure numpy).
-
-    ``indices``: GLOBAL indices (shards sorted, then local index) -- used for
-    the train/val split. ``limit_shots``: truncate each shard (smoke tests).
-
-    ``augment``/``reweight`` only take effect under ``set_train_mode(True)``.
-    They default to OFF, because every evaluation path (the held-out harness,
-    the app worker, the per-epoch validation) has to see the same data as the
-    baseline, otherwise the numbers are not comparable.
-    """
-
-    _META = ("label_v0", "label_phi", "label_a", "label_b", "v0_ball",
-             "phi_ball", "identifiable", "scratch", "fps", "upconvert",
-             "t_first_bb", "t_first_cush", "n_frames", "n_balls", "shot_idx")
-
-    def __init__(self, shard_paths: list[Path], limit_shots: int = 0,
-                 deltas: bool = False,
-                 augment: SlotDropoutConfig | None = None,
-                 reweight: TargetReweight | None = None):
-        self.deltas = deltas
-        self.augment = augment
-        self.reweight = reweight
-        self._train_mode = False
-        self._epoch = 0
-        self.shards = []
-        self._index: list[tuple[int, int]] = []
-        for si, p in enumerate(sorted(Path(q) for q in shard_paths)):
-            z = np.load(p)
-            S = len(z["shot_idx"])
-            if limit_shots:
-                S = min(S, limit_shots)
-            sh = {k: np.asarray(z[k]) for k in self._META}
-            sh["xy"] = np.asarray(z["xy"], dtype=np.float32)
-            sh["covered"] = np.asarray(z["covered"]).astype(bool)
-            sh["img_diff"] = np.asarray(z["img_diff"], dtype=np.float32)
-            sh["ball_ids"] = np.asarray(z["ball_ids"])
-            sh["xy_off"] = np.asarray(z["xy_off"], dtype=np.int64)
-            sh["f_off"] = np.asarray(z["f_off"], dtype=np.int64)
-            sh["b_off"] = np.asarray(z["b_off"], dtype=np.int64)
-            self.shards.append(sh)
-            self._index.extend((si, li) for li in range(S))
-        self.lengths = np.array(
-            [self.shards[si]["n_frames"][li] for si, li in self._index],
-            dtype=np.int64)
-
-    def __len__(self) -> int:
-        return len(self._index)
-
-    def set_train_mode(self, on: bool, epoch: int = 0) -> None:
-        """Turn augmentation and reweighting on or off, and fix the epoch for
-        the RNG.
-
-        Training turns it on (a different epoch gives a different mask, still
-        reproducible from ``[seed, epoch, i]``); validation and evaluation
-        turn it off. One flag for both, because both only mean anything on
-        the training path -- validation numbers have to stay comparable
-        across configs.
-        """
-        self._train_mode = bool(on)
-        self._epoch = int(epoch)
-
-    def raw_shot(self, i: int) -> dict:
-        """The raw shot dict, in the same shape the dataset generator
-        produced."""
-        si, li = self._index[i]
-        sh = self.shards[si]
-        F_n = int(sh["n_frames"][li])
-        B = int(sh["n_balls"][li])
-        x0, f0, b0 = (int(sh["xy_off"][li]), int(sh["f_off"][li]),
-                      int(sh["b_off"][li]))
-        shot = {k: sh[k][li].item() for k in self._META
-                if k not in ("n_frames", "n_balls")}
-        shot["n_frames"], shot["n_balls"] = F_n, B
-        shot["t"] = (np.arange(F_n) / float(sh["fps"][li])).astype(np.float32)
-        shot["xy"] = sh["xy"][x0:x0 + F_n * B].reshape(F_n, B, 2)
-        shot["covered"] = sh["covered"][x0:x0 + F_n * B].reshape(F_n, B)
-        shot["img_diff"] = sh["img_diff"][f0:f0 + F_n]
-        shot["ball_ids"] = sh["ball_ids"][b0:b0 + B]
-        return shot
-
-    def __getitem__(self, i: int) -> dict:
-        shot = self.raw_shot(i)
-        keep = 1.0
-        if self._train_mode and self.augment is not None:
-            # the RNG is keyed on [seed, epoch, i]: the same triple gives the
-            # same mask (every epoch is reproducible) while a different epoch
-            # gives a different one (genuinely on-the-fly augmentation rather
-            # than one fixed thinned copy)
-            rng = np.random.default_rng(
-                [self.augment.seed, self._epoch, int(i)])
-            shot, keep = apply_slot_dropout(shot, self.augment, rng)
-        feats, t = featurize_shot(shot, deltas=self.deltas)
-        item = {"feats": feats, "t": t}
-        for k in LABEL_KEYS:
-            item[k] = float(shot[k])
-        item["keep_rate"] = keep          # diagnostics/tests, not collated
-        if self._train_mode and self.reweight is not None:
-            tf = t_first_contact_s(shot)
-            item["sample_w"] = (self.reweight.weight
-                                if (not math.isnan(tf))
-                                and tf >= self.reweight.t_first_s else 1.0)
-        return item
-
-
-def val_split_indices(n_total: int, val_frac: float,
-                      seed: int) -> tuple[np.ndarray, np.ndarray]:
-    """A validation split of about ``val_frac`` taken off TRAIN by seed --
-    deterministic, disjoint, and independent of the machine or the shard
-    layout. Returns (train_idx, val_idx), both sorted."""
-    perm = np.random.default_rng(seed).permutation(n_total)
-    n_val = int(round(n_total * val_frac))
-    return np.sort(perm[n_val:]), np.sort(perm[:n_val])
-
-
-class BucketBatcher:
-    """Group batches by TOKEN BUDGET (max length in the batch x batch size <=
-    budget) after a length sort with jitter. Sequences run from 13 to 1192
-    frames, so a fixed batch size either blows up VRAM on the long tail or
-    wastes it on padding at the short end (the development GPU has 8 GB).
-    Batch order is shuffled from [seed, epoch], so every epoch is
-    reproducible."""
-
-    def __init__(self, lengths: np.ndarray, indices: np.ndarray,
-                 token_budget: int = 40_000, max_batch: int = 256,
-                 seed: int = 0):
-        self.lengths, self.indices = lengths, np.asarray(indices)
-        self.token_budget, self.max_batch = token_budget, max_batch
-        self.seed = seed
-
-    def epoch_batches(self, epoch: int, shuffle: bool = True) -> list[np.ndarray]:
-        rng = np.random.default_rng([self.seed, epoch])
-        lens = self.lengths[self.indices].astype(np.float64)
-        if shuffle:
-            lens = lens * rng.uniform(0.9, 1.1, len(lens))
-        order = self.indices[np.argsort(lens, kind="stable")]
-        batches, cur, cur_max = [], [], 0
-        for i in order:
-            li = int(self.lengths[i])
-            new_max = max(cur_max, li)
-            if cur and ((len(cur) + 1) * new_max > self.token_budget
-                        or len(cur) >= self.max_batch):
-                batches.append(np.array(cur))
-                cur, cur_max = [], 0
-                new_max = li
-            cur.append(int(i))
-            cur_max = new_max
-        if cur:
-            batches.append(np.array(cur))
-        if shuffle:
-            rng.shuffle(batches)
-        return batches
-
-
-def collate(items: list[dict]) -> dict:
-    """Pad to the batch's max length and produce torch tensors. ``mask``
-    True means a real frame, False means padding.
-
-    ``sample_w`` only appears when the loader emits it -- a batch without
-    that key goes through EXACTLY the old loss code path, not the
-    weighted-mean branch.
-    """
-    B = len(items)
-    T = max(len(it["t"]) for it in items)
-    dim = items[0]["feats"].shape[1]
-    x = torch.zeros(B, T, dim, dtype=torch.float32)
-    t = torch.zeros(B, T, dtype=torch.float32)
-    mask = torch.zeros(B, T, dtype=torch.bool)
-    for i, it in enumerate(items):
-        n = len(it["t"])
-        x[i, :n] = torch.from_numpy(np.ascontiguousarray(it["feats"]))
-        t[i, :n] = torch.from_numpy(np.ascontiguousarray(it["t"]))
-        mask[i, :n] = True
-    out = {"x": x, "t": t, "mask": mask}
-    for k in LABEL_KEYS:
-        out[k] = torch.tensor([it[k] for it in items], dtype=torch.float32)
-    if any("sample_w" in it for it in items):
-        out["sample_w"] = torch.tensor(
-            [float(it.get("sample_w", 1.0)) for it in items],
-            dtype=torch.float32)
-    return out
-
-
 # ----------------------------------------------------------------- model
 
 @dataclass
@@ -721,107 +432,8 @@ class ShotNet(nn.Module):
                 "p_ident": torch.sigmoid(out["ident_logit"]).cpu().numpy()}
 
 
-# ------------------------------------------------------------------ loss
-
-def _phi_vec_loss(pred_vec: torch.Tensor,
-                  phi_deg: torch.Tensor) -> torch.Tensor:
-    """MSE against the unit vector (cos phi, sin phi) -- continuous across
-    0/360."""
-    rad = torch.deg2rad(phi_deg)
-    target = torch.stack([torch.cos(rad), torch.sin(rad)], dim=-1)
-    return F.mse_loss(pred_vec, target, reduction="none").sum(-1)
-
-
-def _phi_ang_huber(pred_vec: torch.Tensor, phi_deg: torch.Tensor,
-                   delta_deg: float) -> torch.Tensor:
-    """Huber on the ANGULAR DISTANCE (in radians, with delta given in
-    degrees): the difference comes through atan2(sin, cos), so it is
-    continuous across 0/360. Compared with vec-MSE: the same ~delta^2
-    curvature when small, but beyond delta the gradient does NOT keep growing
-    with sin(delta) -- hopeless shots (delta ~90 deg) are capped and the bulk
-    of the distribution (which decides the gate's MEDIAN) is not crushed by
-    the tail. A light penalty keeps ||pred_vec|| near 1 (direction is the
-    signal, but the norm must not collapse)."""
-    rad = torch.deg2rad(phi_deg)
-    norm = torch.linalg.vector_norm(pred_vec, dim=-1)
-    u = pred_vec / (norm[..., None] + 1e-6)
-    cos_d = u[..., 0] * torch.cos(rad) + u[..., 1] * torch.sin(rad)
-    sin_d = u[..., 1] * torch.cos(rad) - u[..., 0] * torch.sin(rad)
-    d_rad = torch.atan2(sin_d, cos_d).abs()
-    hub = F.huber_loss(d_rad, torch.zeros_like(d_rad),
-                       delta=math.radians(delta_deg), reduction="none")
-    return hub + 0.01 * (norm - 1.0) ** 2
-
-
-def shotnet_loss(out: dict, batch: dict, cfg: ShotNetConfig) -> dict:
-    """The total loss plus each head's. (a, b) is only scored on
-    identifiable shots.
-
-    When ``batch["sample_w"]`` is PRESENT, every head reduces with a WEIGHTED
-    MEAN ``sum(w.l)/sum(w)`` instead of a plain mean, so the loss scale (and
-    therefore the gradient scale) stays about 1 even though the target
-    slice's weight is 3. WITHOUT that key the expression is the old one,
-    unchanged down to the arithmetic, so the configs stay comparable number
-    for number.
-    """
-    w = batch.get("sample_w")
-    if w is None:
-        def red(x):
-            return x.mean()
-
-        def red_m(x, m):
-            return (x * m).sum() / m.sum().clamp(min=1.0)
-    else:
-        def red(x):
-            return (x * w).sum() / w.sum().clamp(min=1e-6)
-
-        def red_m(x, m):
-            return (x * m * w).sum() / (m * w).sum().clamp(min=1e-6)
-
-    v0_t = batch["label_v0"]
-    v0_target = torch.log(v0_t) if cfg.v0_log else v0_t
-    l_v0 = red(F.huber_loss(out["v0_z"], v0_target, delta=cfg.huber_v0,
-                            reduction="none"))
-    if cfg.phi_loss == "ang_huber":
-        l_phi = red(_phi_ang_huber(out["phi_vec"], batch["label_phi"],
-                                   cfg.phi_huber_deg))
-    else:
-        l_phi = red(_phi_vec_loss(out["phi_vec"], batch["label_phi"]))
-    ab_target = torch.stack([batch["label_a"], batch["label_b"]],
-                            dim=-1) / cfg.ab_scale
-    l_ab_per = F.huber_loss(out["ab"], ab_target, delta=cfg.huber_ab,
-                            reduction="none").mean(-1)
-    m = batch["identifiable"]
-    l_ab = red_m(l_ab_per, m)
-    l_id = red(F.binary_cross_entropy_with_logits(out["ident_logit"], m,
-                                                  reduction="none"))
-    total = (cfg.w_v0 * l_v0 + cfg.w_phi * l_phi + cfg.w_ab * l_ab
-             + cfg.w_ident * l_id)
-    parts = {"v0": l_v0, "phi": l_phi, "ab": l_ab, "ident": l_id}
-    if cfg.aux_ball:
-        vb = batch["v0_ball"].clamp(min=1e-3)
-        l_avb = red(F.huber_loss(out["v0_ball_z"],
-                                 torch.log(vb) if cfg.v0_log else vb,
-                                 delta=cfg.huber_v0, reduction="none"))
-        if cfg.phi_loss == "ang_huber":
-            l_apb = red(_phi_ang_huber(out["phi_ball_vec"],
-                                       batch["phi_ball"], cfg.phi_huber_deg))
-        else:
-            l_apb = red(_phi_vec_loss(out["phi_ball_vec"],
-                                      batch["phi_ball"]))
-        total = total + cfg.w_aux * (l_avb + l_apb)
-        parts.update({"aux_v0_ball": l_avb, "aux_phi_ball": l_apb})
-    parts["total"] = total
-    return parts
-
-
 # --------------------------------------------------------------- metrics
 
-def circ_diff_deg(x: np.ndarray, y: np.ndarray) -> np.ndarray:
-    """|delta phi| on the circle, in degrees -- the same formula as the
-    evaluation harness."""
-    return np.abs(((np.asarray(x) - np.asarray(y) + 180.0) % 360.0) - 180.0)
-
 
 def spin_classes(a: np.ndarray, b: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
     """(a, b) -> (vert, side) at the harness's ground-truth thresholds. vert
@@ -835,28 +447,3 @@ def spin_classes(a: np.ndarray, b: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
     return vert, side
 
 
-def gate_metrics(pred: dict, labels: dict) -> dict:
-    """The four gate metrics, measured on one set (validation every epoch):
-      - dphi_med:      the median |delta phi| over the whole set (degrees)
-      - v0_relerr_med: the median |V0_hat - V0|/V0 (raw, cue ruler)
-      - side_acc:      the sign of a (a plain sign, NO dead zone -- the net
-                       does not abstain) over identifiable shots whose ground
-                       truth side is not neutral
-      - vert_acc:      the three classes follow/stun/draw (b_hat quantised at
-                       B_STUN_MAX) over ALL identifiable shots
-    """
-    ident = np.asarray(labels["identifiable"]) > 0.5
-    dphi = circ_diff_deg(pred["phi_deg"], labels["label_phi"])
-    relerr = np.abs(pred["v0"] - labels["label_v0"]) / labels["label_v0"]
-    gt_vert, gt_side = spin_classes(labels["label_a"], labels["label_b"])
-    pv, _ = spin_classes(pred["a"], pred["b"])
-    side_mask = ident & (gt_side != "")
-    side_ok = (np.sign(pred["a"]) == np.sign(labels["label_a"]))[side_mask]
-    vert_ok = (pv == gt_vert)[ident]
-    id_acc = ((pred["p_ident"] > 0.5) == ident).mean()
-    return {"dphi_med": float(np.median(dphi)),
-            "v0_relerr_med": float(np.median(relerr)),
-            "side_acc": float(side_ok.mean()) if side_ok.size else float("nan"),
-            "vert_acc": float(vert_ok.mean()) if vert_ok.size else float("nan"),
-            "n_side": int(side_mask.sum()), "n_ident": int(ident.sum()),
-            "ident_acc": float(id_acc)}