islkit 0.1.0__py3-none-any.whl

islkit/model.py

@@ -0,0 +1,623 @@
+"""The dual-branch TCN: the pretraining model, and the backbone fine-tuning reuses.
+
+**Why two stacks and not one.** Handshape and location have different temporal
+dynamics. A handshape is close to a held configuration — it changes at
+articulation boundaries and is otherwise flat, so what a filter needs to find is
+*which* configuration is being held. A wrist trajectory is the opposite: it is
+motion throughout, and what matters is its shape over tens of frames. One shared
+filter bank has to compromise between those, and the compromise costs both. Two
+stacks with their own dilations do not.
+
+The split of the 352-dim frame vector:
+
+    branch A   hand-local shapes      126  + velocity 126  = 252 channels
+    branch B   wrist positions + pose  39  + velocity  39  =  78 channels
+    head       non-manual scalars       4  + velocity   4  =   8, pooled straight
+    (gates)    validity mask           14                    multiplied through
+
+Those are all 352. The mask is the part that is easy to miss: it is not a
+channel in either branch. A validity bit is carried per part and **multiplied
+through**, because when the mask was offered to the XGBoost baseline as a feature
+the trees ignored it (0.1% of gain). Here each geometry dim is multiplied by the bit for the part it
+came from, so an absent hand contributes exactly zero rather than a plausible
+hand-shaped vector left over from resampling.
+
+That matters more than it looks. `encode_clip` linearly resamples all 183 dims to
+T=48, the mask included, so on real clips a hand appearing mid-clip leaves
+*fractional* mask values and interpolated geometry at the transition (on INCLUDE,
+8.9% of hand-presence bits are neither 0 nor 1). Gating re-attenuates that
+geometry by exactly the confidence the mask carries.
+
+**Normalise first, then gate.** Each source dim goes through a BatchNorm before
+the gate is applied, so "absent" lands on 0 — the neutral value — rather than on
+whatever -mean/std happens to be. The BatchNorm is also the honest answer to the
+question of z's scale: after body-frame normalisation z is the
+highest-variance channel in the pose block (2.8x x), and per-channel
+standardisation removes that spread before any filter sees it. A tree splits on
+separation and so ignored it; a convolution weights by magnitude and would not.
+
+**Backbone + swappable head, from the start.** Fine-tuning replaces the head with
+a ~40-class one, so `replace_head` and `freeze_backbone` exist from the start
+rather than being retrofitted around whatever pretraining happened to build. The dense
+projection is part of the *backbone*, not the head: it is task-agnostic, and
+keeping it on the frozen side is what makes frozen-backbone-plus-head a real
+option. Transfer measured on synthetic domains says that option loses nothing.
+"""
+
+from __future__ import annotations
+
+import math
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+import torch
+import torch.nn as nn
+
+from islkit.features import DIM_FRAME, DIM_GEOM, N_HAND, N_POSE_SEL
+
+# --------------------------------------------------------------------------
+# Where each dim of the 352-vector goes, and which mask bit gates it
+# --------------------------------------------------------------------------
+
+# The mask block, [169:183], in the order encode_frame writes it.
+MASK_START, MASK_END = DIM_GEOM, DIM_FRAME  # 169, 183
+GATE_HAND = (0, 1)  # slot 0 / slot 1 present
+GATE_POSE_0 = 2  # first of N_POSE_SEL visibility bits
+GATE_FACE = MASK_END - MASK_START - 1  # 13, the face-present bit
+
+_HAND = N_HAND * 3  # 63, one hand's local shape
+_POSE = N_POSE_SEL * 3  # 33, upper-body pose
+
+
+def _branch_indices() -> dict[str, tuple[list[int], list[int]]]:
+    """Source dims and their gating mask bit, per branch.
+
+    Returned rather than hard-coded so the layout is derived from features.py's
+    own constants. A wrong offset here routes the face mesh into the handshape
+    branch and still trains, still converges, and still prints a number — the
+    same failure mode the parquet block-routing test exists for.
+    """
+    a_src, a_gate = [], []
+    for base in (0, DIM_FRAME):  # hand_shape at 0, d_hand_shape at 183
+        for slot in (0, 1):
+            a_src.extend(range(base + slot * _HAND, base + (slot + 1) * _HAND))
+            a_gate.extend([GATE_HAND[slot]] * _HAND)
+
+    b_src, b_gate = [], []
+    wrist_0 = 2 * _HAND  # 126
+    pose_0 = wrist_0 + 6  # 132
+    for base in (0, DIM_FRAME):
+        for slot in (0, 1):  # wrist position shares the hand's validity bit
+            b_src.extend(range(base + wrist_0 + slot * 3, base + wrist_0 + (slot + 1) * 3))
+            b_gate.extend([GATE_HAND[slot]] * 3)
+        for lm in range(N_POSE_SEL):  # each pose landmark has its own visibility
+            b_src.extend(range(base + pose_0 + lm * 3, base + pose_0 + (lm + 1) * 3))
+            b_gate.extend([GATE_POSE_0 + lm] * 3)
+
+    n_src, n_gate = [], []
+    nm_0 = pose_0 + _POSE  # 165
+    for base in (0, DIM_FRAME):
+        n_src.extend(range(base + nm_0, base + nm_0 + 4))
+        n_gate.extend([GATE_FACE] * 4)
+
+    return {"shape": (a_src, a_gate), "motion": (b_src, b_gate), "non_manual": (n_src, n_gate)}
+
+
+BRANCH_INDICES = _branch_indices()
+DIM_SHAPE = len(BRANCH_INDICES["shape"][0])  # 252
+DIM_MOTION = len(BRANCH_INDICES["motion"][0])  # 78
+DIM_NON_MANUAL = len(BRANCH_INDICES["non_manual"][0])  # 8
+DIM_INPUT = DIM_FRAME + DIM_GEOM  # 352
+
+DILATIONS: tuple[int, ...] = (1, 2, 4, 8, 16)
+
+
+# --------------------------------------------------------------------------
+# Building blocks
+# --------------------------------------------------------------------------
+
+
+class TCNBlock(nn.Module):
+    """Two dilated convolutions, then add the input back.
+
+    `padding = dilation * (kernel - 1) // 2` keeps the time axis the same length,
+    so blocks stack without any shape bookkeeping. Residual because with five
+    blocks the useful thing for a later block to learn is a correction, not a
+    replacement.
+    """
+
+    def __init__(self, ch: int, dilation: int, kernel: int = 3, dropout: float = 0.15):
+        super().__init__()
+        pad = dilation * (kernel - 1) // 2
+        self.conv1 = nn.Conv1d(ch, ch, kernel, padding=pad, dilation=dilation)
+        self.conv2 = nn.Conv1d(ch, ch, kernel, padding=pad, dilation=dilation)
+        self.norm1 = nn.BatchNorm1d(ch)
+        self.norm2 = nn.BatchNorm1d(ch)
+        self.act = nn.ReLU()
+        self.drop = nn.Dropout(dropout)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        h = self.drop(self.act(self.norm1(self.conv1(x))))
+        h = self.drop(self.act(self.norm2(self.conv2(h))))
+        return self.act(x + h)
+
+
+class DilatedStack(nn.Module):
+    """One branch: 1x1 stem to `ch` channels, then the dilated residual blocks.
+
+    Input arrives as (B, T, C) — the natural shape out of `encode_clip` — and is
+    transposed to Conv1d's (B, C, T) here, once, in the one place that owns it.
+    """
+
+    def __init__(
+        self,
+        c_in: int,
+        ch: int,
+        dilations: tuple[int, ...] = DILATIONS,
+        kernel: int = 3,
+        dropout: float = 0.15,
+    ):
+        super().__init__()
+        self.stem = nn.Conv1d(c_in, ch, 1)
+        self.blocks = nn.Sequential(*[TCNBlock(ch, d, kernel, dropout) for d in dilations])
+        self.out_ch = ch
+        self.receptive_field = 1 + sum(2 * (kernel - 1) * d for d in dilations)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.blocks(self.stem(x.transpose(1, 2)))
+
+
+# --------------------------------------------------------------------------
+# The backbone
+# --------------------------------------------------------------------------
+
+
+class Backbone(nn.Module):
+    """(B, T, 352) -> (B, embed). Everything fine-tuning keeps.
+
+    Two dilated stacks over the two branches, mean-pooled over time and
+    concatenated with the time-pooled non-manual scalars, then projected to a
+    fixed-width embedding. The classifier on top is one Linear, and is the only
+    part `replace_head` touches.
+    """
+
+    def __init__(
+        self,
+        ch_shape: int = 96,
+        ch_motion: int = 64,
+        embed: int = 192,
+        dilations: tuple[int, ...] = DILATIONS,
+        kernel: int = 3,
+        dropout: float = 0.15,
+        mask_gate: bool = True,
+    ):
+        super().__init__()
+        self.config = {
+            "ch_shape": ch_shape,
+            "ch_motion": ch_motion,
+            "embed": embed,
+            "dilations": list(dilations),
+            "kernel": kernel,
+            "dropout": dropout,
+            "mask_gate": mask_gate,
+        }
+        self.mask_gate = mask_gate
+        self._frozen = False
+
+        for name in ("shape", "motion", "non_manual"):
+            src, gate = BRANCH_INDICES[name]
+            self.register_buffer(f"{name}_src", torch.tensor(src, dtype=torch.long))
+            self.register_buffer(f"{name}_gate", torch.tensor(gate, dtype=torch.long))
+
+        # Per-source-dim standardisation, applied before the gate so that
+        # "absent" is 0 and not an arbitrary offset. See the module docstring.
+        self.norm_shape = nn.BatchNorm1d(DIM_SHAPE)
+        self.norm_motion = nn.BatchNorm1d(DIM_MOTION)
+        self.norm_non_manual = nn.BatchNorm1d(DIM_NON_MANUAL)
+
+        self.shape_stack = DilatedStack(DIM_SHAPE, ch_shape, dilations, kernel, dropout)
+        self.motion_stack = DilatedStack(DIM_MOTION, ch_motion, dilations, kernel, dropout)
+
+        self.project = nn.Sequential(
+            nn.Linear(ch_shape + ch_motion + DIM_NON_MANUAL, embed),
+            nn.BatchNorm1d(embed),
+            nn.ReLU(),
+            nn.Dropout(dropout),
+        )
+        self.out_dim = embed
+        self.receptive_field = self.shape_stack.receptive_field
+
+    def _branch(self, x: torch.Tensor, name: str, norm: nn.Module) -> torch.Tensor:
+        """Gather one branch's dims, standardise them, then gate by the mask."""
+        src = getattr(self, f"{name}_src")
+        out = x.index_select(-1, src)
+        out = norm(out.transpose(1, 2)).transpose(1, 2)  # BatchNorm1d wants (B, C, T)
+        if self.mask_gate:
+            gate = x[..., MASK_START:MASK_END].index_select(-1, getattr(self, f"{name}_gate"))
+            out = out * gate
+        return out
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        if x.shape[-1] != DIM_INPUT:
+            raise ValueError(f"expected (B, T, {DIM_INPUT}) features, got {tuple(x.shape)}")
+
+        a = self.shape_stack(self._branch(x, "shape", self.norm_shape)).mean(dim=2)
+        b = self.motion_stack(self._branch(x, "motion", self.norm_motion)).mean(dim=2)
+        # The four non-manual scalars never enter a convolution. Brow raise and
+        # mouth shape are held configurations, not trajectories, and the baseline measured
+        # them at 1.4% of gain — a dilated stack over four dims would be four
+        # times the parameters for something a mean already says.
+        n = self._branch(x, "non_manual", self.norm_non_manual).mean(dim=1)
+
+        return self.project(torch.cat([a, b, n], dim=1))
+
+    def train(self, mode: bool = True):  # noqa: D102 — nn.Module override
+        # A frozen backbone must stay in eval: BatchNorm updates its running
+        # statistics from the forward pass regardless of requires_grad, so a
+        # "frozen" backbone left in train mode drifts on the fine-tuning set and
+        # the frozen-head result stops being reproducible.
+        return super().train(mode and not self._frozen)
+
+
+class SignClassifier(nn.Module):
+    """Backbone plus a linear head. The head is the part that gets replaced."""
+
+    def __init__(self, backbone: Backbone, n_classes: int):
+        super().__init__()
+        self.backbone = backbone
+        self.head = nn.Linear(backbone.out_dim, n_classes)
+        self.n_classes = n_classes
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.head(self.backbone(x))
+
+
+def build_model(n_classes: int, **kwargs) -> SignClassifier:
+    """A fresh classifier. `kwargs` go to `Backbone`."""
+    return SignClassifier(Backbone(**kwargs), n_classes)
+
+
+def replace_head(model: SignClassifier, n_classes: int) -> SignClassifier:
+    """Swap in a fresh head of a different width, keeping the backbone.
+
+    Fine-tuning's first move: 262 pretraining classes out, ~40 device classes in. The new
+    head lands on the same device as the old one, which is the kind of detail
+    that otherwise surfaces as a device-mismatch error twenty minutes in.
+    """
+    device = next(model.head.parameters()).device
+    model.head = nn.Linear(model.backbone.out_dim, n_classes).to(device)
+    model.n_classes = n_classes
+    return model
+
+
+def freeze_backbone(model: SignClassifier, freeze: bool = True) -> SignClassifier:
+    """Freeze (or unfreeze) everything except the head.
+
+    Both `requires_grad` and BatchNorm mode, because the second is the one that
+    is easy to forget and silently makes the run unreproducible — see
+    `Backbone.train`.
+    """
+    for p in model.backbone.parameters():
+        p.requires_grad = not freeze
+    model.backbone._frozen = freeze
+    model.backbone.train(model.training)
+    return model
+
+
+def n_parameters(model: nn.Module, trainable_only: bool = False) -> int:
+    ps = model.parameters()
+    return sum(p.numel() for p in ps if p.requires_grad or not trainable_only)
+
+
+# --------------------------------------------------------------------------
+# Saving what fine-tuning needs
+# --------------------------------------------------------------------------
+
+
+def save_backbone(backbone: Backbone, path: str | Path, training: dict | None = None) -> Path:
+    """Weights, the config that built them, and how they were trained.
+
+    The config travels with the weights for the same reason the label map does
+    (both are frozen at training time): reconstructing either from code that has moved on since
+    is how a checkpoint loads cleanly and means something else.
+
+    `training` records the run that produced these weights — learning rate,
+    epochs, seed, clip count. The architecture config alone cannot distinguish
+    two checkpoints trained with different hyperparameters, so a re-run silently
+    replaces the file that a committed summary.json claims to describe and
+    nothing anywhere disagrees. `data.py` fingerprints the feature cache against
+    exactly this failure; weights are worth the same treatment.
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    torch.save(
+        {
+            "config": backbone.config,
+            "state_dict": backbone.state_dict(),
+            "training": dict(training or {}),
+        },
+        path,
+    )
+    return path
+
+
+def describe_backbone(path: str | Path) -> dict:
+    """What produced a checkpoint, without building the model.
+
+    For answering "is the file on disk the one the write-up describes?" — which
+    otherwise needs a timestamp and a good memory.
+    """
+    blob = torch.load(Path(path), map_location="cpu", weights_only=True)
+    return {"config": blob["config"], "training": blob.get("training", {})}
+
+
+def load_backbone(path: str | Path, device=None) -> Backbone:
+    """Rebuild a backbone from `save_backbone` output."""
+    blob = torch.load(Path(path), map_location=device or "cpu", weights_only=True)
+    cfg = dict(blob["config"])
+    cfg["dilations"] = tuple(cfg["dilations"])
+    backbone = Backbone(**cfg)
+    backbone.load_state_dict(blob["state_dict"])
+    return backbone.to(device) if device is not None else backbone
+
+
+# Sentinel distinguishing "not passed" (compute it) from an explicit `None`
+# ("write a checkpoint without one" — the pre-guard shape `load_classifier`
+# callers must still be able to load).
+_COMPUTE = object()
+
+
+def save_classifier(
+    model: SignClassifier,
+    path: str | Path,
+    *,
+    labels: str,
+    encoder: dict,
+    training: dict | None = None,
+    encoder_fingerprint: str | None | object = _COMPUTE,
+) -> Path:
+    """Backbone + head + everything needed to feed them correctly.
+
+    `save_backbone` deliberately stores only the backbone, because fine-tuning replaces
+    the head. Inference needs the opposite: a head, and the encoder settings that
+    produced the vectors it was trained on. The label map is frozen because a class order
+    rebuilt at deploy time predicts confidently and wrongly; `T` and `dominant`
+    fail exactly the same way and just as silently, so they travel in the file.
+
+    `labels` is a filename, not a path — the label map ships beside the weights,
+    so the checkpoint records what to look for in its own directory rather than
+    an absolute path that will not survive being copied to the board.
+
+    `encoder_fingerprint` identifies the encoder's behaviour, so a checkpoint
+    can never be served by an encoder it was not fitted on — the same class of
+    silent, confident failure a frozen label map prevents.
+    """
+    # Computed by default so a training run cannot forget it. Passing None
+    # explicitly writes a checkpoint without one, which is what the tests for
+    # the pre-guard path need.
+    signature = None
+    if encoder_fingerprint is _COMPUTE:
+        from islkit.features import encoder_fingerprint as compute
+        from islkit.features import encoder_signature
+
+        encoder_fingerprint = compute()
+        # Travels with the hash because the hash is exact and machines are not:
+        # a checkpoint trained on a laptop must be loadable on the board, and
+        # those two disagree in the last bit of a float32. See features.py.
+        # As a tensor, not the numpy array encoder_signature returns:
+        # load_classifier reads with weights_only=True (it should — a checkpoint
+        # arrives over scp), and that refuses a pickled numpy array outright.
+        signature = torch.from_numpy(encoder_signature())
+
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    torch.save(
+        {
+            "config": model.backbone.config,
+            "n_classes": model.head.out_features,
+            "labels": labels,
+            "encoder": dict(encoder),
+            "encoder_fingerprint": encoder_fingerprint,
+            "encoder_signature": signature,
+            "state_dict": model.state_dict(),
+            "training": dict(training or {}),
+        },
+        path,
+    )
+    return path
+
+
+def load_classifier(path: str | Path, device=None) -> tuple[SignClassifier, dict]:
+    """Rebuild a `save_classifier` file. Returns the model and its metadata."""
+    blob = torch.load(Path(path), map_location=device or "cpu", weights_only=True)
+    cfg = dict(blob["config"])
+    cfg["dilations"] = tuple(cfg["dilations"])
+    model = SignClassifier(Backbone(**cfg), blob["n_classes"])
+    model.load_state_dict(blob["state_dict"])
+    model.eval()
+    if device is not None:
+        model = model.to(device)
+    meta = {k: v for k, v in blob.items() if k != "state_dict"}
+    return model, meta
+
+
+# --------------------------------------------------------------------------
+# Training
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class TrainConfig:
+    """One frozen recipe, for the same reason XGB_PARAMS is frozen.
+
+    The baseline was run with no tuning so that the floor it set was honest. A tuned
+    TCN compared against an untuned baseline measures the search, not the model, so these
+    are ordinary defaults chosen once and left alone.
+
+    `label_smoothing` is deliberately 0.0: the decline confidence threshold
+    has to be re-measured against this model's probabilities, and smoothing would
+    flatten exactly the distribution it needs to read.
+    """
+
+    epochs: int = 60
+    batch: int = 64
+    lr: float = 3e-3
+    weight_decay: float = 1e-4
+    label_smoothing: float = 0.0
+    min_lr: float = 1e-5
+    warmup_epochs: int = 3
+
+
+def _cosine_lr(epoch: int, cfg: TrainConfig) -> float:
+    """Linear warmup then cosine decay, as a multiplier on `cfg.lr`."""
+    if epoch < cfg.warmup_epochs:
+        return (epoch + 1) / max(1, cfg.warmup_epochs)
+    span = max(1, cfg.epochs - cfg.warmup_epochs)
+    t = (epoch - cfg.warmup_epochs) / span
+    floor = cfg.min_lr / cfg.lr
+    return floor + (1 - floor) * 0.5 * (1 + math.cos(math.pi * t))
+
+
+def fit(
+    model: SignClassifier,
+    X: np.ndarray,
+    y: np.ndarray,
+    cfg: TrainConfig | None = None,
+    device=None,
+    X_val: np.ndarray | None = None,
+    y_val: np.ndarray | None = None,
+    verbose: bool = False,
+) -> dict[str, list[float]]:
+    """Train in place. Returns per-epoch loss and accuracy.
+
+    Validation is optional and is only ever used for *reporting a curve*. There
+    is no early stopping and no checkpoint selection on it, because the caller
+    passes the held-out fold and selecting on that would quietly turn the
+    out-of-fold number into a fitted one.
+    """
+    cfg = cfg or TrainConfig()
+    device = device or next(model.parameters()).device
+
+    Xt = torch.as_tensor(np.asarray(X, np.float32)).to(device)
+    yt = torch.as_tensor(np.asarray(y, np.int64)).to(device)
+    opt = torch.optim.AdamW(
+        (p for p in model.parameters() if p.requires_grad),
+        lr=cfg.lr,
+        weight_decay=cfg.weight_decay,
+    )
+    lossfn = nn.CrossEntropyLoss(label_smoothing=cfg.label_smoothing)
+    history: dict[str, list[float]] = {"loss": [], "train_acc": [], "val_acc": []}
+
+    for epoch in range(cfg.epochs):
+        for group in opt.param_groups:
+            group["lr"] = cfg.lr * _cosine_lr(epoch, cfg)
+
+        model.train()
+        order = torch.randperm(len(Xt), device=device)
+        total, correct = 0.0, 0
+        for i in range(0, len(order), cfg.batch):
+            idx = order[i : i + cfg.batch]
+            if len(idx) < 2:
+                continue  # BatchNorm needs more than one row
+            opt.zero_grad()
+            logits = model(Xt[idx])
+            loss = lossfn(logits, yt[idx])
+            loss.backward()
+            opt.step()
+            total += float(loss.detach()) * len(idx)
+            correct += int((logits.argmax(1) == yt[idx]).sum())
+
+        history["loss"].append(total / len(Xt))
+        history["train_acc"].append(correct / len(Xt))
+        if X_val is not None:
+            pred = predict_proba(model, X_val, device=device).argmax(axis=1)
+            history["val_acc"].append(float((pred == np.asarray(y_val)).mean()))
+        if verbose and (epoch % 10 == 9 or epoch == 0):
+            tail = f" val {history['val_acc'][-1] * 100:5.1f}%" if X_val is not None else ""
+            print(
+                f"    epoch {epoch + 1:3d} | loss {history['loss'][-1]:.4f} "
+                f"| train {history['train_acc'][-1] * 100:5.1f}%{tail}",
+                flush=True,
+            )
+    return history
+
+
+@torch.no_grad()
+def predict_proba(
+    model: SignClassifier, X: np.ndarray, device=None, batch: int = 256
+) -> np.ndarray:
+    """Class probabilities, (N, n_classes) float32 on the CPU.
+
+    Softmax rather than logits because the decline threshold and the
+    top-3 figure are both read off probabilities, and because it matches
+    `XGBBaseline.predict_proba` so both models can be driven by the same
+    cross-validation loop.
+    """
+    device = device or next(model.parameters()).device
+    was_training = model.training
+    model.eval()
+    out = []
+    Xa = np.asarray(X, np.float32)
+    for i in range(0, len(Xa), batch):
+        chunk = torch.as_tensor(Xa[i : i + batch]).to(device)
+        out.append(torch.softmax(model(chunk), dim=1).cpu().numpy())
+    model.train(was_training)
+    return np.concatenate(out).astype(np.float32)
+
+
+@dataclass
+class TCNEstimator:
+    """fit / predict_proba around the TCN, so `cross_val_predict` can drive it.
+
+    The TCN's whole claim is a same-split comparison against the baseline. Reusing its
+    cross-validation loop rather than writing a second one is what makes that
+    literally true: identical folds, identical out-of-fold accounting, and the
+    tested guarantee that no model ever scores a row it trained on.
+    """
+
+    n_classes: int
+    cfg: TrainConfig = field(default_factory=TrainConfig)
+    seed: int = 0
+    device: object | None = None
+    backbone_kwargs: dict = field(default_factory=dict)
+    verbose: bool = False
+    # The fold this estimator will be scored on, for a validation *curve* only.
+    # `fit` does no early stopping and no checkpoint selection, so this cannot
+    # leak into the out-of-fold number — it only makes the generalisation gap
+    # visible per epoch instead of only at the end.
+    val: tuple[np.ndarray, np.ndarray] | None = None
+    model: SignClassifier | None = None
+    history: dict = field(default_factory=dict)
+    seconds: float = 0.0
+
+    def fit(self, X: np.ndarray, y: np.ndarray) -> TCNEstimator:
+        from islkit.seeding import set_seed  # noqa: PLC0415 — keeps torch off the import path
+
+        set_seed(self.seed)
+        t0 = time.time()
+        self.model = build_model(self.n_classes, **self.backbone_kwargs).to(self.device)
+        X_val, y_val = self.val if self.val is not None else (None, None)
+        self.history = fit(
+            self.model,
+            X,
+            y,
+            self.cfg,
+            self.device,
+            X_val=X_val,
+            y_val=y_val,
+            verbose=self.verbose,
+        )
+        self.seconds = time.time() - t0
+        return self
+
+    @property
+    def val_size(self) -> int:
+        """Rows in the validation curve. Checked against the fold it should be."""
+        return 0 if self.val is None else len(self.val[1])
+
+    def predict_proba(self, X: np.ndarray) -> np.ndarray:
+        if self.model is None:
+            raise RuntimeError("fit() first")
+        return predict_proba(self.model, X, device=self.device)