# -*- coding: utf-8 -*-
"""Representation encoders for Suite19.

The module deliberately distinguishes *official* implementations from internal
research diagnostics.  Official backends never silently fall back.  This is
important for the Suite19 scientific audit: the report must say exactly which
representation principle produced a result.
"""
from __future__ import annotations

from dataclasses import dataclass
import importlib
import importlib.metadata as importlib_metadata
import inspect
import math
import time
from typing import Any

import numpy as np
from sklearn.decomposition import PCA
from sklearn.random_projection import GaussianRandomProjection

from suite19_common import resolve_device, safe_ap, safe_auc, seed_everything

try:
    import torch
    from torch import nn
    import torch.nn.functional as F
except Exception:  # pragma: no cover - local installation issue reported at runtime
    torch = None
    nn = None
    F = None

EPS = 1e-8


class BaseRepresentationEncoder:
    name = "base"
    implementation = "base"

    def fit(self, X, y, committee=None, mechanism=None, faculty=None):
        raise NotImplementedError

    def transform(self, X):
        raise NotImplementedError

    def metadata(self) -> dict[str, Any]:
        return dict(getattr(self, "metadata_", {}))


def _package_version(pkg: str) -> str:
    try:
        return importlib_metadata.version(pkg)
    except Exception:
        return "not-installed"


def _effective_number(n: int, beta: float) -> float:
    if n <= 0:
        return 1.0
    if beta <= 0 or beta >= 1:
        return float(n)
    return float((1.0 - beta ** n) / max(1.0 - beta, EPS))


def faculty_class_effective_weights(y, faculty=None, beta=.9999) -> np.ndarray:
    """Equalize faculty mass, then use effective-number class balance within faculty."""
    y = np.asarray(y, int).reshape(-1)
    if faculty is None:
        faculty = np.zeros(len(y), int)
    faculty = np.asarray(faculty, int).reshape(-1)
    if len(y) != len(faculty):
        raise ValueError("faculty/y alignment mismatch")
    out = np.zeros(len(y), float)
    unique_fac = np.unique(faculty)
    for fi in unique_fac:
        m = faculty == fi
        yy = y[m]
        raw = np.ones(len(yy), float)
        for c in (0, 1):
            n = int(np.sum(yy == c))
            raw[yy == c] = 1.0 / max(_effective_number(n, float(beta)), EPS)
        # Every represented faculty gets the same aggregate sampling mass.
        raw /= max(raw.sum(), EPS)
        out[m] = raw
    if out.sum() <= 0:
        out[:] = 1.0
    out *= len(out) / max(out.sum(), EPS)
    return out.astype(np.float32)


def committee_hard_sampling_weights(y, committee, strength=2.0) -> np.ndarray:
    """Increase batch probability for examples the immutable Committee finds hard.

    Normal/high-q and failure/low-q rows are hard.  No labels from a future/query
    block may be supplied by the caller; Suite19's prequential ledger enforces
    that temporal boundary.
    """
    y = np.asarray(y, int).reshape(-1)
    q = np.clip(np.asarray(committee, float).reshape(-1), 0.0, 1.0)
    if len(y) != len(q):
        raise ValueError("committee/y alignment mismatch")
    difficulty = np.where(y == 1, 1.0 - q, q)
    return (1.0 + float(strength) * difficulty).astype(np.float32)


def _subsample_indices(n: int, max_rows: int, weights, seed: int) -> np.ndarray:
    if not max_rows or n <= int(max_rows):
        return np.arange(n, dtype=int)
    rng = np.random.default_rng(int(seed))
    p = np.asarray(weights, float)
    p = np.clip(p, 0, None)
    p = p / max(p.sum(), EPS)
    return np.sort(rng.choice(np.arange(n), size=int(max_rows), replace=False, p=p))


# ---------------------------------------------------------------------------
# TabM
# ---------------------------------------------------------------------------


class _InternalTabM(nn.Module):
    """Diagnostic-only compact parameter-efficient ensemble surrogate.

    It is *not* reported as TabM.  The backend name is always
    ``internal_batchensemble_diagnostic``.  It exists so chronology/probe/CLI
    tests can execute in an environment where the official tabm package is not
    installed.
    """
    def __init__(self, d_in: int, d_latent: int, depth: int, k: int, dropout: float):
        super().__init__()
        layers: list[nn.Module] = []
        d = d_in
        for _ in range(max(1, int(depth))):
            layers.extend([nn.Linear(d, d_latent), nn.ReLU()])
            if dropout > 0:
                layers.append(nn.Dropout(float(dropout)))
            d = d_latent
        self.backbone = nn.Sequential(*layers)
        self.k = int(k)
        # Cheap member-specific affine adapters around a shared latent state.
        self.r = nn.Parameter(torch.ones(self.k, d_latent))
        self.s = nn.Parameter(torch.ones(self.k, d_latent))
        self.head = nn.Parameter(torch.empty(self.k, d_latent))
        self.bias = nn.Parameter(torch.zeros(self.k))
        nn.init.normal_(self.r, 1.0, .05)
        nn.init.normal_(self.s, 1.0, .05)
        nn.init.xavier_uniform_(self.head)

    def latent_members(self, x):
        h = self.backbone(x)
        return h[:, None, :] * self.r[None, :, :] * self.s[None, :, :]

    def forward(self, x):
        z = self.latent_members(x)
        return (z * self.head[None, :, :]).sum(-1) + self.bias[None, :]


class TabMRepresentationEncoder(BaseRepresentationEncoder):
    name = "tabm"

    def __init__(
        self,
        latent_dim=32,
        depth=2,
        ensemble_size=8,
        dropout=0.0,
        epochs=40,
        batch_size=512,
        lr=2e-3,
        weight_decay=1e-5,
        class_beta=.9999,
        seed=42,
        device="auto",
        max_train_rows=180000,
        backend="official",
        arch_type="tabm",
    ):
        self.latent_dim = int(latent_dim)
        self.depth = int(depth)
        self.ensemble_size = int(ensemble_size)
        self.dropout = float(dropout)
        self.epochs = int(epochs)
        self.batch_size = int(batch_size)
        self.lr = float(lr)
        self.weight_decay = float(weight_decay)
        self.class_beta = float(class_beta)
        self.seed = int(seed)
        self.device_name = str(device)
        self.max_train_rows = int(max_train_rows or 0)
        self.backend = str(backend).lower()
        self.arch_type = str(arch_type)
        self.model_ = None
        self.metadata_: dict[str, Any] = {}
        self.training_curve_: list[dict] = []
        self._fit_X = None
        self._official_backbone_hook_value = None

    def _official_make(self, d_in: int):
        """
        Construct the pinned official TabM model.

        Suite19 intentionally targets tabm==0.0.3 so that the representation
        experiment is reproducible and does not silently adapt to an unknown API.
        """
        try:
            import tabm
            from tabm import TabM
        except Exception as e:
            raise ImportError(
                "Official TabM backend requested but package 'tabm' is unavailable. "
                "Install tabm==0.0.3. No silent fallback is permitted."
            ) from e

        version = _package_version("tabm")

        if version != "0.0.3":
            raise RuntimeError(
                f"Suite19 official TabM wrapper is validated for tabm==0.0.3, "
                f"but found tabm=={version}."
            )

        if not hasattr(TabM, "make"):
            raise RuntimeError(
                "Installed official TabM does not expose TabM.make; "
                "unsupported API version."
            )

        kwargs = {
            "n_num_features": int(d_in),
            "cat_cardinalities": [],
            "d_out": 1,
            "arch_type": self.arch_type,
            "k": int(self.ensemble_size),
            "n_blocks": int(max(1, self.depth)),
            "d_block": int(self.latent_dim),
            "dropout": float(self.dropout),
        }

        try:
            model = TabM.make(**kwargs)
        except Exception as e:
            raise RuntimeError(
                "Official TabM.make failed.\n"
                f"tabm_version={version}\n"
                f"kwargs={kwargs}\n"
                f"original_error={type(e).__name__}: {e}"
            ) from e

        return model

    def _make_model(self, d_in: int):
        if torch is None:
            raise ImportError("PyTorch is required for TabM")
        if self.backend == "official":
            self.implementation = "official_yandex_tabm"
            return self._official_make(d_in)
        if self.backend == "internal":
            self.implementation = "internal_batchensemble_diagnostic"
            return _InternalTabM(d_in, self.latent_dim, self.depth, self.ensemble_size, self.dropout)
        raise ValueError("TabM backend must be 'official' or explicit 'internal'")

    def _forward_logits(self, xb):
        if self.backend == "internal":
            return self.model_(xb)
        try:
            out = self.model_(xb, None)
        except TypeError:
            try:
                out = self.model_(x_num=xb, x_cat=None)
            except TypeError:
                out = self.model_(xb)
        if out.ndim == 3 and out.shape[-1] == 1:
            out = out[..., 0]
        elif out.ndim == 2 and out.shape[-1] == 1:
            out = out[:, 0:1]
        if out.ndim != 2:
            raise RuntimeError(f"Unexpected official TabM output shape: {tuple(out.shape)}")
        return out

    def fit(self, X, y, committee=None, mechanism=None, faculty=None):
        if torch is None:
            raise ImportError("PyTorch required")
        seed_everything(self.seed)
        X = np.asarray(X, np.float32)
        y = np.asarray(y, int).reshape(-1)
        if np.unique(y).size < 2:
            raise ValueError("TabM requires both classes")
        w = faculty_class_effective_weights(y, faculty, self.class_beta)
        idx = _subsample_indices(len(y), self.max_train_rows, w, self.seed)
        Xs, ys, ws = X[idx], y[idx], w[idx]
        ws = ws / max(float(ws.mean()), EPS)
        self._fit_X = Xs
        dev = resolve_device(self.device_name)
        model = self._make_model(X.shape[1]).to(dev)
        self.model_ = model
        opt = torch.optim.AdamW(model.parameters(), lr=self.lr, weight_decay=self.weight_decay)
        rng = np.random.default_rng(self.seed)
        self.training_curve_ = []
        t0 = time.perf_counter()
        for epoch in range(1, max(1, self.epochs) + 1):
            model.train()
            order = rng.permutation(len(Xs))
            losses = []
            for start in range(0, len(order), max(2, self.batch_size)):
                ii = order[start:start + max(2, self.batch_size)]
                xb = torch.as_tensor(Xs[ii], dtype=torch.float32, device=dev)
                yb = torch.as_tensor(ys[ii], dtype=torch.float32, device=dev)
                wb = torch.as_tensor(ws[ii], dtype=torch.float32, device=dev)
                opt.zero_grad(set_to_none=True)
                logits = self._forward_logits(xb)
                target = yb[:, None].expand_as(logits)
                loss_mat = F.binary_cross_entropy_with_logits(logits, target, reduction="none")
                loss = (loss_mat * wb[:, None]).mean()
                if not torch.isfinite(loss):
                    raise FloatingPointError("TabM training diverged to non-finite loss")
                loss.backward()
                torch.nn.utils.clip_grad_norm_(model.parameters(), 10.0)
                opt.step()
                losses.append(float(loss.detach().cpu()))
            self.training_curve_.append({"epoch": epoch, "train_loss": float(np.mean(losses))})
        train_seconds = time.perf_counter() - t0
        self.metadata_ = {
            "encoder": self.name,
            "implementation": self.implementation,
            "backend": self.backend,
            "package_version": _package_version("tabm") if self.backend == "official" else "internal",
            "latent_dim": self.latent_dim,
            "depth": self.depth,
            "ensemble_size": self.ensemble_size,
            "epochs": self.epochs,
            "batch_size": self.batch_size,
            "train_rows_input": int(len(X)),
            "train_rows_used": int(len(Xs)),
            "train_failures_used": int(ys.sum()),
            "train_prevalence_used": float(ys.mean()),
            "train_seconds": float(train_seconds),
            "parameter_count": int(sum(p.numel() for p in model.parameters())),
            "training_curve": self.training_curve_,
            "methodological_note": (
                "Official Yandex TabM" if self.backend == "official" else
                "DIAGNOSTIC ONLY: internal parameter-efficient ensemble surrogate; not official TabM"
            ),
        }
        return self

    def _official_latent_members(self, xb):
        # The official implementation exposes ``backbone`` publicly. Capture its
        # output using a forward hook, avoiding source modification.
        if not hasattr(self.model_, "backbone"):
            raise RuntimeError("Official TabM model does not expose public backbone; cannot audit penultimate representation")
        box: dict[str, Any] = {}
        handle = self.model_.backbone.register_forward_hook(lambda _m, _i, o: box.__setitem__("z", o))
        try:
            _ = self._forward_logits(xb)
        finally:
            handle.remove()
        z = box.get("z")
        if z is None:
            raise RuntimeError("TabM backbone hook did not emit a latent representation")
        if z.ndim == 2:
            z = z[:, None, :]
        if z.ndim != 3:
            raise RuntimeError(f"Unexpected TabM backbone latent shape {tuple(z.shape)}")
        return z

    def _latent_members_tensor(self, xb):
        if self.backend == "internal":
            return self.model_.latent_members(xb)
        return self._official_latent_members(xb)

    @torch.no_grad() if torch is not None else (lambda f: f)
    def _batch_latent(self, X, batch=4096):
        dev = resolve_device(self.device_name)
        self.model_.eval()
        out = []
        for s in range(0, len(X), batch):
            xb = torch.as_tensor(np.asarray(X[s:s+batch], np.float32), device=dev)
            z = self._latent_members_tensor(xb)
            # A single exported representation is required by Suite19 probes.
            # Average across ensemble members while member disagreement is saved
            # separately from direct prediction.
            out.append(z.mean(1).detach().cpu().numpy())
        z = np.concatenate(out, 0).astype(np.float32)
        if z.shape[1] != self.latent_dim:
            # The installed official version may expose a different backbone
            # width. Keep the true width explicit rather than projecting it away.
            self.metadata_["latent_dim"] = int(z.shape[1])
        return z

    def transform(self, X):
        if self.model_ is None:
            raise RuntimeError("TabM encoder is not fitted")
        return self._batch_latent(np.asarray(X, np.float32))

    @torch.no_grad() if torch is not None else (lambda f: f)
    def predict_members(self, X, batch=4096):
        dev = resolve_device(self.device_name)
        self.model_.eval(); parts=[]
        X=np.asarray(X,np.float32)
        for s in range(0,len(X),batch):
            xb=torch.as_tensor(X[s:s+batch],device=dev)
            parts.append(torch.sigmoid(self._forward_logits(xb)).cpu().numpy())
        return np.concatenate(parts,0).astype(np.float32)

    def predict_proba(self, X):
        return self.predict_members(X).mean(1).astype(np.float32)

    def direct_predict(self, X):
        members=self.predict_members(X)
        self.metadata_["last_prediction_member_std_mean"]=float(np.mean(np.std(members,axis=1)))
        self.metadata_["last_prediction_member_std_p95"]=float(np.quantile(np.std(members,axis=1),.95))
        self.metadata_["last_prediction_member_range_mean"]=float(np.mean(np.max(members,axis=1)-np.min(members,axis=1)))
        return members.mean(1).astype(np.float32)


# ---------------------------------------------------------------------------
# ModernNCA-style metric representation
# ---------------------------------------------------------------------------


class _NCANet(nn.Module):
    def __init__(self, d_in: int, hidden: int, latent: int):
        super().__init__()
        self.encoder = nn.Sequential(
            nn.Linear(d_in, hidden), nn.ReLU(),
            nn.Linear(hidden, hidden), nn.ReLU(),
            nn.Linear(hidden, latent),
        )
        self.aux = nn.Linear(latent, 1)

    def encode(self, x):
        return F.normalize(self.encoder(x), p=2, dim=-1, eps=1e-8)

    def forward(self, x):
        z = self.encode(x)
        return z, self.aux(z).squeeze(-1)


class ModernNCAEncoder(BaseRepresentationEncoder):
    """ModernNCA-style supervised metric learner.

    The implementation follows the defining objective faithfully enough for the
    Suite19 representation audit: a differentiable normalized embedding, a
    leave-self-out soft-neighbor probability, and an NCA negative log likelihood.
    Optional BCE, Committee-hard sampling, and mechanism-aware positive-pair
    weighting are explicit ablations, not hidden changes to the base model.
    """
    name = "modern_nca"
    implementation = "suite19_modern_nca_metric_v4_streaming"

    def __init__(
        self,
        latent_dim=32,
        hidden_dim=128,
        epochs=40,
        batch_size=512,
        temperature=.10,
        lr=2e-3,
        weight_decay=1e-5,
        aux_bce=0.0,
        hard_sampling=False,
        hard_strength=2.0,
        mechanism_aware=False,
        mechanism_tau=1.0,
        class_beta=.9999,
        seed=42,
        device="auto",
        max_train_rows=180000,
        retrieval_k=32,
        retrieval_query_chunk=256,
        retrieval_memory_chunk=8192,
        backend="internal",
    ):
        self.latent_dim=int(latent_dim); self.hidden_dim=int(hidden_dim); self.epochs=int(epochs)
        self.batch_size=int(batch_size); self.temperature=float(temperature); self.lr=float(lr)
        self.weight_decay=float(weight_decay); self.aux_bce=float(aux_bce)
        self.hard_sampling=bool(hard_sampling); self.hard_strength=float(hard_strength)
        self.mechanism_aware=bool(mechanism_aware); self.mechanism_tau=float(mechanism_tau)
        self.class_beta=float(class_beta); self.seed=int(seed); self.device_name=str(device)
        self.max_train_rows=int(max_train_rows or 0); self.retrieval_k=int(retrieval_k)
        self.backend=str(backend).lower(); self.model_=None; self.metadata_={}; self.training_curve_=[]
        self.memory_z_=None; self.memory_y_=None; self.memory_X_=None
        self.retrieval_k = int(retrieval_k)

        self.retrieval_query_chunk = max(
            1,
            int(retrieval_query_chunk),
        )

        self.retrieval_memory_chunk = max(
            1,
            int(retrieval_memory_chunk),
        )

        self._retrieval_log_emitted = False

    @staticmethod
    def soft_neighbor_from_embeddings(
        query_z,
        memory_z,
        memory_y,
        *,
        temperature=.10,
        k=None,
        exclude_self=False,
        return_indices=False,
        chunk_size=256,
        memory_chunk_size=8192,
    ):
        """
        Exact memory-bounded soft-neighbor retrieval.

        For k > 0:
            Computes the exact global top-k neighbors while streaming over
            memory blocks. No Q x full_memory similarity matrix is created.

        For k <= 0 / None:
            Computes the exact softmax-weighted prediction over ALL memory
            rows using streaming log-sum-exp accumulation.

        The numerical/scientific retrieval definition is unchanged.
        """
        q = np.ascontiguousarray(np.asarray(query_z, dtype=np.float32))
        m = np.ascontiguousarray(np.asarray(memory_z, dtype=np.float32))
        y = np.asarray(memory_y, dtype=int).reshape(-1)

        if q.ndim != 2 or m.ndim != 2:
            raise ValueError("query_z and memory_z must be 2-D")
        if q.shape[1] != m.shape[1]:
            raise ValueError(
                f"embedding shape mismatch: query={q.shape}, memory={m.shape}"
            )
        if len(m) != len(y):
            raise ValueError("memory labels mismatch")
        if len(m) == 0:
            raise ValueError("empty retrieval memory")

        q_chunk = max(1, int(chunk_size))
        m_chunk = max(1, int(memory_chunk_size))
        temp = max(float(temperature), 1e-4)

        same_object = (
            bool(exclude_self)
            and len(q) == len(m)
            and (
                query_z is memory_z
                or np.array_equal(q, m)
            )
        )

        if same_object and len(m) <= 1:
            raise ValueError(
                "leave-self-out retrieval requires at least two memory rows"
            )

        # ------------------------------------------------------------------
        # Exact streaming full-memory softmax.
        # Normally Suite19 uses k=32, but retaining this branch makes the
        # primitive complete and prevents a future k=None call from restoring
        # the old OOM behaviour.
        # ------------------------------------------------------------------
        use_all_memory = k is None or int(k) <= 0

        if use_all_memory:
            if return_indices:
                raise ValueError(
                    "return_indices=True requires a positive k; "
                    "full-memory softmax has no finite top-k index set"
                )

            probs = []

            for qs in range(0, len(q), q_chunk):
                qe = min(qs + q_chunk, len(q))
                a = q[qs:qe]
                nq = len(a)

                running_max = np.full(nq, -np.inf, dtype=np.float64)
                running_den = np.zeros(nq, dtype=np.float64)
                running_num = np.zeros(nq, dtype=np.float64)

                for ms in range(0, len(m), m_chunk):
                    me = min(ms + m_chunk, len(m))
                    mb = m[ms:me]

                    sim = a @ mb.T

                    if same_object:
                        lo = max(qs, ms)
                        hi = min(qe, me)
                        if lo < hi:
                            g = np.arange(lo, hi)
                            sim[g - qs, g - ms] = -np.inf

                    logits = sim.astype(np.float64, copy=False) / temp
                    block_max = np.max(logits, axis=1)
                    new_max = np.maximum(running_max, block_max)

                    old_scale = np.zeros(nq, dtype=np.float64)
                    finite_old = np.isfinite(running_max)
                    old_scale[finite_old] = np.exp(
                        running_max[finite_old] - new_max[finite_old]
                    )

                    shifted = logits - new_max[:, None]
                    weights = np.exp(shifted)
                    weights[~np.isfinite(weights)] = 0.0

                    running_den = (
                        running_den * old_scale
                        + weights.sum(axis=1)
                    )

                    running_num = (
                        running_num * old_scale
                        + weights @ y[ms:me].astype(np.float64)
                    )

                    running_max = new_max

                if np.any(running_den <= 0):
                    raise RuntimeError(
                        "streaming soft-neighbor denominator became zero"
                    )

                probs.append(
                    (running_num / running_den).astype(np.float32)
                )

            return np.concatenate(probs)

        # ------------------------------------------------------------------
        # Exact streaming TOP-K.
        # ------------------------------------------------------------------
        max_neighbors = len(m) - (1 if exclude_self else 0)
        if max_neighbors <= 0:
            raise ValueError("no valid retrieval neighbors")

        kk = min(int(k), max_neighbors)
        kk = max(1, kk)

        all_probs = []
        all_indices = [] if return_indices else None

        for qs in range(0, len(q), q_chunk):
            qe = min(qs + q_chunk, len(q))
            a = q[qs:qe]
            nq = len(a)

            best_val = np.full(
                (nq, kk),
                -np.inf,
                dtype=np.float32,
            )
            best_idx = np.full(
                (nq, kk),
                -1,
                dtype=np.int64,
            )

            for ms in range(0, len(m), m_chunk):
                me = min(ms + m_chunk, len(m))
                mb = m[ms:me]

                # BOUNDED similarity matrix:
                # q_chunk x memory_chunk, never q_chunk x full_memory.
                sim = a @ mb.T

                if same_object:
                    lo = max(qs, ms)
                    hi = min(qe, me)

                    if lo < hi:
                        g = np.arange(lo, hi)
                        sim[g - qs, g - ms] = -np.inf

                width = sim.shape[1]
                local_k = min(kk, width)

                if local_k < width:
                    # Select the largest local_k values WITHOUT creating -sim.
                    kth = width - local_k
                    local_part = np.argpartition(
                        sim,
                        kth=kth,
                        axis=1,
                    )[:, -local_k:]
                else:
                    local_part = np.broadcast_to(
                        np.arange(width, dtype=np.int64),
                        (nq, width),
                    )

                local_val = np.take_along_axis(
                    sim,
                    local_part,
                    axis=1,
                )

                local_idx = (
                    local_part.astype(np.int64, copy=False)
                    + ms
                )

                # Merge block-local top-k with the running global top-k.
                merged_val = np.concatenate(
                    [best_val, local_val],
                    axis=1,
                )
                merged_idx = np.concatenate(
                    [best_idx, local_idx],
                    axis=1,
                )

                if merged_val.shape[1] > kk:
                    kth = merged_val.shape[1] - kk

                    keep = np.argpartition(
                        merged_val,
                        kth=kth,
                        axis=1,
                    )[:, -kk:]

                    best_val = np.take_along_axis(
                        merged_val,
                        keep,
                        axis=1,
                    )
                    best_idx = np.take_along_axis(
                        merged_idx,
                        keep,
                        axis=1,
                    )
                else:
                    best_val = merged_val
                    best_idx = merged_idx

            if np.any(best_idx < 0):
                raise RuntimeError(
                    "streaming top-k failed to fill neighbor set"
                )

            # Canonical descending ranking.
            order = np.argsort(
                -best_val,
                axis=1,
                kind="stable",
            )

            val = np.take_along_axis(
                best_val,
                order,
                axis=1,
            )
            idx = np.take_along_axis(
                best_idx,
                order,
                axis=1,
            )

            vmax = np.max(val, axis=1, keepdims=True)

            # Float64 only for tiny Q x K softmax matrix.
            weights = np.exp(
                ((val - vmax) / temp).astype(np.float64)
            )
            weights /= np.maximum(
                weights.sum(axis=1, keepdims=True),
                EPS,
            )

            p = np.sum(
                weights * y[idx],
                axis=1,
            )

            all_probs.append(p.astype(np.float32))

            if return_indices:
                all_indices.append(idx)

        probs = np.concatenate(all_probs)

        if return_indices:
            indices = np.concatenate(all_indices, axis=0)
            return probs, indices

        return probs

    def _nca_loss(self,z,y,mechanism=None):
        n=len(y)
        sim=z@z.T/max(self.temperature,1e-4)
        eye=torch.eye(n,dtype=torch.bool,device=z.device)
        sim=sim.masked_fill(eye,-torch.inf)
        log_den=torch.logsumexp(sim,dim=1)
        same=(y[:,None]==y[None,:])&(~eye)
        pos_logits=sim
        if self.mechanism_aware and mechanism is not None:
            # Explicit ablation: same-outcome positive pairs sharing similar
            # chronology-safe mechanisms receive greater positive-pair mass.
            md=torch.cdist(mechanism,mechanism,p=2)
            logw=-md/max(self.mechanism_tau,1e-4)
            pos_logits=pos_logits+logw
        pos_logits=pos_logits.masked_fill(~same,-torch.inf)
        log_num=torch.logsumexp(pos_logits,dim=1)
        valid=same.any(1)&torch.isfinite(log_num)
        if not valid.any():
            return z.sum()*0.0
        return -(log_num[valid]-log_den[valid]).mean()

    def fit(self,X,y,committee=None,mechanism=None,faculty=None):
        if self.backend!="internal":
            raise ValueError("Suite19 ModernNCA currently has one explicit backend: 'internal' faithful metric implementation")
        if torch is None:raise ImportError("PyTorch required for ModernNCA")
        seed_everything(self.seed);dev=resolve_device(self.device_name)
        X=np.asarray(X,np.float32);y=np.asarray(y,int);fac=np.zeros(len(y),int) if faculty is None else np.asarray(faculty,int)
        if np.unique(y).size<2:raise ValueError("ModernNCA requires both classes")
        mech=None if mechanism is None else np.asarray(mechanism,np.float32)
        if self.mechanism_aware and mech is None:raise ValueError("mechanism-aware NCA requires chronology-safe mechanism targets")
        w=faculty_class_effective_weights(y,fac,self.class_beta).astype(float)
        if self.hard_sampling:
            if committee is None:raise ValueError("hard sampling requires Committee scores from the same legal training prefix")
            w*=committee_hard_sampling_weights(y,committee,self.hard_strength)
        idx=_subsample_indices(len(y),self.max_train_rows,w,self.seed);X=X[idx];y=y[idx];fac=fac[idx];w=w[idx];mech=None if mech is None else mech[idx]
        w=np.clip(w,EPS,None);w/=w.sum()
        model=_NCANet(X.shape[1],self.hidden_dim,self.latent_dim).to(dev);self.model_=model
        opt=torch.optim.AdamW(model.parameters(),lr=self.lr,weight_decay=self.weight_decay);rng=np.random.default_rng(self.seed)
        self.training_curve_=[];t0=time.perf_counter()
        bsz=max(8,min(self.batch_size,len(X)))
        for epoch in range(1,max(1,self.epochs)+1):
            model.train();losses=[];metric_losses=[];aux_losses=[]
            # Probability sampling intentionally reflects faculty/class and explicit hard-case weights.
            steps=max(1,math.ceil(len(X)/bsz))
            for _ in range(steps):
                bi=rng.choice(len(X),size=bsz,replace=len(X)<bsz,p=w)
                xb=torch.as_tensor(X[bi],device=dev);yb=torch.as_tensor(y[bi],dtype=torch.long,device=dev)
                mb=None if mech is None else torch.as_tensor(mech[bi],device=dev)
                opt.zero_grad(set_to_none=True);z,aux=model(xb);ml=self._nca_loss(z,yb,mb)
                al=F.binary_cross_entropy_with_logits(aux,yb.float()) if self.aux_bce>0 else ml*0.0
                loss=ml+self.aux_bce*al
                if not torch.isfinite(loss):raise FloatingPointError("ModernNCA non-finite training loss")
                loss.backward();torch.nn.utils.clip_grad_norm_(model.parameters(),10.0);opt.step()
                losses.append(float(loss.detach().cpu()));metric_losses.append(float(ml.detach().cpu()));aux_losses.append(float(al.detach().cpu()))
            self.training_curve_.append({'epoch':epoch,'loss':float(np.mean(losses)),'metric_loss':float(np.mean(metric_losses)),'aux_bce_loss':float(np.mean(aux_losses))})
        train_seconds=time.perf_counter()-t0
        self.memory_X_ = None
        self.memory_y_ = np.asarray(y, dtype=np.int8).copy()
        self.memory_z_ = self.transform(X)
        self.metadata_={'encoder':self.name,'implementation':self.implementation,'backend':self.backend,'latent_dim':self.latent_dim,'hidden_dim':self.hidden_dim,'temperature':self.temperature,'aux_bce':self.aux_bce,'hard_sampling':self.hard_sampling,'hard_strength':self.hard_strength,'mechanism_aware':self.mechanism_aware,'mechanism_tau':self.mechanism_tau,'retrieval_k':self.retrieval_k,'epochs':self.epochs,'train_rows_used':len(X),'train_failures_used':int(y.sum()),'train_prevalence_used':float(y.mean()),'train_seconds':float(train_seconds),'parameter_count':int(sum(p.numel() for p in model.parameters())),'training_curve':self.training_curve_,'sampling_weight_min':float(w.min()),'sampling_weight_max':float(w.max()),'methodological_note':'normalized differentiable metric embedding with leave-self-out NCA soft-neighbor objective; auxiliary BCE/hard/mechanism variants are explicit ablations',
                        "retrieval_implementation": "exact_streaming_topk_v1",
                        "retrieval_query_chunk": self.retrieval_query_chunk,
                        "retrieval_memory_chunk": self.retrieval_memory_chunk,
                        "retrieval_similarity_block_mb": float(
                            self.retrieval_query_chunk
                            * self.retrieval_memory_chunk
                            * 4
                            / (1024 ** 2)
                        ),
                        "retrieval_partition_index_block_mb": float(
                            self.retrieval_query_chunk
                            * self.retrieval_memory_chunk
                            * 8
                            / (1024 ** 2)
                        ),}
        return self

    @torch.no_grad() if torch is not None else (lambda f:f)
    def transform(self,X):
        if self.model_ is None:raise RuntimeError("ModernNCA is not fitted")
        dev=resolve_device(self.device_name);self.model_.eval();X=np.asarray(X,np.float32);out=[]
        for s in range(0,len(X),4096):out.append(self.model_.encode(torch.as_tensor(X[s:s+4096],device=dev)).cpu().numpy())
        return np.concatenate(out).astype(np.float32)

    @torch.no_grad() if torch is not None else (lambda f:f)
    def direct_predict(self,X):
        if self.model_ is None:return None
        dev=resolve_device(self.device_name);self.model_.eval();X=np.asarray(X,np.float32);out=[]
        for s in range(0,len(X),4096):
            _,a=self.model_(torch.as_tensor(X[s:s+4096],device=dev));out.append(torch.sigmoid(a).cpu().numpy())
        return np.concatenate(out).astype(np.float32)

    def native_predict(
        self,
        X,
        memory_X=None,
        memory_y=None,
        exclude_self=False,
    ):
        qz = self.transform(X)

        if memory_X is None:
            mz = self.memory_z_
            my = self.memory_y_

            if mz is None or my is None:
                raise RuntimeError(
                    "ModernNCA retrieval memory is unavailable"
                )
        else:
            mz = self.transform(memory_X)
            my = np.asarray(memory_y, int)

        if not self._retrieval_log_emitted:
            sim_mb = (
                self.retrieval_query_chunk
                * self.retrieval_memory_chunk
                * 4
                / (1024 ** 2)
            )

            idx_mb = (
                self.retrieval_query_chunk
                * self.retrieval_memory_chunk
                * 8
                / (1024 ** 2)
            )

            old_q = min(4096, len(qz))

            old_sim_gib = (
                old_q
                * len(mz)
                * 4
                / (1024 ** 3)
            )

            print(
                "[NCA RETRIEVAL] "
                f"method=exact_streaming_topk_v1 "
                f"query_rows={len(qz)} "
                f"memory_rows={len(mz)} "
                f"latent_dim={mz.shape[1]} "
                f"k={self.retrieval_k} "
                f"q_chunk={self.retrieval_query_chunk} "
                f"memory_chunk={self.retrieval_memory_chunk} "
                f"sim_block≈{sim_mb:.1f}MiB "
                f"partition_index_block≈{idx_mb:.1f}MiB "
                f"old_dense_sim_only≈{old_sim_gib:.2f}GiB"
            )

            self._retrieval_log_emitted = True

        return self.soft_neighbor_from_embeddings(
            qz,
            mz,
            my,
            temperature=self.temperature,
            k=self.retrieval_k,
            exclude_self=exclude_self,
            chunk_size=self.retrieval_query_chunk,
            memory_chunk_size=self.retrieval_memory_chunk,
        )

    def predict_proba(self,X):
        # Native metric prediction is the primary ModernNCA score.
        return self.native_predict(X)

    def neighbor_examples(self,X,memory_X,memory_y,k=5,max_queries=10):
        qz=self.transform(X);mz=self.transform(memory_X);my=np.asarray(memory_y,int);n=min(int(max_queries),len(qz));rows=[]
        p,idx=self.soft_neighbor_from_embeddings(qz[:n],mz,my,temperature=self.temperature,k=max(k,self.retrieval_k),return_indices=True)
        fail=np.where(my==1)[0];normal=np.where(my==0)[0]
        for qi in range(n):
            sims=qz[qi]@mz[idx[qi]].T; top=idx[qi,:k]
            closest_failure=float(np.min(np.linalg.norm(mz[fail]-qz[qi],axis=1))) if len(fail) else np.nan
            closest_normal=float(np.min(np.linalg.norm(mz[normal]-qz[qi],axis=1))) if len(normal) else np.nan
            top_failure_fraction=float(np.mean(my[top])) if len(top) else np.nan
            for rank,(mi,sim) in enumerate(zip(top,sims[:k]),1):
                rows.append({'query_index':qi,'neighbor_rank':rank,'neighbor_index':int(mi),'neighbor_label':int(my[mi]),'cosine_similarity':float(sim),'distance':float(np.linalg.norm(qz[qi]-mz[mi])),'query_native_probability':float(p[qi]),'topk_failure_fraction':top_failure_fraction,'distance_to_closest_failure':closest_failure,'distance_to_closest_normal':closest_normal,'retrieval_support':int(len(self.memory_y_) if self.memory_y_ is not None else len(my))})
        return rows


# ---------------------------------------------------------------------------
# RFM / AGOP
# ---------------------------------------------------------------------------


def _sym_psd(M, floor=1e-8):
    M=np.asarray(M,float);M=(M+M.T)/2
    vals,vecs=np.linalg.eigh(M);vals=np.clip(vals,float(floor),None);M=(vecs*vals[None,:])@vecs.T
    return ((M+M.T)/2).astype(np.float64)


def _metric_eigendecomposition(M):
    vals,vecs=np.linalg.eigh((np.asarray(M,float)+np.asarray(M,float).T)/2);order=np.argsort(-vals);return np.clip(vals[order],0,None),vecs[:,order]


class RFMAGOPEncoder(BaseRepresentationEncoder):
    name="rfm"

    def __init__(self,latent_dim=32,recursions=2,centers=512,agop_rows=2048,ridge=1e-3,bandwidth=1.0,metric_floor=1e-6,seed=42,backend="official",device="auto",max_train_rows=20000,mem_gb=8):
        self.latent_dim=int(latent_dim);self.recursions=int(recursions);self.centers=int(centers);self.agop_rows=int(agop_rows);self.ridge=float(ridge);self.bandwidth=float(bandwidth);self.metric_floor=float(metric_floor);self.seed=int(seed);self.backend=str(backend).lower();self.device_name=str(device);self.max_train_rows=int(max_train_rows or 0);self.mem_gb=float(mem_gb)
        self.metric_matrix_=None;self.eigvals_=None;self.eigvecs_=None;self.metric_transform_=None;self.metadata_={};self.recursion_history_=[];self.model_=None;self.centers_=None;self.alpha_=None

    def _weighted_subset(self,X,y,faculty):
        w=faculty_class_effective_weights(y,faculty,.9999);idx=_subsample_indices(len(y),self.max_train_rows,w,self.seed);return X[idx],y[idx],idx

    def _official_fit(self, X, y):
        """
        Official aradha/recursive_feature_machines pip_install adapter.

        Validated against the current official API:
        LaplaceRFM(
            bandwidth,
            device,
            mem_gb,
            diag,
            centering,
            reg,
            iters,
            p_batch_size,
            bandwidth_mode
        )

        No silent backend fallback is permitted.
        """
        try:
            import torch
            from rfm import LaplaceRFM
        except Exception as e:
            raise ImportError(
                "Official RFM backend requested but the official 'rfm' package "
                "is unavailable. Install "
                "aradha/recursive_feature_machines@pip_install."
            ) from e

        dev = resolve_device(self.device_name)

        Xt = torch.as_tensor(
            np.asarray(X, dtype=np.float32),
            dtype=torch.float32,
            device=dev,
        )

        yt = torch.as_tensor(
            np.asarray(y, dtype=np.float32).reshape(-1, 1),
            dtype=torch.float32,
            device=dev,
        )

        # IMPORTANT:
        # self.ridge is Suite19's kernel regularization hyperparameter.
        # In the official RFM API this is called `reg`.
        #
        # self.metric_floor is NOT an RFM constructor argument. It remains
        # Suite19's post-fit PSD/eigenvalue stabilization floor.
        model = LaplaceRFM(
            bandwidth=float(self.bandwidth),
            device=dev,
            mem_gb=float(self.mem_gb),
            diag=False,
            centering=False,
            reg=float(self.ridge),
            iters=max(1, int(self.recursions)),
            bandwidth_mode="constant",
        )

        # Current upstream implementation may choose CUDA internally whenever
        # CUDA exists. Reinforce Suite19's requested device explicitly.
        model.device = torch.device(dev)

        t0 = time.perf_counter()

        try:
            model.fit(
                (Xt, yt),
                (Xt, yt),
                iters=max(1, int(self.recursions)),
                method="lstsq",
                classification=False,
                verbose=False,

                # Honour Suite19's AGOP sampling budget instead of allowing
                # the upstream default of 20,000 when we explicitly requested
                # --rfm_agop_rows.
                total_points_to_sample=min(
                    int(self.agop_rows),
                    int(len(Xt)),
                ),

                return_best_params=False,
                return_Ms=False,
                fit_last_M=False,
            )
        except Exception as e:
            raise RuntimeError(
                "Official LaplaceRFM.fit failed.\n"
                f"rows={len(Xt)}\n"
                f"features={Xt.shape[1]}\n"
                f"recursions={self.recursions}\n"
                f"bandwidth={self.bandwidth}\n"
                f"reg={self.ridge}\n"
                f"agop_rows={min(int(self.agop_rows), len(Xt))}\n"
                f"mem_gb={self.mem_gb}\n"
                f"device={dev}\n"
                f"original_error={type(e).__name__}: {e}"
            ) from e

        sec = time.perf_counter() - t0

        if not hasattr(model, "M") or model.M is None:
            raise RuntimeError(
                "Official LaplaceRFM finished without exposing learned metric M."
            )

        M = (
            model.M.detach().cpu().numpy()
            if hasattr(model.M, "detach")
            else np.asarray(model.M)
        )

        if M.ndim != 2 or M.shape != (X.shape[1], X.shape[1]):
            raise RuntimeError(
                f"Unexpected official RFM metric shape: {M.shape}; "
                f"expected {(X.shape[1], X.shape[1])}"
            )

        if not np.isfinite(M).all():
            raise RuntimeError(
                "Official RFM emitted a non-finite learned metric."
            )

        self.model_ = model

        # metric_floor belongs HERE, not in LaplaceRFM(...)
        self.metric_matrix_ = _sym_psd(
            M,
            self.metric_floor,
        )

        train_pred = self._official_predict(X)

        self.recursion_history_ = [{
            "recursion": int(self.recursions),
            "metric_trace": float(
                np.trace(self.metric_matrix_)
            ),
            "native_train_ap": safe_ap(
                y,
                train_pred,
            ),
            "native_train_auc": safe_auc(
                y,
                train_pred,
            ),
            "official_fit_seconds": float(sec),
            "official_reg": float(self.ridge),
            "suite19_metric_floor": float(
                self.metric_floor
            ),
            "agop_rows_requested": int(
                self.agop_rows
            ),
            "agop_rows_used": int(
                min(self.agop_rows, len(X))
            ),
        }]

        return sec

    def _official_predict(self,X):
        dev=resolve_device(self.device_name);xt=torch.as_tensor(np.asarray(X,np.float32),device=dev)
        with torch.no_grad():p=self.model_.predict(xt)
        p=p.detach().cpu().numpy().reshape(-1) if hasattr(p,'detach') else np.asarray(p).reshape(-1)
        return np.clip(p,0,1).astype(np.float32)

    @staticmethod
    def _rbf_features(X,C,M,bw):
        # Gaussian metric kernel for scalable internal AGOP diagnostic backend.
        XM=X@M;CM=C@M
        d=np.sum(XM*X,1)[:,None]+np.sum(CM*C,1)[None,:]-2*XM@C.T
        d=np.maximum(d,0);return np.exp(-d/(2*max(bw,1e-4)**2))

    def _fit_internal_predictor(self,X,y,C,M):
        K=self._rbf_features(X,C,M,self.bandwidth);A=K.T@K+self.ridge*np.eye(K.shape[1]);b=K.T@y.astype(float);alpha=np.linalg.solve(A,b);return alpha

    def _internal_gradients(self,X,C,M,alpha):
        K=self._rbf_features(X,C,M,self.bandwidth);D=X[:,None,:]-C[None,:,:]
        # grad_x k = -k * (M @ (x-c)) / bw^2; M is symmetric metric.
        MD=np.einsum('ab,nkb->nka',M,D);coef=-(K*alpha[None,:])/(max(self.bandwidth,1e-4)**2);return np.einsum('nk,nkd->nd',coef,MD)

    def _internal_fit(self,X,y):
        rng=np.random.default_rng(self.seed);d=X.shape[1];M=np.eye(d);hist=[];t0=time.perf_counter();C=None;alpha=None
        for r in range(1,max(1,self.recursions)+1):
            ci=rng.choice(len(X),size=min(self.centers,len(X)),replace=False);C=X[ci];alpha=self._fit_internal_predictor(X,y,C,M)
            ai=rng.choice(len(X),size=min(self.agop_rows,len(X)),replace=False);G=self._internal_gradients(X[ai],C,M,alpha);agop=(G.T@G)/max(len(G),1);agop=_sym_psd(agop,self.metric_floor)
            # Normalize global scale so bandwidth semantics remain stable.
            tr=max(float(np.trace(agop)),EPS);M=agop*(d/tr)
            alpha_after=self._fit_internal_predictor(X,y,C,M)
            pred=np.clip(self._rbf_features(X,C,M,self.bandwidth)@alpha_after,0,1)
            vals,_=_metric_eigendecomposition(M);p=vals/max(vals.sum(),EPS);er=float(np.exp(-np.sum(p[p>0]*np.log(p[p>0]))))
            hist.append({'recursion':r,'native_train_ap':safe_ap(y,pred),'native_train_auc':safe_auc(y,pred),'metric_trace':float(np.trace(M)),'metric_effective_rank':er,'top_eigenvalue':float(vals[0])})
        # Refit predictor under final metric.
        ci=rng.choice(len(X),size=min(self.centers,len(X)),replace=False);C=X[ci];alpha=self._fit_internal_predictor(X,y,C,M)
        self.centers_=C;self.alpha_=alpha;self.metric_matrix_=_sym_psd(M,self.metric_floor);self.recursion_history_=hist
        return time.perf_counter()-t0

    def fit(self,X,y,committee=None,mechanism=None,faculty=None):
        X=np.asarray(X,np.float32);y=np.asarray(y,int);fac=np.zeros(len(y),int) if faculty is None else np.asarray(faculty,int)
        if np.unique(y).size<2:raise ValueError("RFM requires both classes")
        Xs,ys,idx=self._weighted_subset(X,y,fac);self.train_subset_idx_=idx
        if self.backend=='official':self.implementation='official_aradha_laplace_rfm';seconds=self._official_fit(Xs,ys)
        elif self.backend=='internal':self.implementation='internal_low_rank_agop_diagnostic';seconds=self._internal_fit(Xs,ys)
        else:raise ValueError("RFM backend must be 'official' or explicit 'internal'")
        vals,vecs=_metric_eigendecomposition(self.metric_matrix_);k=min(self.latent_dim,len(vals));self.eigvals_=vals;self.eigvecs_=vecs;self.metric_transform_=vecs[:,:k]*np.sqrt(np.clip(vals[:k],0,None))[None,:]
        energy=np.cumsum(vals)/max(vals.sum(),EPS);p=vals/max(vals.sum(),EPS);er=float(np.exp(-np.sum(p[p>0]*np.log(p[p>0]))))
        self.metadata_={'encoder':self.name,'implementation':self.implementation,'backend':self.backend,'package_version':_package_version('rfm') if self.backend=='official' else 'internal','latent_dim':int(k),'recursions':self.recursions,'bandwidth':self.bandwidth,'ridge':self.ridge,'train_rows_input':len(X),'train_rows_used':len(Xs),'train_failures_used':int(ys.sum()),'train_prevalence_used':float(ys.mean()),'train_seconds':float(seconds),'metric_effective_rank':er,'metric_eigenvalues':vals.tolist(),'metric_cumulative_energy':energy.tolist(),'metric_eigenvectors_top':vecs[:,:k].tolist(),'recursion_history':self.recursion_history_,'methodological_note':('Official aradha LaplaceRFM; target/future labels never supplied' if self.backend=='official' else 'DIAGNOSTIC ONLY: scalable internal Gaussian-kernel AGOP recursion; not official RFM')}
        return self

    def transform(self,X):
        if self.metric_transform_ is None:raise RuntimeError("RFM encoder is not fitted")
        return (np.asarray(X,np.float32)@self.metric_transform_).astype(np.float32)

    def native_predict(self,X,memory_X=None,memory_y=None,exclude_self=False):
        if self.backend=='official':return self._official_predict(X)
        return np.clip(self._rbf_features(np.asarray(X,np.float32),self.centers_,self.metric_matrix_,self.bandwidth)@self.alpha_,0,1).astype(np.float32)

    def predict_proba(self,X):return self.native_predict(X)

    def direct_predict(self,X):return self.native_predict(X)


# ---------------------------------------------------------------------------
# Matched compression controls
# ---------------------------------------------------------------------------


class PCARepresentationEncoder(BaseRepresentationEncoder):
    name='pca';implementation='sklearn_pca'
    def __init__(self,latent_dim=32,seed=42,**_):self.latent_dim=int(latent_dim);self.seed=int(seed);self.model_=None;self.metadata_={}
    def fit(self,X,y=None,committee=None,mechanism=None,faculty=None):
        X=np.asarray(X,np.float32);k=min(self.latent_dim,X.shape[1],max(1,len(X)-1));self.model_=PCA(n_components=k,svd_solver='auto',random_state=self.seed).fit(X);self.metadata_={'encoder':self.name,'implementation':self.implementation,'latent_dim':k,'train_rows_used':len(X),'explained_variance_ratio':float(self.model_.explained_variance_ratio_.sum())};return self
    def transform(self,X):return self.model_.transform(np.asarray(X,np.float32)).astype(np.float32)
    def predict_proba(self,X):return None


class RandomProjectionRepresentationEncoder(BaseRepresentationEncoder):
    name='random_projection';implementation='sklearn_gaussian_random_projection'
    def __init__(self,latent_dim=32,seed=42,**_):self.latent_dim=int(latent_dim);self.seed=int(seed);self.model_=None;self.metadata_={}
    def fit(self,X,y=None,committee=None,mechanism=None,faculty=None):
        X=np.asarray(X,np.float32);k=max(1,int(self.latent_dim));self.model_=GaussianRandomProjection(n_components=k,random_state=self.seed).fit(X);self.metadata_={'encoder':self.name,'implementation':self.implementation,'latent_dim':k,'train_rows_used':len(X)};return self
    def transform(self,X):return self.model_.transform(np.asarray(X,np.float32)).astype(np.float32)
    def predict_proba(self,X):return None


def make_encoder(name: str, **kwargs) -> BaseRepresentationEncoder:
    n=name.lower().strip()
    if n=='tabm':return TabMRepresentationEncoder(**kwargs)
    if n in {'modern_nca','nca'}:return ModernNCAEncoder(**kwargs)
    if n in {'modern_nca_hard','nca_hard'}:kwargs['hard_sampling']=True;return ModernNCAEncoder(**kwargs)
    if n in {'modern_nca_mechanism','nca_mechanism'}:kwargs['mechanism_aware']=True;return ModernNCAEncoder(**kwargs)
    if n in {'rfm','rfm_agop'}:return RFMAGOPEncoder(**kwargs)
    if n=='pca':return PCARepresentationEncoder(**kwargs)
    if n in {'random','random_projection','rp'}:return RandomProjectionRepresentationEncoder(**kwargs)
    raise KeyError(f'unknown encoder {name}')
