"""Wrappers around every SuperHugeAAD envelope decoder with one interface.

    dec.fit(train_trials, val_trials, meta)   train on the training datasets only
    dec.features(trial) -> (A, B0, B1)         per-sample arrays; evidence r_s = mean_f corr(A_f, Bs_f) in a window
    dec.lookahead_s                            future data used per output sample (s), for label stamping

Linear decoders use the package classes (update/fit) wherever they run at corpus scale; deviations are noted.
DNNs use the package backbone + the RegressionInterface output head (EinMix -> 1 feature), trained with a
contrastive Pearson loss (-r(attended) + r(ignored)) on 5-s windows.
"""
from __future__ import annotations

import importlib
import math
import time

import numpy as np
import torch
import yaml
from einops.layers.torch import EinMix

from common_exp import CFG, EXP, FS, ROOT

L = CFG["linear"]
D = CFG["dnn"]
DEV = torch.device("cuda" if torch.cuda.is_available() else "cpu")


def _t(x):
    return torch.from_numpy(np.ascontiguousarray(x, dtype=np.float32))


def _targets(tr):
    """(T, 2 streams, F) DNN targets per D['targets']: 'env' = the prep's envelope, 'onset' = half-wave rectified
    first difference of it (causal: t and t-1 only), 'delta'/'theta' = causal band-passed envelope, 'glim'/'mask' =
    causal band-passed envelope where the talker is clearly louder than the other / not (build_glimpse.py)."""
    feats = []
    for f in D.get("targets", ["env"]):
        if f == "env":
            feats.append(tr["env"])
        elif f in ("delta", "theta"):                         # envelope modulation bands, CAUSAL band-pass
            from scipy.signal import butter, sosfilt
            lo, hi = (1.0, 4.0) if f == "delta" else (4.0, 8.0)
            b = sosfilt(butter(2, [lo, hi], "bandpass", fs=FS, output="sos"), tr["env"].astype(np.float64), axis=0)
            feats.append(b.astype(np.float32))                # no trial-level normalisation (see below)
        elif f in ("glim", "mask", "dom", "orel", "odiff", "ediff"):                           # build_glimpse.py: glimpsed / masked part, causal
            feats.append(tr[f])
        elif f == "onset":
            # No full-trial z-score here: the rules exempt the full-trial z-score only ONCE per pipeline (already
            # used on the envelope). Loss and evidence are Pearson correlations per window, which are invariant to a
            # trial-level affine rescaling, so dropping it changes nothing numerically.
            feats.append(np.maximum(0.0, np.diff(tr["env"], axis=0, prepend=tr["env"][:1])))
    return np.stack(feats, -1).astype(np.float32)


def _att_tgt(tr):
    """Attended / ignored DNN targets: (T,) each for one target (unchanged behaviour), (T, F) for several."""
    Y = _targets(tr)
    idx = np.arange(len(Y))
    a = tr["att"].astype(int)[: len(Y)]
    ya, yi = Y[idx, a], Y[idx, 1 - a]
    return (ya[:, 0], yi[:, 0]) if ya.shape[1] == 1 else (ya, yi)


def _att_env(tr):
    idx = np.arange(len(tr["env"]))
    a = tr["att"].astype(int)
    return tr["env"][idx, a], tr["env"][idx, 1 - a]


# =====================================================================================================================
# Linear decoders
# =====================================================================================================================
class BackwardWF:
    """superhuge.model.linear.WienerFilter (Ledoit-Wolf covariance, EEG lags 0-400 ms, as the official baseline)."""
    name = "wf"
    lookahead_s = L["wf_lags"][1]

    def __init__(self, C):
        from superhuge.model.linear import WienerFilter
        self.m = WienerFilter(lags=L["wf_lags"], l2=0.0, use_lwcov=True, fs=FS, window_length=1, num_channels=C)

    def fit(self, train, val, meta):
        for tr in train:
            ya, _ = _att_env(tr)
            self.m.update(_t(tr["eeg"])[None], _t(ya)[None, :, None, None])
        self.m.fit()

    def reconstruct(self, tr):
        with torch.no_grad():
            y, _ = self.m.predict(_t(tr["eeg"])[None], _t(tr["env"])[None, :, None, :])
        return y[0, :, 0].numpy()

    def features(self, tr):
        y = self.reconstruct(tr)
        return y, tr["env"][:, 0], tr["env"][:, 1]


class PerSubjectWF(BackwardWF):
    """superhuge.model.linear.PerSubjectWienerFilter: Rxx estimated per subject, averaged across subjects."""
    name = "wf_persubject"

    def __init__(self, C):
        from superhuge.model.linear import PerSubjectWienerFilter
        self.m = PerSubjectWienerFilter(lags=L["wf_lags"], l2=0.0, use_lwcov=True, fs=FS, window_length=1, num_channels=C)

    def fit(self, train, val, meta):
        for tr, (dsid, sid) in zip(train, meta):
            ya, _ = _att_env(tr)
            self.m.update(_t(tr["eeg"])[None], _t(ya)[None, :, None, None],
                          meta={"dataset_id": torch.tensor([dsid]), "subject_id": torch.tensor([sid])})
        self.m.fit()


class RiemannWF(BackwardWF):
    """Riemannian Wiener filter. DEVIATION: the package class stores one p x p matrix per SAMPLE (infeasible at corpus
    scale), so Rxx = Riemannian (affine-invariant) mean of the per-SUBJECT lagged covariances, rxy = mean over subjects."""
    name = "wf_riemann"

    def __init__(self, C):
        from superhuge.model.linear import WienerFilter
        self.m = WienerFilter(lags=L["wf_lags"], l2=0.0, use_lwcov=False, fs=FS, window_length=1, num_channels=C)

    def fit(self, train, val, meta):
        from pyriemann.geometry.mean import mean_riemann
        stats = {}
        for tr, key in zip(train, meta):
            ya, _ = _att_env(tr)
            X = self.m.lag_and_flatten(_t(tr["eeg"])[None], "batch time lag channel -> (batch time) (lag channel)",
                                       self.m.cfg.lag_start_samples, self.m.cfg.lag_end_samples).double()
            s = stats.setdefault(key, [0, 0, 0])
            s[0] = s[0] + X.T @ X
            s[1] = s[1] + X.T @ _t(ya).double()[:, None]
            s[2] += len(X)
        R = np.array([(v[0] / v[2]).numpy() for v in stats.values()])
        p = R.shape[1]
        R = R + L["l2_rel"] * np.trace(R, axis1=1, axis2=2)[:, None, None] / p * np.eye(p)[None]
        Rm = mean_riemann(torch.from_numpy(R)).numpy()      # torch input: pyriemann 0.12 needs .mT (numpy >= 2)
        r = np.mean([(v[1] / v[2]).numpy() for v in stats.values()], 0)
        self.m.weights = torch.from_numpy(np.linalg.solve(Rm, r)).float()
        self.m._fitted = True


class ForwardWF:
    """superhuge.model.linear.ForwardWienerFilter (encoding model EEG(t) from envelope(t-0.4..t)); fitted with the package
    class. DEVIATION: its predict() has an invalid einops pattern, so predictions are computed from its fitted weights.
    Evidence: mean over channels of corr(EEG, predicted EEG from stream s). Uses no future data."""
    name = "wf_forward"
    lookahead_s = 0.0

    def __init__(self, C):
        from superhuge.model.linear import ForwardWienerFilter
        self.C = C
        self.m = ForwardWienerFilter(lags=L["fwd_lags"], l2=0.0, fs=FS, num_features=1, num_channels=C)

    def fit(self, train, val, meta):
        for tr in train:
            ya, _ = _att_env(tr)
            self.m.update(_t(tr["eeg"])[None], _t(ya)[None, :, None, None])
        # relative ridge instead of the absolute l2 (the statistics are sums over millions of samples)
        n = self.m._n_samples
        Rxx, Rxy = self.m.Rxx / n, self.m.Rxy / n
        p = Rxx.shape[0]
        Rxx = Rxx + L["l2_rel"] * torch.trace(Rxx) / p * torch.eye(p)
        self.W = torch.linalg.solve(Rxx, Rxy)                     # (lag*1, C)

    def features(self, tr):
        out = []
        for s in (0, 1):
            e = _t(tr["env"][:, s])[None, :, None]
            X = self.m.lag_and_flatten(e, "batch time lag channel -> (batch time) (lag channel)",
                                       self.m.cfg.lag_start_samples, self.m.cfg.lag_end_samples)
            out.append((X @ self.W).numpy())
        return tr["eeg"], out[0], out[1]


class CCADec:
    """superhuge.model.linear.CCA: lagged EEG (0-400 ms) vs lagged envelope (-250..0 ms), 3 components.
    Evidence: mean over components of corr(EEG projection, envelope projection of stream s)."""
    name = "cca"
    lookahead_s = L["cca_x_lags"][1]

    def __init__(self, C):
        from superhuge.model.linear import CCA
        self.m = CCA(x_lags=L["cca_x_lags"], y_lags=L["cca_y_lags"], l2=0.0, num_components=L["cca_components"],
                     fs=FS, num_channels=C, num_audio_features={"env": 1})

    def fit(self, train, val, meta):
        for tr in train:
            ya, _ = _att_env(tr)
            self.m.update(_t(tr["eeg"])[None], _t(ya)[None, :, None, None])
        self.m.fit()

    def features(self, tr):
        with torch.no_grad():
            xp, yp = self.m.predict(_t(tr["eeg"])[None], _t(tr["env"])[None, :, None, :])
        return xp[0].numpy(), yp[0, :, :, 0].numpy(), yp[0, :, :, 1].numpy()


class FBCCADec:
    """superhuge.model.linear.FilterbankCCA: FIR filter bank (lengths 2-32 samples) on EEG and envelope, 3 components.
    Its conv uses padding='same' (non-causal): lookahead = half the longest filter = 0.5 s.
    DEVIATION: fit() re-implemented around the package solver because update() never counts samples (fit -> NaN)."""
    name = "fbcca"
    lookahead_s = (max(L["fbcca_ir_lengths"]) // 2) / FS

    def __init__(self, C):
        from superhuge.model.linear import FilterbankCCA
        self.m = FilterbankCCA(fs=FS, impulse_response_lengths=L["fbcca_ir_lengths"], num_components=L["fbcca_components"],
                               num_channels=C, num_audio_features={"env": 1})

    def fit(self, train, val, meta):
        from superhuge.model.linear.regression.fb_cca import canonical_correlation_analysis
        n = 0
        for tr in train:
            ya, _ = _att_env(tr)
            self.m.update(_t(tr["eeg"])[None], _t(ya)[None, :, None, None])
            n += len(ya)
        # PACKAGE BUG: FilterbankCCA.update() never increments _n_samples, so its fit() divides by 0 (NaN covariance).
        # Same CCA solver on the correctly normalised covariance (float64, tiny relative ridge).
        cov = (self.m.Rxyxy / n).double()
        p = cov.shape[0]
        cov = cov + 1e-6 * torch.trace(cov) / p * torch.eye(p, dtype=cov.dtype)
        wx, wy = canonical_correlation_analysis(cov_matrix=cov, num_features_x=self.m.cfg.num_channels * len(L["fbcca_ir_lengths"]),
                                                reg_strength=1e-5, num_components=self.m.cfg.num_components)
        self.m.weight_x, self.m.weight_y = wx.float(), wy.float()
        self.m._fitted = True

    def features(self, tr):
        with torch.no_grad():
            out = []
            for s in (0, 1):
                xp, yp = self.m.predict(_t(tr["eeg"])[None], _t(tr["env"][:, s])[None, :, None, None])
                out.append(yp.numpy())
        return xp.numpy(), out[0], out[1]


# =====================================================================================================================
# DNN decoders
# =====================================================================================================================
MODEL_CFG = f"{ROOT}/baselines/python/SuperHugeAAD/train/configs/models/"


class VLAAIwsPatched(torch.nn.Module):
    """VLAAI_ws with a minimal fix. The package class raises NameError ('_' undefined) because a weight-shared block
    cannot take num_channels inputs in block 1 and num_kernels[-1] afterwards. Fix: 1x1 input projection
    C -> num_kernels[-1], then the shared block from the package."""

    def __init__(self, *, nb_blocks, extractor_args, output_context_kernel_size, use_skip=True, dropout=0.0, **kw):
        super().__init__()
        from superhuge.model.pure_cnn.vlaai import vlaai_block
        k = extractor_args.num_kernels[-1]
        self.proj = torch.nn.Conv1d(kw["num_channels"], k, 1)
        self.block = vlaai_block(num_kernels=extractor_args.num_kernels, kernel_sizes=extractor_args.kernel_sizes,
                                 output_context_kernel_size=output_context_kernel_size, num_channels=k,
                                 time_dim=kw["fs"] * kw["window_length"], drouput=dropout)
        self.nb_blocks, self.use_skip = nb_blocks, use_skip

    def forward(self, x):
        x = self.proj(x.transpose(1, 2))
        h = x
        for i in range(self.nb_blocks):
            if self.use_skip and i > 0:
                h = h + x
            h = self.block(h)
        return h.transpose(1, 2)


MODEL_OVERRIDES = {}   # name -> dict of model_args overriding the package yaml (debug / ablations); empty by default


class ADT(torch.nn.Module):
    """ADT-style decoder (auditory decoding transformer; Xu et al. 2024, PMC11489951), re-implemented:
    spatio-temporal convolution front-end, learned positional embedding, transformer layers whose attention is
    ANTICAUSAL-BANDED: output time t attends only to EEG times t .. t + resp (the brain responds AFTER the sound),
    resp = 0.5 s. The causal read-out of DNNDec still limits every output to <= 0.75 s of future EEG."""

    def __init__(self, C, W, d=64, heads=4, layers=2, ff=128, dropout=0.1, resp_s=0.5):
        super().__init__()
        self.front = torch.nn.Sequential(
            torch.nn.Conv1d(C, d, 9, padding=4), torch.nn.GELU(), torch.nn.Dropout(dropout),
            torch.nn.Conv1d(d, d, 9, padding=4), torch.nn.GELU())
        self.pos = torch.nn.Parameter(torch.zeros(1, W, d))
        layer = torch.nn.TransformerEncoderLayer(d, heads, ff, dropout, batch_first=True, norm_first=True)
        self.enc = torch.nn.TransformerEncoder(layer, layers)
        t = torch.arange(W)
        r = int(resp_s * FS)
        allowed = (t[None, :] >= t[:, None]) & (t[None, :] <= t[:, None] + r)   # query t -> keys t..t+r
        self.register_buffer("mask", ~allowed)                                   # True = masked

    def forward(self, x):                                       # (B, W, C) -> (B, W, d)
        h = self.front(x.transpose(1, 2)).transpose(1, 2) + self.pos[:, : x.shape[1]]
        return self.enc(h, mask=self.mask[: x.shape[1], : x.shape[1]])


class _PreLNFFTBlock(torch.nn.Module):
    """FastSpeech feed-forward transformer block with pre-layer normalisation (HappyQuokka): x + MHA(LN(x)), then
    x + Conv1d(k1) -> ReLU -> Conv1d(k2) of LN(x); dropout on both residual branches."""

    def __init__(self, d, d_inner, heads, kernels, dropout):
        super().__init__()
        self.ln1, self.ln2 = torch.nn.LayerNorm(d), torch.nn.LayerNorm(d)
        self.att = torch.nn.MultiheadAttention(d, heads, dropout=0.1, batch_first=True)
        self.w1 = torch.nn.Conv1d(d, d_inner, kernels[0], padding=kernels[0] // 2)
        self.w2 = torch.nn.Conv1d(d_inner, d, kernels[1], padding=kernels[1] // 2)
        self.drop = torch.nn.Dropout(dropout)

    def forward(self, x):
        h = self.ln1(x)
        x = x + self.drop(self.att(h, h, h, need_weights=False)[0])
        h = self.ln2(x).transpose(1, 2)
        return x + self.drop(self.w2(torch.relu(self.w1(h))).transpose(1, 2))


class HappyQuokka(torch.nn.Module):
    """HappyQuokka (Piao et al., ICASSP 2023 Auditory EEG Challenge, regression winner; official code
    github.com/jkyunnng/HappyQuokka_system_for_EEG_Challenge): pre-conv (kernel 7) -> 8 pre-LN FFT blocks
    (d_model 128, d_inner 1024, 2 heads, FFN conv kernels (9, 1), dropout 0.3) -> linear (the Net head here).
    No positional encoding (as the original). DEVIATIONS: no subject global conditioner (LODO subjects are unseen;
    subject IDs may not be inputs); trained with this benchmark's losses (contrastive / Pearson) instead of
    -Pearson + 0.2 L1; full attention inside the window, the causal read-out of DNNDec keeps <= 0.75 s future."""

    def __init__(self, C, d=128, d_inner=1024, heads=2, layers=8, kernels=(9, 1), dropout=0.3):
        super().__init__()
        self.pre = torch.nn.Conv1d(C, d, 7, padding=3)
        self.blocks = torch.nn.ModuleList([_PreLNFFTBlock(d, d_inner, heads, kernels, dropout) for _ in range(layers)])

    def forward(self, x):                                       # (B, W, C) -> (B, W, d)
        h = self.pre(x.transpose(1, 2)).transpose(1, 2)
        for b in self.blocks:
            h = b(h)
        return h


def build_backbone(name, C, W):
    from superhuge.model.pure_cnn import ExtractorParams
    common = dict(fs=FS, window_length=int(W / FS), num_channels=C, num_audio_features={"env": 1})
    if name == "adt":
        return ADT(C, W)
    if name == "happyquokka":
        return HappyQuokka(C, **MODEL_OVERRIDES.get(name, {}))
    if name == "vlaai_ws":
        # size sweep (--set model_blocks=N model_kernels=K): a changed size needs its own pretrained network
        return VLAAIwsPatched(nb_blocks=int(D.get("model_blocks", 4)),
                              extractor_args=ExtractorParams(kernel_sizes=[3, 7, 11, 15], num_kernels=[int(D.get("model_kernels", 64))],
                                                             num_layers=3),
                              output_context_kernel_size=17, dropout=D.get("model_dropout", 0.0), **common)
    cfgname = {"vlaai": "vlaai", "simple_cnn": "simple_cnn", "lsm_cnn": "lsm_cnn", "deformer": "deformer",
               "deformer_ws": "rebok_deformer", "ssmamba": "ssmamba"}[name]
    c = yaml.safe_load(open(MODEL_CFG + cfgname + ".yaml"))["init_args"]
    mod, cls = c["model_class"].rsplit(".", 1)
    args = dict(c["model_args"])
    if isinstance(args.get("extractor_args"), dict) and "class_path" in args["extractor_args"]:
        args["extractor_args"] = ExtractorParams(**args["extractor_args"]["init_args"])
    args.update(MODEL_OVERRIDES.get(name, {}))
    if name == "ssmamba":
        args["use_subject_embedding"] = False          # subject IDs may not be inputs
    if name == "deformer_ws":
        args.update(window_length=int(W / FS), fs=FS, time_dim=W, num_electrodes=C)
    return getattr(importlib.import_module(mod), cls)(**{**args, **{k: v for k, v in common.items() if k not in args}})


class Net(torch.nn.Module):
    def __init__(self, name, C, W):
        super().__init__()
        self.name = name
        self.backbone = build_backbone(name, C, W).to(DEV)
        with torch.no_grad():
            o = self._bb(torch.zeros(1, W, C, device=DEV))
        self.F = len(D.get("targets", ["env"]))
        self.head = (EinMix("b t c -> b t f", weight_shape="c f", c=o.shape[-1], f=self.F)
                     if (o.shape[-1] != 1 or self.F > 1) else torch.nn.Identity())

    def _bb(self, x):
        if self.name == "ssmamba":
            y = self.backbone(x, {"subject_id": torch.ones(x.shape[0], dtype=torch.long, device=x.device)})
        else:
            y = self.backbone(x)
        return y[0] if isinstance(y, (tuple, list)) else y

    def forward(self, x):
        y = self.head(self._bb(x))
        return y[..., 0] if self.F == 1 else y                     # (B, W) or (B, W, F)


def infonce(y, Ya, Yi, tau):
    """InfoNCE over the batch: for window i the positive is its attended target, negatives are its ignored target
    and the attended targets of all other windows in the batch. Similarity = Pearson over time, logits = sim / tau.
    y, Ya, Yi: (B, W) or (B, W, F); the loss is averaged over targets F."""
    if y.dim() == 2:
        y, Ya, Yi = y[..., None], Ya[..., None], Yi[..., None]
    z = lambda a: (a - a.mean(1, keepdim=True)) / (a.std(1, keepdim=True) * np.sqrt(a.shape[1]) + 1e-8)
    zy, za, zi = z(y), z(Ya), z(Yi)
    sim = torch.einsum("btf,ctf->fbc", zy, za)                           # (F, B, B) corr(y_b, att_c)
    neg = torch.einsum("btf,btf->fb", zy, zi)[..., None]                 # (F, B, 1) corr(y_b, ign_b)
    logits = torch.cat([sim, neg], -1) / tau
    target = torch.arange(y.shape[0], device=y.device).expand(y.shape[-1], -1)
    return torch.nn.functional.cross_entropy(logits.reshape(-1, logits.shape[-1]), target.reshape(-1))


def pearson(a, b):
    a = a - a.mean(1, keepdim=True)
    b = b - b.mean(1, keepdim=True)
    return (a * b).sum(1) / torch.sqrt((a * a).sum(1) * (b * b).sum(1) + 1e-8)


def _grid_pos(names):
    """Approximate 2-D scalp grid (row, column) from 10-10 labels: letters -> anterior-posterior row, number -> lateral
    column (odd = left, even = right, z = midline). Enough to find neighbouring electrodes (no mne installed)."""
    import re
    rows = {"FP": 0, "AF": 1, "F": 2, "FC": 3, "FT": 3, "C": 4, "T": 4, "CP": 5, "TP": 5, "P": 6, "PO": 7, "O": 8,
            "CB": 9, "I": 9}
    out = []
    for n in names:
        m = re.match(r"([A-Z]+)(\d+|Z)$", n.upper())
        let, num = m.group(1), m.group(2)
        col = 0.0 if num == "Z" else (-(int(num) + 1) / 2 if int(num) % 2 else int(num) / 2)
        out.append((rows.get(let, rows.get(let[:1], 4)), col))
    return np.array(out, float)


def apply_overrides(pairs, aug_pairs=()):
    """Hyper-parameter search: --set key=value overrides config dnn (lr, weight_decay, batch_size, model_dropout, ...),
    --aug-set key=value overrides the augmentation dict (noise, p_chan, p_cluster, ...). Call after D['augment'] is set."""
    num = lambda v: int(v) if v.lstrip("-").isdigit() else float(v)
    for kv in pairs or ():
        k, v = kv.split("=")
        D[k] = num(v)
    if aug_pairs:
        D["augment"] = dict(D.get("augment") or {})
        for kv in aug_pairs:
            k, v = kv.split("=")
            D["augment"][k] = num(v)


def _dataset_of(key):
    return key.split("-subject-")[0]


# ---- adversarial domain loss (D['adv'] = 'dataset' | 'subject'): a domain classifier on the time-pooled backbone features
# behind a gradient-reversal layer (DANN); the backbone is pushed to make dataset / subject unpredictable
class _GRL(torch.autograd.Function):
    @staticmethod
    def forward(ctx, x, lam):
        ctx.lam = lam
        return x.view_as(x)

    @staticmethod
    def backward(ctx, g):
        return -ctx.lam * g, None


def domain_ids(trials, kind):
    """Domain label per training trial: 'dataset' (corpus dataset or the external set) or 'subject'."""
    def name(k):
        if "-subject-" in k:
            return k.split("-subject-")[0] if kind == "dataset" else k.split("-trial-")[0]
        return k.split("_")[0] if kind == "dataset" else k.rsplit("_", 1)[0]
    names = [name(t["key"]) for t in trials]
    uniq = sorted(set(names))
    return np.array([uniq.index(n) for n in names]), len(uniq)


class AdvHead(torch.nn.Module):
    def __init__(self, d, n):
        super().__init__()
        self.net = torch.nn.Sequential(torch.nn.Linear(2 * d, 128), torch.nn.ReLU(), torch.nn.Linear(128, n))

    def forward(self, f, lam):                                   # f: backbone features (B, W, d)
        return self.net(_GRL.apply(torch.cat([f.mean(1), f.std(1)], -1), lam))


def adv_lambda(step):
    """DANN schedule: 0 -> D['adv_lambda'] over the first D['adv_ramp_epochs'] epochs."""
    p = min(1.0, step / (D.get("adv_ramp_epochs", 5) * D["steps_per_epoch"]))
    return D.get("adv_lambda", 0.05) * (2.0 / (1.0 + math.exp(-10.0 * p)) - 1.0)



class DNNDec:
    def __init__(self, name, C, log=print, mode="causal"):
        self.name, self.C, self.log = name, C, log
        self.W = int(D["window_s"] * FS)
        self.hop = int(D["infer_hop_s"] * FS)
        self.fut = int(D["causal_future_s"] * FS)
        # label stamping of the evidence windows (score.py): a window ending on the read-out grid at t_end only needs
        # EEG < t_end + fut (its last hop block [t_end - hop, t_end) is read from the window ending at t_end + fut),
        # although a single output sample uses up to fut + hop = 0.75 s of future (leakage_test.py)
        self.lookahead_s = D.get("evidence_lookahead_s", (self.fut + self.hop) / FS)
        assert self.lookahead_s >= self.fut / FS and int(CFG["evidence"]["hop_s"] * FS) % self.hop == 0 \
            and int(CFG["evidence"]["win_s"] * FS) % self.hop == 0, "evidence windows must end on the read-out grid"
        self.offline_lookahead_s = (self.W - self.W // 4) / FS  # 3.75 s (reference only, violates the rule)
        torch.manual_seed(D.get("train_seed", CFG["seed"]))   # --train-seed (step 0)
        self.net = Net(name, C, self.W).to(DEV)

    def _augment(self, X, rng):
        """Training-only augmentation (D['augment'], off by default), per window, in place on X (n, W, C):
        spectral tilt (p_tilt of the windows, exponent within +-tilt), channel mask (p_chan_mask of the windows, each channel dropped with p_chan), per-channel gain (log-uniform
        within +-gain), additive Gaussian noise (std noise, data are z-scored), zero prefix (p_zero_prefix of the
        windows get their first 1..pos0 samples zeroed, as the zero padding at a trial start at inference)."""
        A = D.get("augment") or {}
        n, W, C = X.shape
        C0 = 58 if C % 58 == 0 else C                       # electrodes; C = C0 x feature groups (e.g. + gamma)
        if A.get("p_tilt", 0) > 0:
            # spectral tilt: amplitude spectrum x (f / f0)^alpha, alpha ~ U(-tilt, tilt) per window (all channels alike:
            # a subject / device difference in the spectral slope), f0 = 3 Hz (centre of the 1-9 Hz band), RMS kept
            sel = np.flatnonzero(rng.random(n) < A["p_tilt"])
            if len(sel):
                f = np.fft.rfftfreq(W, 1.0 / FS)
                al = rng.uniform(-A.get("tilt", 0.5), A.get("tilt", 0.5), (len(sel), 1, 1))
                g = (np.clip(f, 0.5, 12.0) / 3.0)[None, :, None] ** al
                Y = np.fft.irfft(np.fft.rfft(X[sel], axis=1) * g, n=W, axis=1)
                r = X[sel].std(1, keepdims=True) / np.maximum(Y.std(1, keepdims=True), 1e-8)
                X[sel] = (Y * np.where(X[sel].std(1, keepdims=True) > 0, r, 0.0)).astype(np.float32)
        if A.get("p_chan_mask", 0) > 0:
            sel = rng.random(n) < A["p_chan_mask"]
            m = (rng.random((sel.sum(), 1, C0)) > A.get("p_chan", 0.2)).astype(np.float32)
            X[sel] *= np.tile(m, (1, 1, C // C0))
        if A.get("gain", 0) > 0:
            g = np.exp(rng.uniform(-np.log1p(A["gain"]), np.log1p(A["gain"]), (n, 1, C))).astype(np.float32)
            X *= g
        if A.get("noise", 0) > 0:
            X += (A["noise"] * rng.standard_normal(X.shape)).astype(np.float32)
        if (A.get("p_cluster", 0) > 0 or A.get("p_spatial_mix", 0) > 0 or A.get("p_reref", 0) > 0) \
                and not hasattr(self, "_nbr"):
            from common import MONTAGES
            P = _grid_pos(MONTAGES[CFG["montage"]])
            self._nbr = np.argsort(((P[:, None] - P[None]) ** 2).sum(-1), 1)       # channels by distance
        if A.get("p_spatial_mix", 0) > 0 and C == self._nbr.shape[0]:
            # covariance augmentation 1: X <- X (I + eps N), N mixes each electrode with its k nearest neighbours
            k, sig = int(A.get("mix_k", 6)), float(A.get("mix_sigma", 0.15))
            for j in np.flatnonzero(rng.random(n) < A["p_spatial_mix"]):
                Mx = np.eye(C, dtype=np.float32)
                cols = self._nbr[:, 1:k + 1]                                       # (C, k) neighbours of each channel
                Mx[cols, np.repeat(np.arange(C)[:, None], k, 1)] += (sig * rng.uniform(-1, 1, (C, k))).astype(np.float32)
                X[j] = X[j] @ Mx
        if A.get("p_reref", 0) > 0 and C == self._nbr.shape[0]:
            # covariance augmentation 2: random partial re-reference to the mean of a random electrode cluster
            for j in np.flatnonzero(rng.random(n) < A["p_reref"]):
                grp = self._nbr[rng.integers(C), : int(rng.integers(1, A.get("reref_max", 8) + 1))]
                X[j] -= float(rng.uniform(0.5, 1.0)) * X[j][:, grp].mean(1, keepdims=True)
        if A.get("p_cluster", 0) > 0:                     # drop a cluster of neighbouring electrodes
            for j in np.flatnonzero(rng.random(n) < A["p_cluster"]):
                k = rng.integers(A.get("cluster_min", 3), A.get("cluster_max", 8) + 1)
                el = self._nbr[rng.integers(C0), :k]
                X[j][:, np.concatenate([el + g * C0 for g in range(C // C0)])] = 0.0
        if A.get("p_renorm", 0) > 0:                      # re-z-score with statistics of a random sub-segment
            for j in np.flatnonzero(rng.random(n) < A["p_renorm"]):
                L_ = rng.integers(FS, W + 1); a = rng.integers(0, W - L_ + 1)
                seg = X[j, a:a + L_]
                sd = seg.std(0); sd[sd == 0] = 1.0
                X[j] = (X[j] - seg.mean(0)) / sd
        if A.get("p_zero_prefix", 0) > 0:
            pos0 = self.W - self.fut - self.hop
            for j in np.flatnonzero(rng.random(n) < A["p_zero_prefix"]):
                X[j, :rng.integers(1, pos0 + 1)] = 0.0
        return X

    def _windows(self, trials, n, rng, aug=False):
        A = (D.get("augment") or {}) if aug else {}
        warp, lag = A.get("warp", 0.0), int(A.get("lag_jitter", 0))
        span = int(np.ceil(self.W * (1 + warp))) + 2 * lag      # longest raw segment a window may need
        lens = np.array([len(t["eeg"]) - span for t in trials])
        p = np.maximum(lens, 0).astype(float)
        if A.get("balance") == "dataset":                        # every training dataset equally often
            ds = np.array([_dataset_of(t["key"]) for t in trials])
            for d in np.unique(ds):
                p[ds == d] /= max(p[ds == d].sum(), 1e-9)
        p = p / p.sum()
        gf = D.get("group_frac") or {}
        if gf:                                                   # fixed sampling share per extra dataset (S2)
            grp = np.array([t.get("_grp", "") for t in trials])
            rest = ~np.isin(grp, list(gf))
            p[rest] *= (1 - sum(v for g, v in gf.items() if (grp == g).any())) / max(p[rest].sum(), 1e-12)
            for g, v in gf.items():
                if (grp == g).any():
                    p[grp == g] *= v / max(p[grp == g].sum(), 1e-12)
            p = p / p.sum()
        ti = rng.choice(len(trials), n, p=p)
        self._last_ti = ti                                        # trial of every window (adversarial domain loss)
        X = np.empty((n, self.W, self.C), np.float32)
        fshape = trials[0]["_ya"].shape[1:]                       # () for one target, (F,) for several
        Ya = np.empty((n, self.W) + fshape, np.float32)
        Yi = np.empty((n, self.W) + fshape, np.float32)
        for j, i in enumerate(ti):
            s = rng.integers(0, lens[i] + 1) + lag
            tr = trials[i]
            ya, yi = tr["_ya"], tr["_yi"]
            if warp > 0:                                        # same time warp for EEG and both envelopes
                Lr = int(round(self.W * (1 + rng.uniform(-warp, warp))))
                tq = np.linspace(0, Lr - 1, self.W)
                t0_, fr = np.floor(tq).astype(int), (tq - np.floor(tq))[:, None]
                t1_ = np.minimum(t0_ + 1, Lr - 1)
                d_ = rng.integers(-lag, lag + 1) if lag else 0   # EEG shifted vs envelope by d_ samples
                e = tr["eeg"][s + d_:s + d_ + Lr]
                X[j] = e[t0_] * (1 - fr) + e[t1_] * fr
                Ya[j] = ya[s:s + Lr][t0_] * (1 - fr[:, 0]) + ya[s:s + Lr][t1_] * fr[:, 0]
                Yi[j] = yi[s:s + Lr][t0_] * (1 - fr[:, 0]) + yi[s:s + Lr][t1_] * fr[:, 0]
            else:
                d_ = rng.integers(-lag, lag + 1) if lag else 0
                X[j] = tr["eeg"][s + d_:s + d_ + self.W]
                Ya[j], Yi[j] = ya[s:s + self.W], yi[s:s + self.W]
        if aug:
            X = self._augment(X, rng)
        return torch.from_numpy(X), torch.from_numpy(Ya), torch.from_numpy(Yi)

    def fit(self, train, val, meta):
        for tr in train + val:
            tr["_ya"], tr["_yi"] = _att_tgt(tr)
        rng = np.random.default_rng(D.get("train_seed", CFG["seed"]))
        Xv, Yav, Yiv = self._windows(val, D["val_windows"], rng)
        adv, step = None, 0
        params = list(self.net.parameters())
        if D.get("adv"):
            dom, n_dom = domain_ids(train, D["adv"])
            with torch.no_grad():
                d_feat = self.net._bb(torch.zeros(1, self.W, self.C, device=DEV)).shape[-1]
            adv = AdvHead(d_feat, n_dom).to(DEV)
            params += list(adv.parameters())
            self.log(f"  adversarial {D['adv']} loss: {n_dom} classes, lambda {D.get('adv_lambda', 0.05)}")
        opt = torch.optim.AdamW(params, lr=D["lr"], weight_decay=D["weight_decay"])
        sch = torch.optim.lr_scheduler.ReduceLROnPlateau(opt, mode="min", factor=0.5, patience=D["lr_patience"])
        best, bad, best_state = math.inf, 0, None
        warm = int(D.get("warmup_epochs", 0))    # epochs with linear LR ramp (lr/10 -> lr), no early stop / LR decay
        for ep in range(D["max_epochs"]):
            t0 = time.time()
            if ep < warm:
                for g in opt.param_groups:
                    g["lr"] = D["lr"] * (0.1 + 0.9 * ep / warm)
            elif ep == warm and warm > 0:
                for g in opt.param_groups:
                    g["lr"] = D["lr"]
            self.net.train()
            tl, da = [], []
            for _ in range(D["steps_per_epoch"]):
                X, Ya, Yi = self._windows(train, D["batch_size"], rng, aug=True)
                X, Ya, Yi = X.to(DEV), Ya.to(DEV), Yi.to(DEV)
                if adv is None:
                    y = self.net(X)
                else:
                    f = self.net._bb(X)
                    y = self.net.head(f)
                    y = y[..., 0] if self.net.F == 1 else y
                if D.get("loss", "contrastive") == "infonce":
                    loss = infonce(y, Ya, Yi, D.get("infonce_tau", 0.1))
                elif D.get("loss") == "pearson":                   # pretraining on single-speaker data (S1)
                    loss = -pearson(y, Ya).mean()
                else:
                    loss = (-pearson(y, Ya) + pearson(y, Yi)).mean()
                tl.append(loss.item())
                if adv is not None:                               # the reversed gradient reaches the backbone scaled by lambda
                    dl = adv(f, adv_lambda(step))
                    dt = torch.from_numpy(dom[self._last_ti]).to(DEV)
                    loss = loss + torch.nn.functional.cross_entropy(dl, dt)
                    da.append((dl.argmax(1) == dt).float().mean().item())
                    step += 1
                opt.zero_grad()
                loss.backward()
                torch.nn.utils.clip_grad_norm_(params, 5.0)
                opt.step()
            self.net.eval()
            with torch.no_grad():
                vl = []
                for i in range(0, len(Xv), 256):
                    y = self.net(Xv[i:i + 256].to(DEV))
                    vl.append((-pearson(y, Yav[i:i + 256].to(DEV)) + pearson(y, Yiv[i:i + 256].to(DEV))).cpu())
                vl = torch.cat(vl).mean().item()
            if ep >= warm:
                sch.step(vl)
            self.log(f"    epoch {ep:02d} train {np.mean(tl):+.4f} val {vl:+.4f} ({time.time() - t0:.0f}s)"
                     + (f" [warm-up, lr {opt.param_groups[0]['lr']:.1e}]" if ep < warm else "")
                     + (f" | adversary acc {np.mean(da):.3f}" if da else ""))
            if vl < best - 1e-4:
                best, bad = vl, 0
                best_state = {k: v.detach().clone() for k, v in self.net.state_dict().items()}
            elif ep >= warm:
                bad += 1
                if bad >= D["patience"]:
                    break
        if best_state is not None:
            self.net.load_state_dict(best_state)
        self.net.eval()
        for tr in train + val:
            tr.pop("_ya", None)
            tr.pop("_yi", None)
        return best

    # ---------------------------------------------------------------------------------------------------------------
    # A1: end-to-end sequence training (2-state linear-chain CRF / HMM filter) on sequences with synthetic switches
    # ---------------------------------------------------------------------------------------------------------------
    def _sequences(self, trials, n, rng, aug=False):
        """n training sequences of D['seq_len_s'] s with their causal context: EEG (n, ctx + Ls + fut, C), targets of
        both streams (n, Ls, 2, F), attended column (n, Ls) and the synthetic-switch flag (n, Ls): with probability
        D['seq_p_switch'] the two streams swap roles at a uniform time (as generateSyntheticSwitches does at test)."""
        Ls, ctx = int(D["seq_len_s"] * FS), self.W - self.fut - self.hop
        need = ctx + Ls + self.fut
        lens = np.array([len(t["eeg"]) - need for t in trials])
        p = np.maximum(lens + 1, 0).astype(float)
        ti = rng.choice(len(trials), n, p=p / p.sum())
        X = np.empty((n, need, self.C), np.float32)
        Y = np.empty((n, Ls) + trials[0]["_Y"].shape[1:], np.float32)
        att, st = np.empty((n, Ls), np.int64), np.zeros((n, Ls), bool)
        for j, i in enumerate(ti):
            a = rng.integers(0, lens[i] + 1)
            tr = trials[i]
            X[j], Y[j], att[j] = tr["eeg"][a:a + need], tr["_Y"][a + ctx:a + ctx + Ls], tr["att"][a + ctx:a + ctx + Ls]
            if rng.random() < D["seq_p_switch"]:
                st[j, rng.integers(int(0.2 * Ls), int(0.8 * Ls)):] = True
        if aug:
            X = self._augment(X, rng)
        return torch.from_numpy(X), torch.from_numpy(Y), torch.from_numpy(att), torch.from_numpy(st)

    def _seq_loss(self, X, Y, att, st, v, kind):
        """Decoder on every 0.25-s hop of the sequences (the causal read-out of reconstruct()), per-target Pearson in
        1-s windows against both streams, evidence sign flipped in the synthetically switched windows, unary log-odds
        u = sum_f v_f (r0_f - r1_f), 2-state chain with p_stay. kind 'filter': cross-entropy of the causal FILTERING
        posterior (what is used at test); 'crf': negative log-likelihood of the whole state path (CRF).
        Returns (loss, filtering cross-entropy, filtering accuracy)."""
        B, Ls = Y.shape[0], Y.shape[1]
        pos0, EW = self.W - self.fut - self.hop, int(CFG["evidence"]["win_s"] * FS)
        win = X.unfold(1, self.W, self.hop).permute(0, 1, 3, 2).reshape(-1, self.W, self.C)     # (B * Ls/hop, W, C)
        y = self.net(win)[:, pos0:pos0 + self.hop]
        y = y.reshape(B, Ls, -1)                                                               # (B, Ls, F)
        uw = lambda a: a.unfold(1, EW, self.hop)                                               # (B, n, F, EW)

        def corr(a, b):
            a, b = a - a.mean(-1, keepdim=True), b - b.mean(-1, keepdim=True)
            return (a * b).sum(-1) / torch.sqrt((a * a).sum(-1) * (b * b).sum(-1) + 1e-8)
        yw = uw(y)
        d = corr(yw, uw(Y[:, :, 0])) - corr(yw, uw(Y[:, :, 1]))                                # (B, n, F)
        frac = lambda z: z.float().unfold(1, EW, self.hop).mean(-1) > 0.5
        wsw, a_w = frac(st), frac(att)
        u = (d * torch.where(wsw, -1.0, 1.0)[..., None] * v).sum(-1)                           # log-odds of column 0
        state = (a_w ^ wsw).long()                                                             # true attended column
        ls, lsw = math.log(D["seq_p_stay"]), math.log(1 - D["seq_p_stay"])
        un = torch.stack([u / 2, -u / 2], -1)                                                  # (B, n, 2)
        lp = torch.full((B, 2), math.log(0.5), device=u.device)
        logZ, post = 0.0, []
        for j in range(un.shape[1]):
            if j > 0:
                lp = torch.stack([torch.logaddexp(lp[:, 0] + ls, lp[:, 1] + lsw),
                                  torch.logaddexp(lp[:, 1] + ls, lp[:, 0] + lsw)], 1)
            lp = lp + un[:, j]
            c = torch.logsumexp(lp, 1, keepdim=True)
            logZ, lp = logZ + c[:, 0], lp - c
            post.append(lp)
        post = torch.stack(post, 1)                                                            # filtering log-posteriors
        ce = -post.gather(2, state[..., None])[..., 0].mean()
        acc = (post.argmax(-1) == state).float().mean()
        if kind == "crf":
            gold = un.gather(2, state[..., None])[..., 0].sum(1) + math.log(0.5) + \
                torch.where(state[:, 1:] == state[:, :-1], ls, lsw).sum(1)
            return ((logZ - gold) / un.shape[1]).mean(), ce, acc
        return ce, ce, acc

    def fit_sequence(self, train, val):
        """Phase 2 after fit(): fine-tune the decoder and the CRF unary weights v END-TO-END with a sequence loss on
        synthetic-switch sequences. Early stopping on the filtering cross-entropy of fixed validation sequences.
        Returns dict(v, p_stay) for score.py (--evidence-weights crf)."""
        kind = D["seq_loss"]
        need = int(D["seq_len_s"] * FS) + self.W - self.hop
        for tr in train + val:
            tr["_Y"] = _targets(tr)
        tr_ok, va_ok = [t for t in train if len(t["eeg"]) >= need], [t for t in val if len(t["eeg"]) >= need]
        rng = np.random.default_rng(D.get("train_seed", CFG["seed"]) + 7)
        # unary weights: free (scale and mix learned), or 'seq_v_norm': v = seq_v_init x softmax(theta), i.e. only the
        # MIX of the targets is learned and the total LLR scale stays that of the scoring HMM (the cross-entropy
        # otherwise shrinks the scale to calibrate the overlapping windows, which slows the filter down)
        th = torch.nn.Parameter(torch.zeros(self.net.F, device=DEV) if D.get("seq_v_norm")
                                else torch.full((self.net.F,), D["seq_v_init"] / self.net.F, device=DEV))
        vf = (lambda: D["seq_v_init"] * torch.softmax(th, 0)) if D.get("seq_v_norm") else (lambda: th)
        opt = torch.optim.AdamW([dict(params=self.net.parameters(), lr=D["seq_lr"]),
                                 dict(params=[th], lr=D["seq_v_lr"], weight_decay=0.0)], weight_decay=D["weight_decay"])
        Vb = [self._sequences(va_ok, D["seq_batch"], rng) for _ in range(D["seq_val_batches"])]

        def validate():
            self.net.eval()
            with torch.no_grad():
                r = [self._seq_loss(*[z.to(DEV) for z in b], vf(), kind) for b in Vb]
            return float(np.mean([x[1].item() for x in r])), float(np.mean([x[2].item() for x in r]))
        best, acc0 = validate()
        self.log(f"    seq[{kind}] start: val filter-CE {best:.4f} acc {acc0:.3f}  v {np.round(vf().detach().cpu().numpy(), 3)}")
        bad, best_state, best_v = 0, {k: x.detach().clone() for k, x in self.net.state_dict().items()}, vf().detach().clone()
        for ep in range(D["seq_epochs"]):
            t0, tl = time.time(), []
            self.net.train()
            for _ in range(D["seq_steps"]):
                b = [z.to(DEV) for z in self._sequences(tr_ok, D["seq_batch"], rng, aug=True)]
                loss = self._seq_loss(*b, vf(), kind)[0]
                opt.zero_grad()
                loss.backward()
                torch.nn.utils.clip_grad_norm_(self.net.parameters(), 5.0)
                opt.step()
                tl.append(loss.item())
            vl, va = validate()
            self.log(f"    seq[{kind}] epoch {ep:02d} train {np.mean(tl):.4f} val filter-CE {vl:.4f} acc {va:.3f} "
                     f"v {np.round(vf().detach().cpu().numpy(), 3)} ({time.time() - t0:.0f}s)")
            if vl < best - 1e-4:
                best, bad = vl, 0
                best_state, best_v = {k: x.detach().clone() for k, x in self.net.state_dict().items()}, vf().detach().clone()
            else:
                bad += 1
                if bad >= D["seq_patience"]:
                    break
        self.net.load_state_dict(best_state)
        self.net.eval()
        for tr in train + val:
            tr.pop("_Y", None)
        return dict(v=[float(x) for x in best_v.cpu().numpy()], p_stay=D["seq_p_stay"], val_ce=best)

    @torch.no_grad()
    def reconstruct(self, tr, mode="causal"):
        """causal : output sample u is read from the window ending at u + fut + (u mod hop) -> <= 0.75 s future.
        offline: centre quarter-to-three-quarters of windows at hop W/2 (reference; uses up to 3.75 s future)."""
        x = tr["eeg"].astype(np.float32)
        T = len(x)
        if mode == "causal":
            pos0 = self.W - self.fut - self.hop                    # first read position inside the window
            pad_l, pad_r = pos0, self.fut + self.hop
            step, take = self.hop, slice(pos0, pos0 + self.hop)
        else:
            q = self.W // 4
            pad_l, pad_r, step, take = q, self.W, self.W // 2, slice(q, q + self.W // 2)
        xp = np.concatenate([np.zeros((pad_l, self.C), np.float32), x, np.zeros((pad_r, self.C), np.float32)])
        starts = np.arange(0, T, step)
        F = self.net.F
        out = np.zeros((len(starts) * step,) + ((F,) if F > 1 else ()), np.float32)
        for i in range(0, len(starts), 512):
            s = starts[i:i + 512]
            X = torch.from_numpy(np.stack([xp[a:a + self.W] for a in s])).to(DEV)
            y = self.net(X)[:, take].cpu().numpy()
            out[i * step:(i + len(s)) * step] = y.reshape((-1,) + ((F,) if F > 1 else ()))
        return out[:T]

    def features(self, tr, mode="causal"):
        y = self.reconstruct(tr, mode)
        if self.net.F == 1:
            return y, tr["env"][:, 0], tr["env"][:, 1]
        Y = _targets(tr)                                            # evidence = mean correlation over targets
        return y, Y[:, 0, :], Y[:, 1, :]


LINEAR = {"wf": BackwardWF, "wf_persubject": PerSubjectWF, "wf_riemann": RiemannWF, "wf_forward": ForwardWF,
          "cca": CCADec, "fbcca": FBCCADec}
DNN = ["simple_cnn", "lsm_cnn", "vlaai", "vlaai_ws", "deformer", "deformer_ws", "ssmamba", "adt", "happyquokka"]


def make(name, C, log=print):
    if name in LINEAR:
        return LINEAR[name](C)
    return DNNDec(name, C, log)
