tabcustody 0.1.0__py3-none-any.whl

tabcustody/__init__.py

@@ -0,0 +1,6 @@
+"""Package tabcustody tells whether a saved model file carries its training data, without running the file."""
+
+from tabcustody._detect import Finding
+from tabcustody._report import Report, scan_file
+
+__all__ = ["Finding", "Report", "scan_file"]

tabcustody/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from tabcustody._cli import main
+
+sys.exit(main())

tabcustody/_cli.py

@@ -0,0 +1,43 @@
+"""The `tabcustody` command: exits 1 when a file carries training data, 2 when a file cannot be read, 0 otherwise."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+
+from tabcustody._report import scan_file
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="tabcustody")
+    commands = parser.add_subparsers(dest="command", required=True)
+    scan = commands.add_parser("scan", help="tell whether model files carry their training data")
+    scan.add_argument("files", nargs="+", help="pickle, joblib or .tabpfn_fit files")
+    scan.add_argument("--json", action="store_true", help="print one JSON report per file")
+    scan.add_argument(
+        "--min-rows", type=int, default=20, help="smallest table reported (default: 20)"
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    arguments = _parser().parse_args(argv)
+    reports = [scan_file(path, min_rows=arguments.min_rows) for path in arguments.files]
+    if arguments.json:
+        print(json.dumps([report.to_dict() for report in reports], indent=2))
+    else:
+        print("\n\n".join(report.to_text() for report in reports))
+        carrying = sum(report.carries_training_data for report in reports)
+        unreadable = sum(report.error is not None for report in reports)
+        print(
+            f"\n{len(reports)} file(s) scanned: {carrying} carry training data, {unreadable} unreadable."
+        )
+    if any(report.error for report in reports):
+        return 2
+    return 1 if any(report.carries_training_data for report in reports) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tabcustody/_detect.py

@@ -0,0 +1,230 @@
+"""Finds training tables in an object tree built by the reader, without being given the training data."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from dataclasses import dataclass, replace
+from typing import Any
+
+import numpy as np
+
+from tabcustody._reader import Shell
+from tabcustody._reverse import produced, scaler_kind
+
+TRAINING_NAMES = frozenset(
+    {"X_train", "X_", "_fit_X", "X_fit_", "support_vectors_", "X_transformed_"}
+)
+
+
+@dataclass(frozen=True)
+class Finding:
+    """A 2-D numeric array judged to hold training rows; `companion` is the 1-D array with one entry per row, if any."""
+
+    path: str
+    shape: tuple[int, ...]
+    companion: str | None
+    evidence: tuple[str, ...]
+    reversible_by: str | None = None
+    owner: str | None = None
+    hint: str | None = None
+
+
+def _is_numeric(value: Any, ndim: int) -> bool:
+    return isinstance(value, np.ndarray) and value.ndim == ndim and value.dtype.kind in "iuf"
+
+
+_FRAMES = frozenset({"pandas.DataFrame", "pandas.core.frame.DataFrame"})
+_SERIES = frozenset({"pandas.Series", "pandas.core.series.Series"})
+
+
+def _manager(node: Shell) -> Any:
+    return node.attributes.get("_mgr", node.attributes.get("_data"))
+
+
+def _placement(locations: Any, count: int) -> list[int] | None:
+    if isinstance(locations, slice):
+        columns = list(range(locations.start or 0, locations.stop, locations.step or 1))
+    elif _is_numeric(locations, 1):
+        columns = [int(column) for column in locations]
+    else:
+        return None
+    return columns if len(columns) == count else None
+
+
+def _blocks(manager: Any) -> list[tuple[np.ndarray, Any]]:
+    """Pairs each block of a pickled pandas BlockManager with the columns it holds, for pandas 1 to 3 layouts."""
+    blocks: dict[int, tuple[np.ndarray, Any]] = {}
+    for _, node in _walk(manager):
+        if isinstance(node, Shell) and node.name.endswith("_unpickle_block") and node.args:
+            values, locations = node.args[0], node.args[1] if len(node.args) > 1 else None
+        elif isinstance(node, dict) and "values" in node and "mgr_locs" in node:
+            values, locations = node["values"], node["mgr_locs"]
+        else:
+            continue
+        if isinstance(values, np.ndarray):
+            blocks[id(values)] = (values, locations)
+    return list(blocks.values())
+
+
+def as_table(node: Any) -> np.ndarray | None:
+    """Returns `node` as a 2-D numeric array: a NumPy array as is, a pickled pandas DataFrame rebuilt from its numeric blocks."""
+    if _is_numeric(node, 2):
+        return node  # type: ignore[no-any-return]
+    if not (isinstance(node, Shell) and node.name in _FRAMES):
+        return None
+    columns: dict[int, np.ndarray] = {}
+    for values, locations in _blocks(_manager(node)):
+        if not _is_numeric(values, 2):
+            continue
+        placement = _placement(locations, values.shape[0])
+        if placement is None:
+            return None
+        columns.update(zip(placement, values, strict=True))
+    if not columns or len({column.shape[0] for column in columns.values()}) != 1:
+        return None
+    return np.column_stack([columns[index] for index in sorted(columns)])
+
+
+def as_vector(node: Any) -> np.ndarray | None:
+    """Returns `node` as a 1-D numeric array: a NumPy array as is, a pickled pandas Series by its values."""
+    if _is_numeric(node, 1):
+        return node  # type: ignore[no-any-return]
+    if not (isinstance(node, Shell) and node.name in _SERIES):
+        return None
+    return next((values for _, values in _walk(_manager(node)) if _is_numeric(values, 1)), None)
+
+
+def _is_lookup_grid(array: np.ndarray) -> bool:
+    """Tells a lookup table, such as QuantileTransformer's quantiles_, where every column is sorted, from rows of data."""
+    return array.shape[0] > 1 and bool(np.all(np.diff(array, axis=0) >= 0))
+
+
+def _named_children(node: Any) -> list[tuple[str, Any]]:
+    if isinstance(node, Shell):
+        return [(f".{key}", value) for key, value in node.attributes.items()] + [
+            (f"[{key!r}]", value) for key, value in node.entries.items()
+        ]
+    if isinstance(node, dict):
+        return [(f"[{key!r}]", value) for key, value in node.items()]
+    return []
+
+
+def _positional_children(node: Any) -> list[tuple[str, Any]]:
+    if isinstance(node, Shell):
+        children = [(f"[{index}]", value) for index, value in enumerate(node.items)]
+        children += [(f"<arg{index}>", value) for index, value in enumerate(node.args)]
+        if node.state is not None:
+            children.append(("<state>", node.state))
+        return children
+    if isinstance(node, list | tuple | set | frozenset):
+        return [(f"[{index}]", value) for index, value in enumerate(node)]
+    if isinstance(node, np.ndarray) and node.dtype.kind == "O":
+        return [(f"[{index}]", value) for index, value in enumerate(node.ravel())]
+    return []
+
+
+def _walk(root: Any) -> Iterator[tuple[str, Any]]:
+    seen: set[int] = set()
+    stack: list[tuple[str, Any]] = [("", root)]
+    while stack:
+        path, node = stack.pop()
+        if id(node) in seen:
+            continue
+        seen.add(id(node))
+        yield path, node
+        children = _named_children(node) + _positional_children(node)
+        stack.extend((path + suffix, child) for suffix, child in reversed(children))
+
+
+_PIPELINE_STEP = re.compile(r"^(?P<pipeline>.*)\[(?P<index>\d+)\]\[1\]$")
+
+
+def _parent(path: str) -> str:
+    return path[: max(path.rfind("."), path.rfind("["), 0)]
+
+
+def _feeds(scaler_path: str, table_path: str) -> bool:
+    """Tells whether the scaler sits beside the table's owner, or is the pipeline step right before it."""
+    owner = _parent(table_path)
+    if _parent(scaler_path) == owner:
+        return True
+    step = _PIPELINE_STEP.match(owner)
+    if step is None:
+        return False
+    return scaler_path == f"{step['pipeline']}[{int(step['index']) - 1}][1]"
+
+
+def _attach_scalers(
+    tables: list[Finding], arrays: dict[str, np.ndarray], scalers: list[tuple[str, Shell]]
+) -> list[Finding]:
+    attached = []
+    for finding in tables:
+        feeding = [
+            (path, scaler)
+            for path, scaler in scalers
+            if _feeds(path, finding.path) and produced(arrays[finding.path], scaler)
+        ]
+        if len(feeding) != 1:
+            attached.append(finding)
+            continue
+        path, scaler = feeding[0]
+        note = f"its columns carry the fingerprint of the {scaler_kind(scaler)} at {path}, which reverses it"
+        attached.append(replace(finding, reversible_by=path, evidence=(*finding.evidence, note)))
+    return attached
+
+
+def find_tables(tree: Any, min_rows: int = 20, prefix: str = "") -> list[Finding]:
+    """Returns the training tables in `tree`: 2-D numeric arrays beside a 1-D array of the same length, then their copies."""
+
+    def _clean(path: str) -> str:
+        return prefix + path.removeprefix(".")
+
+    tables: list[Finding] = []
+    arrays: dict[str, np.ndarray] = {}
+    scalers: list[tuple[str, Shell]] = []
+    for path, node in _walk(tree):
+        table = as_table(node)
+        if table is not None:
+            arrays[_clean(path)] = table
+        if scaler_kind(node) is not None:
+            scalers.append((_clean(path), node))
+        siblings = _named_children(node)
+        for name, child in siblings:
+            value = as_table(child)
+            if value is None or value.shape[0] < min_rows or _is_lookup_grid(value):
+                continue
+            companion = next(
+                (
+                    other
+                    for other, candidate in siblings
+                    if (vector := as_vector(candidate)) is not None
+                    and len(vector) == value.shape[0]
+                ),
+                None,
+            )
+            if companion is None:
+                continue
+            evidence = [f"the 1-D array {_clean(path + companion)} has one entry per row"]
+            if name.lstrip(".") in TRAINING_NAMES:
+                evidence.append(f"{name.lstrip('.')} is a name libraries use for training rows")
+            owner = node.name if isinstance(node, Shell) else None
+            tables.append(
+                Finding(
+                    _clean(path + name),
+                    value.shape,
+                    _clean(path + companion),
+                    tuple(evidence),
+                    owner=owner,
+                )
+            )
+
+    confirmed = {finding.path: finding.shape[0] for finding in tables}
+    for path, array in arrays.items():
+        if path in confirmed:
+            continue
+        source = next((other for other, rows in confirmed.items() if rows == array.shape[0]), None)
+        if source is not None:
+            copy_evidence = (f"it has as many rows as the training table {source}",)
+            tables.append(Finding(path, array.shape, None, copy_evidence))
+    return _attach_scalers(tables, arrays, scalers)

tabcustody/_reader.py

@@ -0,0 +1,280 @@
+"""Reads a pickle without running it: NumPy arrays are rebuilt, every other class or function becomes a Shell."""
+
+from __future__ import annotations
+
+import bz2
+import collections
+import gzip
+import importlib
+import io
+import lzma
+import pickle
+import zipfile
+import zlib
+from pathlib import Path
+from typing import Any, BinaryIO, ClassVar, Self, cast
+
+import numpy as np
+
+
+class Shell:
+    """An object the file asked for, kept as its dotted name, arguments and state, with none of its code run."""
+
+    dotted_name: ClassVar[str] = ""
+
+    args: tuple[Any, ...]
+    attributes: dict[str, Any]
+    state: Any
+    items: list[Any]
+    entries: dict[Any, Any]
+
+    def __new__(cls, *args: Any, **kwargs: Any) -> Self:
+        shell = object.__new__(cls)
+        shell.args = args + tuple(kwargs.items())
+        shell.attributes = {}
+        shell.state = None
+        shell.items = []
+        shell.entries = {}
+        return shell
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        pass
+
+    @property
+    def name(self) -> str:
+        return type(self).dotted_name
+
+    def __setstate__(self, state: Any) -> None:
+        if (
+            isinstance(state, tuple)
+            and len(state) == 2
+            and all(p is None or isinstance(p, dict) for p in state)
+        ):
+            for part in state:
+                self.attributes.update(part or {})
+        elif isinstance(state, dict) and all(isinstance(key, str) for key in state):
+            self.attributes.update(state)
+        else:
+            self.state = state
+
+    def append(self, item: Any) -> None:
+        self.items.append(item)
+
+    def extend(self, items: Any) -> None:
+        self.items.extend(items)
+
+    def __setitem__(self, key: Any, value: Any) -> None:
+        self.entries[key] = value
+
+    def __repr__(self) -> str:
+        return f"Shell({self.name})"
+
+
+_shell_classes: dict[str, type[Shell]] = {}
+
+
+def _shell_class(dotted_name: str) -> type[Shell]:
+    if dotted_name not in _shell_classes:
+        _shell_classes[dotted_name] = type(dotted_name, (Shell,), {"dotted_name": dotted_name})
+    return _shell_classes[dotted_name]
+
+
+def _numpy_attribute(submodule: str, name: str) -> Any:
+    try:
+        module = importlib.import_module(f"numpy._core.{submodule}")
+    except ImportError:
+        module = importlib.import_module(f"numpy.core.{submodule}")
+    return getattr(module, name)
+
+
+def _new_object(cls: Any, *args: Any) -> Any:
+    if isinstance(cls, type) and issubclass(cls, Shell):
+        return cls.__new__(cls, *args)
+    return _shell_class("copyreg.__newobj__")(cls, *args)
+
+
+def _reconstructor(cls: Any, base: Any, state: Any) -> Any:
+    shell = _new_object(cls)
+    if state is not None and isinstance(shell, Shell):
+        shell.state = state
+    return shell
+
+
+def _encode(text: Any, encoding: str = "utf-8", *rest: Any) -> Any:
+    """Stands in for `_codecs.encode`, which pickle protocol 2 uses to carry bytes; only turns text into bytes."""
+    if (
+        isinstance(text, str)
+        and isinstance(encoding, str)
+        and encoding.lower() in ("latin1", "latin-1", "utf-8")
+    ):
+        return text.encode(encoding)
+    return _shell_class("_codecs.encode")(text, encoding, *rest)
+
+
+_NUMPY_BUILDERS = {
+    ("multiarray", "_reconstruct"),
+    ("multiarray", "scalar"),
+    ("numeric", "_frombuffer"),
+}
+
+_SAFE_GLOBALS: dict[tuple[str, str], Any] = {
+    ("builtins", "set"): set,
+    ("builtins", "frozenset"): frozenset,
+    ("builtins", "bytearray"): bytearray,
+    ("builtins", "complex"): complex,
+    ("builtins", "slice"): slice,
+    ("builtins", "object"): object,
+    ("builtins", "list"): list,
+    ("builtins", "dict"): dict,
+    ("builtins", "tuple"): tuple,
+    ("collections", "OrderedDict"): collections.OrderedDict,
+    ("copyreg", "_reconstructor"): _reconstructor,
+    ("copyreg", "__newobj__"): _new_object,
+    ("_codecs", "encode"): _encode,
+    ("numpy", "ndarray"): np.ndarray,
+    ("numpy", "dtype"): np.dtype,
+}
+
+
+class UnreadableFileError(Exception):
+    """Raised when a file is neither a pickle, a joblib file nor a zip archive of them, or is malformed."""
+
+
+_JOBLIB_WRAPPER = "joblib.numpy_pickle.NumpyArrayWrapper"
+
+
+def _read_exactly(stream: BinaryIO, size: int) -> bytes:
+    chunks, remaining = [], size
+    while remaining:
+        chunk = stream.read(remaining)
+        if not chunk:
+            raise UnreadableFileError("the file ends inside an array")
+        chunks.append(chunk)
+        remaining -= len(chunk)
+    return b"".join(chunks)
+
+
+class _Unpickler(pickle._Unpickler):
+    # The C unpickler reads ahead, which would swallow the raw array bytes joblib writes between opcodes.
+
+    dispatch: ClassVar[dict[int, Any]] = dict(pickle._Unpickler.dispatch)
+    stack: list[Any]
+
+    def __init__(self, stream: BinaryIO) -> None:
+        super().__init__(stream)
+        self._stream = stream
+
+    def find_class(self, module: str, name: str) -> Any:
+        if (module, name) in _SAFE_GLOBALS:
+            return _SAFE_GLOBALS[(module, name)]
+        prefix, _, submodule = module.rpartition(".")
+        if prefix in ("numpy.core", "numpy._core") and (submodule, name) in _NUMPY_BUILDERS:
+            return _numpy_attribute(submodule, name)
+        if module.startswith("numpy.dtypes") and name.endswith("DType"):
+            return getattr(importlib.import_module("numpy.dtypes"), name)
+        return _shell_class(f"{module}.{name}")
+
+    def persistent_load(self, pid: Any) -> Shell:
+        return _shell_class("pickle.persistent_id")(pid)
+
+    def _load_build(self) -> None:
+        pickle._Unpickler.load_build(self)  # type: ignore[attr-defined]
+        top = self.stack[-1]
+        if isinstance(top, Shell) and top.name == _JOBLIB_WRAPPER:
+            self.stack[-1] = self._read_joblib_array(top)
+
+    def _read_joblib_array(self, wrapper: Shell) -> np.ndarray:
+        """Reads the array joblib writes right after its NumpyArrayWrapper, as joblib 1.6 `read_array` does."""
+        try:
+            dtype = np.dtype(wrapper.attributes["dtype"])
+            shape = tuple(int(size) for size in wrapper.attributes["shape"])
+        except (KeyError, TypeError, ValueError) as error:
+            raise UnreadableFileError(f"malformed joblib array header: {error}") from error
+        if dtype.hasobject:
+            loaded = _Unpickler(self._stream).load()
+            return np.asarray(loaded, dtype=object)
+        if wrapper.attributes.get("numpy_array_alignment_bytes") is not None:
+            padding = int.from_bytes(_read_exactly(self._stream, 1), "little")
+            _read_exactly(self._stream, padding)
+        count = int(np.prod(shape, dtype=np.int64)) if shape else 1
+        array = np.frombuffer(
+            _read_exactly(self._stream, count * dtype.itemsize), dtype=dtype, count=count
+        )
+        if wrapper.attributes.get("order") == "F":
+            return np.asarray(array.reshape(shape[::-1]).transpose())
+        return np.asarray(array.reshape(shape))
+
+
+_Unpickler.dispatch[pickle.BUILD[0]] = _Unpickler._load_build
+
+
+class _ZlibReader(io.RawIOBase):
+    """The zlib stream joblib writes with `compress=` an integer, decompressed as it is read."""
+
+    def __init__(self, stream: BinaryIO) -> None:
+        self._stream = stream
+        self._decompressor = zlib.decompressobj()
+        self._pending = b""
+
+    def readable(self) -> bool:
+        return True
+
+    def readinto(self, buffer: Any) -> int:
+        while not self._pending and not self._decompressor.eof:
+            compressed = self._stream.read(1 << 16)
+            if not compressed:
+                break
+            self._pending = self._decompressor.decompress(compressed)
+        size = min(len(buffer), len(self._pending))
+        buffer[:size] = self._pending[:size]
+        self._pending = self._pending[size:]
+        return size
+
+
+def _decompressed(stream: BinaryIO) -> BinaryIO:
+    head = stream.peek(6)[:6] if hasattr(stream, "peek") else b""
+    if head.startswith(b"\x1f\x8b"):
+        return cast(BinaryIO, gzip.GzipFile(fileobj=stream))
+    if head.startswith(b"BZh"):
+        return cast(BinaryIO, bz2.BZ2File(stream))
+    if head.startswith((b"\xfd7zXZ\x00", b"]\x00\x00")):
+        return cast(BinaryIO, lzma.LZMAFile(stream))
+    if head[:1] == b"\x78":
+        return cast(BinaryIO, io.BufferedReader(_ZlibReader(stream)))
+    return stream
+
+
+def _load(stream: BinaryIO) -> Any:
+    try:
+        return _Unpickler(_decompressed(stream)).load()
+    except UnreadableFileError:
+        raise
+    except Exception as error:
+        raise UnreadableFileError(
+            f"not a readable pickle or joblib file: {type(error).__name__}: {error}"
+        ) from error
+
+
+def read_bytes(data: bytes) -> Any:
+    """Returns the object tree of a pickle, rebuilding NumPy arrays and turning every other class into a Shell."""
+    return _load(io.BufferedReader(io.BytesIO(data)))
+
+
+def read(path: str | Path) -> Any:
+    """Returns the object tree of the pickle or joblib file at `path`; nothing it names is imported or called, NumPy array builders aside."""
+    with Path(path).open("rb") as stream:
+        return _load(stream)
+
+
+def read_members(path: str | Path) -> tuple[str, list[tuple[str | None, Any]]]:
+    """Returns the file's format and the object tree of each pickle or joblib member; a lone file has one member named None."""
+    if zipfile.is_zipfile(path):
+        trees: list[tuple[str | None, Any]] = []
+        with zipfile.ZipFile(path) as archive:
+            for member in archive.infolist():
+                if member.is_dir() or member.filename.endswith(".json"):
+                    continue
+                with archive.open(member) as stream:
+                    trees.append((member.filename, _load(stream)))  # type: ignore[arg-type]
+        return "zip", trees
+    return "pickle", [(None, read(path))]

tabcustody/_report.py

@@ -0,0 +1,125 @@
+"""Turns the findings of a file into a report that names paths, shapes and fixes, and never a value of the table."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Any
+
+from tabcustody._detect import Finding, find_tables
+from tabcustody._reader import UnreadableFileError, read_members
+
+_KEEP_CONFIDENTIAL = "keep this file as confidential as the data it was fitted on."
+_INSTANCE_BASED = f"An instance-based model keeps training rows by design: {_KEEP_CONFIDENTIAL}"
+
+HINTS = (
+    (
+        "tabicl.",
+        (
+            "TabICL can save without the rows: fit with kv_cache=True, then call "
+            "save(path, save_training_data=False); the file then keeps the model's key-value cache instead."
+        ),
+    ),
+    (
+        "tabpfn.",
+        (
+            "TabPFN keeps the rows in its default fit mode. Releases that include PriorLabs/TabPFN "
+            "pull request 1323 drop them once the caches are built when the model is fitted with "
+            f"fit_mode='fit_with_cache'; otherwise {_KEEP_CONFIDENTIAL}"
+        ),
+    ),
+    ("tabdpt.", f"TabDPT has no save function and keeps its training rows: {_KEEP_CONFIDENTIAL}"),
+    ("sklearn.neighbors.", _INSTANCE_BASED),
+    ("sklearn.svm.", _INSTANCE_BASED),
+)
+
+
+def _hint(owner: str | None) -> str | None:
+    if owner is None:
+        return None
+    return next((hint for prefix, hint in HINTS if owner.startswith(prefix)), None)
+
+
+@dataclass(frozen=True)
+class Report:
+    """What one file carries: its findings, or the reason it could not be read."""
+
+    path: str
+    format: str
+    findings: tuple[Finding, ...]
+    error: str | None = None
+
+    @property
+    def carries_training_data(self) -> bool:
+        return bool(self.findings)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "path": self.path,
+            "format": self.format,
+            "carries_training_data": self.carries_training_data,
+            "error": self.error,
+            "findings": [
+                {
+                    "path": finding.path,
+                    "rows": finding.shape[0],
+                    "columns": finding.shape[1],
+                    "kind": "training table" if finding.companion else "copy",
+                    "companion": finding.companion,
+                    "reversible_by": finding.reversible_by,
+                    "owner": finding.owner,
+                    "evidence": list(finding.evidence),
+                    "hint": finding.hint,
+                }
+                for finding in self.findings
+            ],
+        }
+
+    def to_text(self) -> str:
+        lines = [f"{self.path} ({self.format})"]
+        if self.error:
+            lines.append(f"  unreadable: {self.error}")
+        elif not self.findings:
+            lines.append("  no training table found")
+        for group in _alike(self.findings):
+            first, kind = group[0], "training table" if group[0].companion else "copy"
+            rows = " or ".join(sorted({str(f.shape[0]) for f in group}, key=int, reverse=True))
+            columns = " or ".join(sorted({str(f.shape[1]) for f in group}, key=int, reverse=True))
+            count = f"  ({len(group)} alike)" if len(group) > 1 else ""
+            path = _pattern(first.path) if len(group) > 1 else first.path
+            lines.append(f"  {kind}  {path}  {rows} rows x {columns} columns{count}")
+            evidence = [_pattern(reason) if len(group) > 1 else reason for reason in first.evidence]
+            lines.extend(f"    why: {reason}" for reason in evidence)
+            if first.hint:
+                lines.append(f"    fix: {first.hint}")
+        return "\n".join(lines)
+
+
+_INDEX = re.compile(r"\[\d+\]")
+
+
+def _pattern(text: str) -> str:
+    return _INDEX.sub("[*]", text)
+
+
+def _alike(findings: tuple[Finding, ...]) -> list[list[Finding]]:
+    groups: dict[tuple[str, bool, str | None], list[Finding]] = {}
+    for finding in findings:
+        key = (_pattern(finding.path), finding.companion is None, finding.hint)
+        groups.setdefault(key, []).append(finding)
+    return list(groups.values())
+
+
+def scan_file(path: str | Path, min_rows: int = 20) -> Report:
+    """Scans one model file without running it; a file it cannot read gives a Report whose `error` says why."""
+    try:
+        file_format, members = read_members(path)
+    except (UnreadableFileError, OSError) as error:
+        return Report(str(path), "unknown", (), str(error))
+    findings = tuple(
+        replace(finding, hint=_hint(finding.owner))
+        for member, tree in members
+        for finding in find_tables(tree, min_rows=min_rows, prefix=f"{member}:" if member else "")
+    )
+    return Report(str(path), file_format, findings)

tabcustody/_reverse.py

@@ -0,0 +1,72 @@
+"""Reverses scikit-learn scalers from their stored arrays alone, without importing scikit-learn."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from tabcustody._reader import Shell
+
+SCALERS = ("StandardScaler", "MinMaxScaler", "RobustScaler")
+TOLERANCE = 1e-6
+
+
+def scaler_kind(node: Any) -> str | None:
+    """Returns the scaler class name when `node` is the Shell of a scikit-learn scaler this module can reverse."""
+    if not isinstance(node, Shell) or not node.name.startswith("sklearn.preprocessing"):
+        return None
+    kind = node.name.rsplit(".", 1)[-1]
+    return kind if kind in SCALERS else None
+
+
+def _vector(scaler: Shell, name: str, width: int, default: float) -> np.ndarray:
+    value = scaler.attributes.get(name)
+    return np.full(width, default) if value is None else np.asarray(value, dtype=float)
+
+
+def _width(scaler: Shell) -> int | None:
+    scale = scaler.attributes.get("scale_")
+    return None if scale is None else int(np.asarray(scale).shape[0])
+
+
+def reverse(table: np.ndarray, scaler: Shell) -> np.ndarray:
+    """Returns the rows `scaler` was given before it produced `table`; raises ValueError for a scaler it cannot reverse."""
+    kind, width = scaler_kind(scaler), table.shape[1]
+    scale = _vector(scaler, "scale_", width, 1.0)
+    if kind == "StandardScaler":
+        return np.asarray(table * scale + _vector(scaler, "mean_", width, 0.0), dtype=float)
+    if kind == "MinMaxScaler":
+        return np.asarray((table - _vector(scaler, "min_", width, 0.0)) / scale, dtype=float)
+    if kind == "RobustScaler":
+        return np.asarray(table * scale + _vector(scaler, "center_", width, 0.0), dtype=float)
+    raise ValueError(f"no reversal for {scaler.name}")
+
+
+def produced(table: np.ndarray, scaler: Shell) -> bool:
+    """Tells whether `table` carries the fingerprint `scaler` leaves on the very rows it was fitted on."""
+    kind = scaler_kind(scaler)
+    if kind is None or _width(scaler) != table.shape[1] or table.shape[0] < 2:
+        return False
+    varying = np.ptp(table, axis=0) > TOLERANCE
+    if not varying.any():
+        return False
+    columns = table[:, varying]
+    if kind == "StandardScaler":
+        centred = scaler.attributes.get("mean_") is None or np.allclose(
+            columns.mean(axis=0), 0, atol=TOLERANCE
+        )
+        return centred and np.allclose(columns.std(axis=0), 1, atol=TOLERANCE)
+    if kind == "MinMaxScaler":
+        low, high = scaler.attributes.get("feature_range", (0, 1))
+        return np.allclose(columns.min(axis=0), low, atol=TOLERANCE) and np.allclose(
+            columns.max(axis=0), high, atol=TOLERANCE
+        )
+    centred = scaler.attributes.get("center_") is None or np.allclose(
+        np.median(columns, axis=0), 0, atol=TOLERANCE
+    )
+    if scaler.attributes.get("scale_") is None:
+        return centred
+    low, high = scaler.attributes.get("quantile_range", (25.0, 75.0))
+    spread = np.percentile(columns, high, axis=0) - np.percentile(columns, low, axis=0)
+    return centred and np.allclose(spread, 1, atol=TOLERANCE)

tabcustody-0.1.0.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.5
+Name: tabcustody
+Version: 0.1.0
+Summary: With in-context tabular models (TabPFN, TabICL, TabDPT), the saved model file is your training data. tabcustody detects it.
+Project-URL: Homepage, https://github.com/jrachid/tabcustody
+Project-URL: Repository, https://github.com/jrachid/tabcustody
+Project-URL: Issues, https://github.com/jrachid/tabcustody/issues
+Author: Rachid Jeffali
+License-Expression: MIT
+License-File: LICENSE
+Keywords: data-leakage,gdpr,in-context-learning,mlops,pickle,privacy,tabdpt,tabicl,tabpfn,tabular-foundation-models
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Description-Content-Type: text/markdown
+
+# tabcustody
+
+> With in-context tabular models, the model file **is** your training data. tabcustody proves it on your files, then lets you deploy, erase and trace without exposing that data.
+
+**Status: pre-alpha.** Version 0.1 ships the scanner: it tells whether a model file carries its training data, without running the file. Separating, erasing and tracing come next.
+
+## Quick start
+
+```bash
+pip install tabcustody
+tabcustody scan model.pkl other.joblib fitted.tabpfn_fit
+```
+
+The command reads pickle files, joblib files (plain or compressed with zlib, gzip, bz2 or xz) and zip archives of them such as TabPFN's `.tabpfn_fit`. It exits with 1 when a file carries training data, 2 when a file cannot be read, 0 otherwise, so it can gate a CI job; `--json` prints one report per file.
+
+From Python, with scikit-learn installed:
+
+```python
+import pickle
+
+from sklearn.datasets import make_classification
+from sklearn.neighbors import KNeighborsClassifier
+
+from tabcustody import scan_file
+
+X, y = make_classification(n_samples=200, n_features=4, random_state=0)
+with open("model.pkl", "wb") as file:
+    pickle.dump(KNeighborsClassifier().fit(X, y), file)
+
+report = scan_file("model.pkl")
+print(report.to_text())
+assert report.carries_training_data
+```
+
+```
+model.pkl (pickle)
+  training table  _fit_X  200 rows x 4 columns
+    why: the 1-D array _y has one entry per row
+    why: _fit_X is a name libraries use for training rows
+    fix: An instance-based model keeps training rows by design: keep this file as confidential as the data it was fitted on.
+```
+
+On a TabPFN archive the report names the rows of every ensemble member, and on a TabICL file it names the save option that leaves them out:
+
+```
+fitted.tabpfn_fit (zip)
+  training table  executor_state.joblib:ensemble_members[*].X_train  300 rows x 10 or 4 columns  (8 alike)
+    why: the 1-D array executor_state.joblib:ensemble_members[*].y_train has one entry per row
+    why: X_train is a name libraries use for training rows
+    fix: TabPFN keeps the rows in its default fit mode. Releases that include PriorLabs/TabPFN pull request 1323 drop them once the caches are built when the model is fitted with fit_mode='fit_with_cache'; otherwise keep this file as confidential as the data it was fitted on.
+```
+
+The scanner never unpickles the file the usual way: only NumPy arrays and plain containers are rebuilt, every other class becomes an inert placeholder, and no library the file names is imported. The report gives paths, shapes and evidence, never a value of the table.
+
+## The problem, measured
+
+A classic model such as XGBoost learns rules from its training data, then forgets the data: the saved file holds split thresholds, nothing else. The new tabular foundation models — TabPFN, TabICL, TabDPT — work differently. They predict by reading the training table again at every prediction, the way a language model reads its prompt. So a fitted model keeps the table, and saving the model saves the table.
+
+The same 300 synthetic customers, each model fitted then saved with `pickle`, and only the saved file inspected afterwards:
+
+| Model | Saved file | Incomes found verbatim | Incomes rebuilt from the file alone |
+|---|---|---|---|
+| XGBoost 3.4.1 (control) | 0.1 MB | 0 / 300 | 0 / 300 |
+| TabICL 2.2.0 | < 0.1 MB | 300 / 300 | 300 / 300 |
+| TabPFN v2 (tabpfn 9.0.0) | 29.2 MB | 300 / 300 | 300 / 300 |
+| TabPFN v3.5, the default weights (tabpfn 9.0.0) | 876.3 MB | 300 / 300 | 300 / 300 |
+| TabDPT 1.3.1 | 252.5 MB | 11 / 300 | 300 / 300 |
+
+Measured on 28 September 2026 by [`comparisons/leak.py`](comparisons/leak.py), which anyone can rerun with the pinned versions of [`comparisons/pyproject.toml`](comparisons/pyproject.toml).
+
+TabDPT is the instructive row. It stores the table standardised — an income of 38,693.02 becomes -0.058 — so searching the file for known values finds almost nothing, and a manual check concludes the file is clean. But the scaler that standardised the table is saved in the same file, and calling it in reverse rebuilds every income to the cent.
+
+Nothing here is a bug in these libraries: keeping the table is how in-context learning works. The risk is in the habits around model files. Teams have treated them as harmless build artefacts for a decade — committed to Git, copied to buckets, sent to vendors — and with these models each of those copies is a copy of the customer table.
+
+## What the libraries' own saves keep
+
+The table above uses `pickle`. Each library's own save function tells the same story by default, and one of them offers a way out:
+
+| Save | Incomes found verbatim | Largest prediction gap after reload |
+|---|---|---|
+| TabPFN v2 `save_fit_state` (tabpfn 9.0.0) | 300 / 300 | n/a |
+| TabICL 2.2.0 `save(save_training_data=True)`, `kv_cache=False` | 300 / 300 | 0 |
+| TabICL 2.2.0 `save(save_training_data=False)`, `kv_cache=True` | 4 / 300 | 0 |
+
+Measured by [`comparisons/builtin_saves.py`](comparisons/builtin_saves.py).
+
+TabICL's documentation presents `save_training_data=False` as giving "better data privacy": the file keeps the model's cached key-value projections of the table instead of the table, and predictions after reload are unchanged. It works only if the model was fitted with `kv_cache=True`, it is off by default, 4 incomes still appear verbatim, and whether the table can be rebuilt from the cache has not been measured here. TabPFN's `.tabpfn_fit` archive leaves out the foundation model's weights but keeps the table, and TabDPT offers no option to drop it. TabPFN is about to follow TabICL: [pull request 1323](https://github.com/PriorLabs/TabPFN/pull/1323), merged on 28 September 2026 for memory reasons and not yet released, drops each ensemble member's table once its cache is built in `fit_mode="fit_with_cache"`. Measured on TabPFN's main branch at commit `dbba40314b`, with TabPFN v2 weights: the default mode keeps 300 of 300 incomes in the `.tabpfn_fit` archive, `fit_with_cache` keeps 4, and predictions after reload are unchanged in both.
+
+## What existing tools see
+
+The closest prior work is [SACRO-ML](https://github.com/AI-SDC/SACRO-ML), which checks models leaving trusted research environments. Its instance-based attack detects models that store their training rows — SVMs and k-nearest-neighbours, the classic cases — by comparing the stored instances with the training data you give it. On its own ground it works, and on anything else it reports no risk:
+
+| Model | SACRO-ML 2.0.1 verdict | Rows it matched |
+|---|---|---|
+| KNeighborsClassifier (scikit-learn 1.9.1) | leakage confirmed | 300 / 300 |
+| TabICL 2.2.0 | not instance-based, no data leakage risk | 0 / 300 |
+
+Same 300 customers as above, measured by [`comparisons/sacroml_check.py`](comparisons/sacroml_check.py). The TabICL file it clears is one from which every income is rebuilt.
+
+Other tools look at model files for a different reason, or skip them:
+
+- **Pickle security scanners** — [fickling](https://github.com/trailofbits/fickling), [picklescan](https://github.com/mmaitre314/picklescan), [modelscan](https://github.com/protectai/modelscan), the [Hugging Face pickle scan](https://huggingface.co/docs/hub/security-pickle) — look for code that runs when the file loads. Arrays are data, so they are not their concern.
+- **Model auditors** — [ModelAudit](https://github.com/promptfoo/modelaudit) also searches weights for embedded credentials such as API keys, not for rows of a dataset.
+- **Cloud data-loss prevention** — [Amazon Macie](https://docs.aws.amazon.com/macie/latest/user/discovery-supported-storage.html) classifies pickle and NumPy files as objects it cannot analyse, so personal data inside them goes unreported.
+
+tabcustody discovers the table without being handed the training data, covers the in-context tabular models, and tells when values stored behind a scaler can be rebuilt, as with TabDPT.
+
+## Guarantees and the tests that prove them
+
+| Guarantee | Test |
+|---|---|
+| Reading a file runs none of its code, joblib object arrays included | `test_safety.py::test_a_pickle_that_runs_a_command_on_load_runs_nothing`, `test_formats.py::test_an_object_array_inside_a_joblib_file_is_read_without_running_it` |
+| Scanning imports no model library | `test_safety.py::test_scanning_imports_neither_torch_nor_xgboost` |
+| The training table of TabICL, TabPFN v2, TabPFN v3.5 and TabDPT is found | `test_detection.py::test_the_training_table_of_each_in_context_model_is_found` (TabPFN and TabDPT files are too large to version: marked `integration`), `test_formats.py::test_a_tabpfn_fit_archive_is_scanned_member_by_member` |
+| Instance-based models (k-nearest-neighbours, SVM) are reported | `test_detection.py::test_instance_based_models_are_reported_like_sacroml_does` |
+| No finding on XGBoost, LightGBM, logistic regression, random forest, gradient boosting, a 100×100 MLP or a QuantileTransformer pipeline | `test_detection.py::test_classic_models_report_no_table`, `::test_a_square_weight_matrix_next_to_its_bias_is_not_a_table`, `::test_a_quantile_grid_beside_its_levels_is_not_a_table` |
+| A table kept as a pandas DataFrame, pickled by pandas 2 or 3, is found and rebuilt in its column order | `test_detection.py::test_a_table_kept_as_a_pandas_dataframe_is_found`, `::test_a_dataframe_is_rebuilt_column_by_column_in_its_own_order` |
+| A table stored standardised is declared reversible, and reversing gives the exact rows | `test_reversal.py::test_a_standardised_table_is_rebuilt_from_the_scaler_saved_beside_it`, `::test_a_scaled_pipeline_table_is_rebuilt_from_the_scaler_step` |
+| A scaler that does not feed the table is never credited | `test_reversal.py::test_a_scaler_nested_inside_another_transformer_is_not_credited`, `::test_a_table_stored_as_is_is_not_said_to_be_reversible` |
+| The report never prints a value of the table | `test_report.py::test_the_report_never_prints_a_value_of_the_table` |
+| joblib files, compressed or not, read like pickles | `test_formats.py::test_a_joblib_file_is_scanned_like_a_pickle`, `::test_compressed_joblib_files_are_read` |
+| The command exits 1 on a file that carries training data | `test_cli.py::test_the_command_exits_non_zero_when_a_table_is_found` |
+
+## Limits
+
+- **A table is recognised by its target.** The scanner looks for a 2-D numeric array beside a 1-D array with one entry per row. Rows kept without a target, or tables under 20 rows (`--min-rows`), are not reported.
+- **A one-column table stored in sorted order** is taken for a lookup grid, such as QuantileTransformer's quantiles, and not reported.
+- **Only numeric columns are read.** Text and category columns of a DataFrame stay in the file but are not part of the reported shape.
+- **Reversal covers scikit-learn's StandardScaler, MinMaxScaler and RobustScaler**, when the scaler sits beside the table or is the pipeline step right before it. Tables behind other transforms are still reported; they are not called reversible.
+- **Formats.** Not read: lz4-compressed joblib, safetensors, ONNX, `torch.save` archives. PyTorch tensors inside a pickle stay opaque placeholders.
+- **Memory.** The whole object tree is loaded: scanning the 836 MB TabPFN v3.5 pickle peaks at about the size of the file.
+
+## What comes next
+
+1. **Detect** — shipped in 0.1.
+2. **Separate.** Save the model without its table, and supply the table at prediction time from a place you control.
+3. **Erase.** Find a person's rows, remove them, refit, and keep a record that proves it — an erasure request under GDPR article 17 becomes a routine operation with these models, where classic models would need retraining.
+4. **Trace and verify.** Know which exact table was in place for any past prediction, and check that production predicts like development.
+
+Each step ships on its own, with its guarantees backed by named tests.
+
+## What tabcustody does not claim
+
+- **Leakage through predictions.** Whether an attacker can infer training rows from a model's answers is a research question, studied in [arXiv 2606.26021](https://arxiv.org/abs/2606.26021) and [arXiv 2606.31474](https://arxiv.org/abs/2606.31474). tabcustody is about the far plainer leak above: the rows are in the file.
+- **That users are already reporting this.** As of 28 September 2026 no public issue describes it. These models are young; tabcustody is built ahead of the moment teams put them in production at scale.
+- **Models not in the table.** TabPFN 2.5, 2.6 and 3, and AutoGluon's Mitra, are not measured yet. They join the table when `comparisons/leak.py` has run on them.
+
+## License
+
+MIT

tabcustody-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+tabcustody/__init__.py,sha256=m7ZB6xX0mCoRmM2fopiE5oqDo3506yUozcNd0_JrcLo,246
+tabcustody/__main__.py,sha256=LnPOD1Is8i6ksVrXIgPiV-KY7d1CHqKL4pg8Kcqx_PA,63
+tabcustody/_cli.py,sha256=_sSL7-epC8p-EVNs0v0Mbku_cukh6RWLC-R5Xcob3kc,1690
+tabcustody/_detect.py,sha256=fX59ha0HsiRMy9ORdhfnmizeu_NNQjXvB9rucVPi1w8,8936
+tabcustody/_reader.py,sha256=56GOZcP5zZrs6mmCFoUxk5mq-scsZEl4QSlFjJ6bPSs,9838
+tabcustody/_report.py,sha256=3wK5cnUhsVQg8vUtJ0MalnBnA7ZvUcZhFfQY8pl5Mpc,4765
+tabcustody/_reverse.py,sha256=8O1G8kyV47kLYbQkAaC3OR_BJCVxFSRNxMh9diAaU4k,3081
+tabcustody/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tabcustody-0.1.0.dist-info/METADATA,sha256=37z6BVOB34QdhZbSUl49CiWSiddhThyNICEfHGEkI3A,13639
+tabcustody-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+tabcustody-0.1.0.dist-info/entry_points.txt,sha256=sTjk7jJLXuuSm3lnnsasT0CW0ZpWPJiC7URgUcPBucY,52
+tabcustody-0.1.0.dist-info/licenses/LICENSE,sha256=eCHmfhsEWXn7Hlw1UZuEJpp7JTf6UTYRnl1aqZVW_g0,1071
+tabcustody-0.1.0.dist-info/RECORD,,

tabcustody-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

tabcustody-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tabcustody = tabcustody._cli:main

tabcustody-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rachid Jeffali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.