tabctx 0.9.0__py3-none-any.whl

tabctx/__init__.py

@@ -0,0 +1,41 @@
+"""tabctx: multi-tenant context caching and serving for tabular
+in-context-learning foundation models (TabICL, TabPFN, and similar).
+
+The core idea: these models already cache their encoded training context
+internally to speed up repeated predict() calls against the same training
+set (both TabICL and TabPFN call this a "KV cache"), but only as a
+single-process, single-estimator-object feature. tabctx makes that a real
+multi-tenant, evictable, memory-governed resource -- the analog of what
+PagedAttention did for per-request LLM KV caches.
+"""
+
+from tabctx.cache.manager import CachedContext, ContextCacheManager
+from tabctx.engine import TabctxEngine
+from tabctx.errors import (
+    AdmissionRejected,
+    BackendComputeError,
+    CacheCapacityError,
+    DatasetNotFoundError,
+    InvalidInputError,
+    TabctxError,
+    UploadNotFoundError,
+    UploadTooLargeError,
+)
+from tabctx.types import EngineStats, PredictOutcome, Task
+
+__all__ = [
+    "AdmissionRejected",
+    "BackendComputeError",
+    "CacheCapacityError",
+    "CachedContext",
+    "ContextCacheManager",
+    "DatasetNotFoundError",
+    "EngineStats",
+    "InvalidInputError",
+    "PredictOutcome",
+    "TabctxEngine",
+    "TabctxError",
+    "Task",
+    "UploadNotFoundError",
+    "UploadTooLargeError",
+]

tabctx/backends/__init__.py

@@ -0,0 +1,3 @@
+from tabctx.backends.base import TabularICLBackend
+
+__all__ = ["TabularICLBackend"]

tabctx/backends/base.py

@@ -0,0 +1,58 @@
+"""Backend protocol: what tabctx needs from a tabular ICL model implementation.
+
+This is the seam that lets tabctx add a second backend (e.g. TabPFN) later
+without touching the cache manager, memory estimator, or engine -- none of
+those import a specific backend, they only depend on this protocol.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from tabctx.types import ArrayLike, PredictOutcome, Task
+
+
+class TabularICLBackend(Protocol):
+    """A tabular in-context-learning model, wrapped for tabctx.
+
+    Implementations MUST construct a fresh underlying estimator/model
+    instance inside every fit() call. fit() mutates instance state (that's
+    the whole point -- it's where the training context gets encoded), so
+    reusing one shared instance across dataset_ids would silently corrupt
+    every cached context that isn't the most recent one.
+    """
+
+    name: str
+
+    def fit(self, X: ArrayLike, y: ArrayLike, task: Task) -> Any:
+        """Encode the training context. Returns an opaque, backend-owned
+        payload that the cache manager retains standalone (the engine never
+        inspects it) and later passes back into predict()."""
+        ...
+
+    def predict(
+        self, payload: Any, X_test: ArrayLike, return_proba: bool = False
+    ) -> PredictOutcome:
+        """Run inference against a cached context. Must be a SINGLE
+        inference pass regardless of return_proba -- derive predictions from
+        probabilities (e.g. argmax) rather than calling predict() and
+        predict_proba() separately, since each call is a full forward pass
+        over the cached context."""
+        ...
+
+    def context_bytes_hint(self, n_train: int, n_features: int) -> int | None:
+        """RESIDENT cost of the context most recently returned by fit(),
+        for cache capacity/eviction accounting -- called by the engine
+        AFTER fit(), not before, so an implementation can report a real
+        measurement (e.g. actual device memory delta) instead of a guess.
+        Return None if the backend has no opinion; the engine falls back
+        to its own (much more conservative, pre-fit-only) MemoryEstimator.
+
+        Implementations MAY also expose ``fit_peak_bytes_hint() -> int |
+        None`` (optional; the engine probes with getattr): the TRANSIENT
+        high-water memory of the most recent fit(). That is the
+        admission-relevant quantity -- peak is what actually OOMs, and it
+        can exceed the resident context by orders of magnitude -- and the
+        engine feeds it (not the resident size) back into the estimator's
+        admission learning."""
+        ...

tabctx/backends/fake.py

@@ -0,0 +1,99 @@
+"""Deterministic backend with no GPU/torch/tabicl dependency, for unit tests.
+
+Not a serious model: classification predicts the training majority class for
+every test row, regression predicts the training mean. What matters for
+tabctx's own tests is the *shape* of the contract (fit returns an opaque
+payload, predict does one pass, context_bytes_hint is controllable), not
+prediction quality.
+"""
+
+from __future__ import annotations
+
+import time
+from collections import Counter
+from dataclasses import dataclass
+from typing import Any
+
+from tabctx.types import ArrayLike, PredictOutcome, Task
+
+
+@dataclass
+class _FakePayload:
+    task: Task
+    n_train: int
+    n_features: int
+    majority_class: str | None = None
+    class_fractions: dict[str, float] | None = None
+    mean_y: float | None = None
+
+
+class FakeBackend:
+    """Test double. `fit_delay_s`/`predict_delay_s` let tests simulate work
+    without a real GPU, e.g. to assert cache reuse actually skips fit()."""
+
+    name = "fake"
+
+    def __init__(
+        self,
+        bytes_hint: int | None = None,
+        fit_delay_s: float = 0.0,
+        predict_delay_s: float = 0.0,
+        peak_bytes_hint: int | None = None,
+        name: str = "fake",
+    ) -> None:
+        self.name = name  # instance override (tests deploy several fakes)
+        self._bytes_hint = bytes_hint
+        self._peak_bytes_hint = peak_bytes_hint
+        self._fit_delay_s = fit_delay_s
+        self._predict_delay_s = predict_delay_s
+        self.fit_calls = 0
+        self.predict_calls = 0
+
+    def fit(self, X: ArrayLike, y: ArrayLike, task: Task) -> Any:
+        self.fit_calls += 1
+        if self._fit_delay_s:
+            time.sleep(self._fit_delay_s)
+        n_train = len(X)
+        n_features = len(X[0]) if n_train else 0
+        if task == "classification":
+            counts = Counter(str(v) for v in y)
+            total = sum(counts.values()) or 1
+            return _FakePayload(
+                task=task,
+                n_train=n_train,
+                n_features=n_features,
+                majority_class=counts.most_common(1)[0][0] if counts else None,
+                class_fractions={k: v / total for k, v in counts.items()},
+            )
+        mean_y = sum(float(v) for v in y) / len(y) if len(y) else 0.0
+        return _FakePayload(
+            task=task, n_train=n_train, n_features=n_features, mean_y=mean_y
+        )
+
+    def predict(
+        self, payload: _FakePayload, X_test: ArrayLike, return_proba: bool = False
+    ) -> PredictOutcome:
+        self.predict_calls += 1
+        if self._predict_delay_s:
+            time.sleep(self._predict_delay_s)
+        n_test = len(X_test)
+        if payload.task == "classification":
+            predictions = [payload.majority_class] * n_test
+            probabilities = None
+            classes = None
+            if return_proba:
+                fractions = payload.class_fractions or {}
+                classes = sorted(fractions)
+                row = [fractions.get(c, 0.0) for c in classes]
+                probabilities = [row for _ in range(n_test)]
+            return PredictOutcome(
+                predictions=predictions, probabilities=probabilities, classes=classes
+            )
+        return PredictOutcome(predictions=[payload.mean_y] * n_test)
+
+    def context_bytes_hint(self, n_train: int, n_features: int) -> int | None:
+        del n_train, n_features  # unused: this backend's hint is fixed at construction
+        return self._bytes_hint
+
+    def fit_peak_bytes_hint(self) -> int | None:
+        return self._peak_bytes_hint

tabctx/backends/tabicl.py

@@ -0,0 +1,263 @@
+"""TabICL/TabICLv2 backend (github.com/soda-inria/tabicl).
+
+Fixes two bugs found in the hand-rolled wrapper this library replaces
+(inference-platform's tests/gke-tabicl-test/app.py):
+
+1. That wrapper called model.predict() and then model.predict_proba()
+   separately when return_proba was requested -- two full inference passes
+   for one request. Here, predict_proba() is called once and predictions are
+   derived from it via argmax, so return_proba never costs an extra pass.
+2. That wrapper built a fresh estimator per request and never reused
+   anything across requests, discarding the entire benefit of TabICL's own
+   fit-time context caching. Here, fit() still builds a fresh estimator per
+   call (required -- see backends/base.py), but the returned estimator is
+   retained by tabctx's ContextCacheManager and reused across many predict()
+   calls, which is the actual point of this library.
+
+torch/tabicl are imported lazily inside this module (not at package import
+time) so the rest of tabctx has no hard dependency on either.
+
+EMPIRICAL CHECK (per the tabctx build plan, run locally on CPU before
+finalizing this file): does constructing a fresh TabICLClassifier/Regressor
+reload the checkpoint every time, or is it memoized in-process? Confirmed by
+reading tabicl/_sklearn/classifier.py's _load_model(): huggingface_hub only
+avoids re-downloading (the file is cached on disk after the first fetch),
+but torch.load() + load_state_dict() run fresh on every instantiation --
+there is no in-process memoization. Measured cost of that reload alone (CPU,
+checkpoint already on disk): ~0.1s per fit() call, separate from and in
+addition to the actual context-encoding cost. Fine for v1 (a fresh instance
+per fit() is required regardless -- see backends/base.py), but a real
+optimization opportunity for later: load the backbone weights once per
+backend instance and share them across fit() calls, keeping only the
+per-fit training-encoding state instance-specific.
+
+REAL GPU MEMORY MEASUREMENT (found via extensive multi-tenant load testing
+on a real A100-40GB, 2026-08-28): the formula-based MemoryEstimator, when
+used to size a context for cache-capacity accounting, reported ~14x more
+bytes than what was actually resident on the device for a realistic shape
+(cache accounting said ~21.85GB used; torch.cuda.memory_allocated() said
+~1.56GB) -- because that estimator is calibrated on active train+test
+forward-pass memory, not resting post-fit context size, and (separately)
+already over-estimates small inputs (see memory/estimator.py). This
+needlessly throttled effective multi-tenant capacity to a fraction of what
+the hardware actually supports. Fixed here by measuring the real
+torch.cuda.memory_allocated() delta across fit() and reporting it via
+context_bytes_hint() -- safe because the engine holds its cache lock across
+the whole fit() call (see engine.py), so no concurrent GPU work can pollute
+the before/after delta.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from tabctx.errors import BackendComputeError
+from tabctx.types import ArrayLike, PredictOutcome, Task
+
+
+class TabICLBackend:
+    # The exact model id callers select via the API's `model` field --
+    # named for the checkpoint actually loaded (tabicl-classifier-v2-*).
+    name = "tabicl-v2"
+
+    def __init__(self, device: str | None = None, kv_cache: bool | str = "kv") -> None:
+        """kv_cache: passed through to TabICL ("kv", "repr", True, or
+        False). tabicl's own default is False, which makes every
+        predict() re-encode the ENTIRE training set through all three
+        transformer stages -- i.e. the exact cost tabctx exists to avoid
+        paying twice (confirmed by tracing predict_proba: with no cache,
+        transform(mode="both") re-concatenates and re-encodes train+test
+        on every call). tabctx defaults it ON ("kv": fastest, most
+        memory-hungry -- the memory cost lands inside fit()'s measured
+        delta, so cache accounting and the adaptive admission gate see it
+        automatically; "repr" trades ~24x less ICL-cache memory for
+        re-running the ICL stack per predict)."""
+        import torch
+
+        self._device = device or ("cuda" if torch.cuda.is_available() else "cpu")
+        self._kv_cache = kv_cache
+        self._last_context_bytes: int | None = None
+        self._last_fit_peak_bytes: int | None = None
+        # task -> attrs of an already-loaded backbone, shared across
+        # fits. Loading is ~hundreds of MB of torch.load + H2D transfer
+        # PER FIT without this. Sharing one nn.Module across estimators
+        # is tabicl's own sanctioned pattern (see
+        # _unsupervised/unsupervised.py and _finetune/base.py, both of
+        # which do exactly this with the comment "prevents redundant
+        # torch.load() calls"). Safe here because the engine serializes
+        # every backend call behind its cache lock -- the shared module's
+        # per-call mutable state (its _cache pointer, InferenceManager
+        # config) is never touched concurrently.
+        self._shared_backbones: dict[str, dict[str, Any]] = {}
+
+    def _make_estimator(self, task: Task) -> Any:
+        if task == "classification":
+            from tabicl import TabICLClassifier
+
+            est = TabICLClassifier(device=self._device, kv_cache=self._kv_cache)
+        else:
+            from tabicl import TabICLRegressor
+
+            est = TabICLRegressor(device=self._device, kv_cache=self._kv_cache)
+
+        shared = self._shared_backbones.get(task)
+        if shared is not None:
+            for attr, value in shared.items():
+                setattr(est, attr, value)
+            # Instance attribute shadows the method: fit() calls
+            # self._load_model() and gets this no-op instead of a fresh
+            # torch.load + load_state_dict.
+            est._load_model = lambda: None
+        return est
+
+    def _stash_backbone(self, task: Task, model: Any) -> None:
+        if task in self._shared_backbones:
+            return
+        shared = {"model_": model.model_}
+        # Keep save()/pickling of estimators working: __setstate__ only
+        # rebuilds from weights when model_config_ exists (see tabicl
+        # _sklearn/base.py); copying these mirrors _finetune/base.py.
+        for attr in ("model_config_", "model_path_"):
+            if hasattr(model, attr):
+                shared[attr] = getattr(model, attr)
+        self._shared_backbones[task] = shared
+
+    def fit(self, X: ArrayLike, y: ArrayLike, task: Task) -> Any:
+        import torch
+
+        # Fresh estimator instance every call (load-bearing -- see
+        # backends/base.py), but the underlying pretrained nn.Module is
+        # shared across fits after the first (see __init__).
+        model = self._make_estimator(task)
+
+        measuring = self._device == "cuda"
+        before_bytes = torch.cuda.memory_allocated() if measuring else 0
+        if measuring:
+            torch.cuda.reset_peak_memory_stats()
+        try:
+            model.fit(X, y)
+        except torch.cuda.OutOfMemoryError as e:
+            self._last_context_bytes = None
+            self._last_fit_peak_bytes = None
+            raise BackendComputeError(f"CUDA OOM during fit(): {e}") from e
+        # Two DIFFERENT real measurements, for two different consumers --
+        # conflating them was the v0.4.0 design flaw fixed in v0.9.0:
+        # - resident delta (context_bytes_hint): what the fitted context
+        #   occupies afterward -> cache capacity/eviction accounting.
+        # - peak delta (fit_peak_bytes_hint): the transient high-water
+        #   during fit -> what ADMISSION must bound, since this is what
+        #   actually OOMs. Peak can exceed resident by orders of
+        #   magnitude (activations, ensemble intermediates).
+        # None on CPU; the engine falls back to the formula estimator.
+        if measuring:
+            after_bytes = torch.cuda.memory_allocated()
+            self._last_context_bytes = max(0, after_bytes - before_bytes)
+            self._last_fit_peak_bytes = max(
+                0, torch.cuda.max_memory_allocated() - before_bytes
+            )
+        else:
+            self._last_context_bytes = None
+            self._last_fit_peak_bytes = None
+        self._stash_backbone(task, model)
+        # Explicit even though tabicl's fit path clears internally today:
+        # a future tabicl change must not silently re-pin (see
+        # _unpin_shared_module for the OOM this prevents).
+        self._unpin_shared_module(model)
+        return model
+
+    def _unpin_shared_module(self, model: Any) -> None:
+        """Drop the shared backbone's pointer to the last-used context.
+
+        tabicl's `forward_with_cache` stores the active context's cache
+        on the MODULE (`model_._cache = cache`) and leaves it there.
+        With the backbone shared across all contexts (see __init__),
+        that pointer pins the most recently used context's multi-GB kv
+        cache even after tabctx evicts it -- found on a real A100 as
+        ~15GB that eviction "freed" in the accounting but never left the
+        device, eventually OOMing a fit the books said was safe. The
+        context's own cache lives on its estimator (model_kv_cache_), so
+        clearing the module pointer costs nothing and unpins eviction."""
+        module = getattr(model, "model_", None)
+        if module is not None and hasattr(module, "clear_cache"):
+            module.clear_cache()
+
+    def predict(
+        self, payload: Any, X_test: ArrayLike, return_proba: bool = False
+    ) -> PredictOutcome:
+        import torch
+
+        model = payload
+        try:
+            if hasattr(model, "predict_proba"):
+                if return_proba:
+                    proba = model.predict_proba(X_test)
+                    class_idx = np.argmax(proba, axis=1)
+                    classes = [str(c) for c in model.classes_]
+                    predictions = [classes[i] for i in class_idx]
+                    return PredictOutcome(
+                        predictions=predictions,
+                        probabilities=proba.tolist(),
+                        classes=classes,
+                    )
+                predictions = model.predict(X_test).tolist()
+                return PredictOutcome(predictions=predictions)
+            # Regressor: no predict_proba to derive from.
+            predictions = model.predict(X_test).tolist()
+            return PredictOutcome(predictions=predictions)
+        except torch.cuda.OutOfMemoryError as e:
+            raise BackendComputeError(f"CUDA OOM during predict(): {e}") from e
+        finally:
+            self._unpin_shared_module(model)
+
+    def context_bytes_hint(self, n_train: int, n_features: int) -> int | None:
+        del n_train, n_features
+        # Real measurement from the fit() call this is queried after (see
+        # module docstring); None on CPU or if fit() OOM'd, in which case
+        # the engine falls back to the formula-based MemoryEstimator.
+        return self._last_context_bytes
+
+    def fit_peak_bytes_hint(self) -> int | None:
+        """Transient high-water memory of the most recent fit() -- the
+        admission-relevant quantity (see fit()); None on CPU/after OOM."""
+        return self._last_fit_peak_bytes
+
+    # ---- spillover serialization (see cache/spill.py) ----------------
+
+    def dumps_payload(self, payload: Any) -> bytes:
+        """Pickle a fitted estimator for the disk spill tier WITHOUT the
+        shared pretrained backbone (hundreds of MB, identical across all
+        contexts, unpicklable anyway once _load_model is shadowed with a
+        lambda): strip the shared attributes, pickle, restore."""
+        import pickle
+
+        stripped = {}
+        for attr in ("model_", "_load_model"):
+            if attr in payload.__dict__:
+                stripped[attr] = payload.__dict__.pop(attr)
+        try:
+            return pickle.dumps(payload)
+        finally:
+            payload.__dict__.update(stripped)
+
+    def loads_payload(self, data: bytes) -> Any:
+        """Inverse of dumps_payload: unpickle and re-attach this
+        process's shared backbone (loading it first if this replica has
+        never fit this task type -- e.g. right after a restart)."""
+        import pickle
+
+        model = pickle.loads(data)
+        task: Task = (
+            "classification" if hasattr(model, "predict_proba") else "regression"
+        )
+        if task not in self._shared_backbones:
+            # Cold restore on a fresh replica: borrow a throwaway
+            # estimator's load path to populate the shared backbone.
+            probe = self._make_estimator(task)
+            probe._load_model()
+            self._stash_backbone(task, probe)
+        for attr, value in self._shared_backbones[task].items():
+            setattr(model, attr, value)
+        model._load_model = lambda: None
+        return model

tabctx/backends/tabpfn.py

@@ -0,0 +1,147 @@
+"""TabPFN backend (github.com/PriorLabs/TabPFN).
+
+The second backend behind the `TabularICLBackend` protocol -- proving
+the engine/cache/estimator stack really is backend-agnostic (the design
+claim in backends/base.py; nothing outside this module imports tabpfn).
+
+The kv-cache lesson from TabICL (see backends/tabicl.py and CHANGELOG
+0.7.0) applies verbatim here: TabPFN's default `fit_mode` is
+"fit_preprocessors", which caches training-data PREPROCESSING but still
+re-runs the transformer's training-context forward pass on every
+predict. Its equivalent of the kv cache is `fit_mode="fit_with_cache"`
+("the transformer key-value cache is also initialized, allowing for much
+faster inference on the same data at a large cost of memory" -- exactly
+the cost tabctx's memory accounting exists to price). tabctx maps its
+cache modes accordingly:
+
+    tabctx mode  ->  TabPFN fit_mode
+    "kv"             "fit_with_cache"   (fastest predicts, memory-heavy)
+    "repr"           "fit_preprocessors" (cheap contexts, slower predicts)
+    "off"            "low_memory"        (escape hatch; re-preprocesses
+                                          per predict)
+
+TabPFN enforces pretraining limits (~10k train rows, ~500 features on
+v2-series checkpoints) by raising before any meaningful GPU work; those
+surface as InvalidInputError so a multi-tenant caller gets a clean 422,
+not a 500. Unlike TabICL, TabPFN memoizes model loading internally per
+(model_path, device) via its model-cache mechanism, so there is no
+per-fit torch.load to elide here; a fresh estimator per fit() (required
+by the protocol -- fit() mutates estimator state) is already cheap.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from tabctx.errors import BackendComputeError, InvalidInputError
+from tabctx.types import ArrayLike, PredictOutcome, Task
+
+_FIT_MODES = {
+    "kv": "fit_with_cache",
+    "repr": "fit_preprocessors",
+    "off": "low_memory",
+}
+
+
+class TabPFNBackend:
+    # The exact model id callers select via the API's `model` field --
+    # named for the checkpoint the OSS package loads locally
+    # (tabpfn-v3-*-v3_default.ckpt, i.e. PriorLabs' "TabPFN-3").
+    name = "tabpfn-3"
+
+    def __init__(self, device: str | None = None, cache_mode: str = "kv") -> None:
+        import torch
+
+        if cache_mode not in _FIT_MODES:
+            raise ValueError(
+                f"cache_mode must be one of {sorted(_FIT_MODES)}, got {cache_mode!r}"
+            )
+        self._device = device or ("cuda" if torch.cuda.is_available() else "cpu")
+        self._fit_mode = _FIT_MODES[cache_mode]
+        self._last_context_bytes: int | None = None
+        self._last_fit_peak_bytes: int | None = None
+
+    def _make_estimator(self, task: Task) -> Any:
+        if task == "classification":
+            from tabpfn import TabPFNClassifier
+
+            return TabPFNClassifier(device=self._device, fit_mode=self._fit_mode)
+        from tabpfn import TabPFNRegressor
+
+        return TabPFNRegressor(device=self._device, fit_mode=self._fit_mode)
+
+    def fit(self, X: ArrayLike, y: ArrayLike, task: Task) -> Any:
+        import torch
+
+        model = self._make_estimator(task)
+        measuring = self._device == "cuda"
+        before_bytes = torch.cuda.memory_allocated() if measuring else 0
+        if measuring:
+            torch.cuda.reset_peak_memory_stats()
+        try:
+            model.fit(np.asarray(X, dtype=float), np.asarray(y))
+        except torch.cuda.OutOfMemoryError as e:
+            self._last_context_bytes = None
+            self._last_fit_peak_bytes = None
+            raise BackendComputeError(f"CUDA OOM during fit(): {e}") from e
+        except ValueError as e:
+            # TabPFN's own input gate (pretraining limits: too many rows,
+            # features, or classes) raises before meaningful GPU work; a
+            # caller's oversized table is bad input, not a server fault.
+            self._last_context_bytes = None
+            raise InvalidInputError(f"tabpfn rejected the training table: {e}") from e
+        # Resident vs peak: two different consumers -- see
+        # backends/tabicl.py fit() for the full rationale.
+        if measuring:
+            self._last_context_bytes = max(
+                0, torch.cuda.memory_allocated() - before_bytes
+            )
+            self._last_fit_peak_bytes = max(
+                0, torch.cuda.max_memory_allocated() - before_bytes
+            )
+        else:
+            self._last_context_bytes = None
+            self._last_fit_peak_bytes = None
+        return model
+
+    def predict(
+        self, payload: Any, X_test: ArrayLike, return_proba: bool = False
+    ) -> PredictOutcome:
+        import torch
+
+        model = payload
+        X_arr = np.asarray(X_test, dtype=float)
+        try:
+            if hasattr(model, "predict_proba"):
+                # Single pass regardless of return_proba (protocol
+                # requirement): derive labels from probabilities.
+                proba = model.predict_proba(X_arr)
+                class_idx = np.argmax(proba, axis=1)
+                classes = [str(c) for c in model.classes_]
+                predictions = [classes[i] for i in class_idx]
+                if return_proba:
+                    return PredictOutcome(
+                        predictions=predictions,
+                        probabilities=proba.tolist(),
+                        classes=classes,
+                    )
+                return PredictOutcome(predictions=predictions)
+            return PredictOutcome(predictions=model.predict(X_arr).tolist())
+        except torch.cuda.OutOfMemoryError as e:
+            raise BackendComputeError(f"CUDA OOM during predict(): {e}") from e
+
+    def context_bytes_hint(self, n_train: int, n_features: int) -> int | None:
+        del n_train, n_features
+        # Real measurement from the fit() this is queried after; None on
+        # CPU, where the engine falls back to its MemoryEstimator. NOTE:
+        # that estimator's static calibration is TabICL-on-A100 data --
+        # treat capacity numbers for TabPFN deployments as provisional
+        # until real fits accumulate in the AdaptiveMemoryEstimator.
+        return self._last_context_bytes
+
+    def fit_peak_bytes_hint(self) -> int | None:
+        """Transient high-water memory of the most recent fit() -- the
+        admission-relevant quantity; None on CPU/after OOM."""
+        return self._last_fit_peak_bytes