slide2vec 7.1.1__tar.gz → 7.1.3__tar.gz

{slide2vec-7.1.1 → slide2vec-7.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 7.1.1
+Version: 7.1.3
 Summary: Embedding of whole slide images with Foundation Models
 Author-email: Clément Grisi <clement.grisi@radboudumc.nl>
 License-Expression: Apache-2.0
@@ -11,94 +11,51 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: hs2p[asap,cucim,openslide,sam2,tifffile,vips]>=6.1.0
 Requires-Dist: omegaconf
 Requires-Dist: matplotlib
-Requires-Dist: numpy<2
 Requires-Dist: pandas
 Requires-Dist: pillow
 Requires-Dist: rich
 Requires-Dist: torch
 Requires-Dist: torchvision
-Requires-Dist: transformers
+Requires-Dist: transformers<5,>=4.47
 Requires-Dist: wandb
 Requires-Dist: einops
-Requires-Dist: timm>=1.0.3
+Requires-Dist: einops-exts
+Requires-Dist: timm>=1.0.20
 Requires-Dist: huggingface_hub
-Provides-Extra: hoptimus
-Requires-Dist: torch>=2.0; extra == "hoptimus"
-Requires-Dist: torchvision>=0.15.0; extra == "hoptimus"
-Requires-Dist: xformers>=0.0.18; extra == "hoptimus"
-Provides-Extra: virchow
-Requires-Dist: timm>=1.0.3; extra == "virchow"
-Requires-Dist: torch>=2.0; extra == "virchow"
-Provides-Extra: uni
-Requires-Dist: torch>=2.0; extra == "uni"
-Requires-Dist: timm>=1.0.3; extra == "uni"
-Requires-Dist: xformers>=0.0.18; extra == "uni"
+Requires-Dist: packaging
 Provides-Extra: prism
-Requires-Dist: transformers~=4.53.0; extra == "prism"
-Requires-Dist: torch<2.8,>=2.3; extra == "prism"
-Requires-Dist: einops==0.8.0; extra == "prism"
-Requires-Dist: environs==11.0.0; extra == "prism"
-Requires-Dist: sacremoses==0.1.1; extra == "prism"
-Requires-Dist: xformers==0.0.31; extra == "prism"
+Requires-Dist: torch>=2.3; extra == "prism"
+Requires-Dist: environs; extra == "prism"
+Requires-Dist: sacremoses; extra == "prism"
 Provides-Extra: prism2
 Requires-Dist: torch>=2.3; extra == "prism2"
-Requires-Dist: transformers==4.51.3; extra == "prism2"
-Requires-Dist: safetensors; extra == "prism2"
-Requires-Dist: einops; extra == "prism2"
-Requires-Dist: flash-attn>=2.6.3; extra == "prism2"
-Provides-Extra: hibou
-Requires-Dist: scipy~=1.8.1; extra == "hibou"
-Requires-Dist: scikit-image~=0.19.3; extra == "hibou"
-Provides-Extra: moozy
-Requires-Dist: huggingface_hub<1.0,>=0.30.0; extra == "moozy"
+Requires-Dist: transformers<5,>=4.51; extra == "prism2"
 Provides-Extra: titan
-Requires-Dist: torch==2.0.1; extra == "titan"
-Requires-Dist: timm==1.0.3; extra == "titan"
-Requires-Dist: einops==0.6.1; extra == "titan"
-Requires-Dist: einops-exts==0.0.4; extra == "titan"
-Requires-Dist: transformers==4.46.0; extra == "titan"
+Requires-Dist: einops; extra == "titan"
+Requires-Dist: einops-exts; extra == "titan"
+Requires-Dist: timm>=1.0.3; extra == "titan"
+Requires-Dist: transformers<5,>=4.46; extra == "titan"
 Provides-Extra: waiv
-Requires-Dist: transformers<6,>=5.14; extra == "waiv"
-Requires-Dist: safetensors>=0.8; extra == "waiv"
-Requires-Dist: huggingface_hub==1.25.1; extra == "waiv"
+Requires-Dist: transformers>=4.57; extra == "waiv"
+Provides-Extra: flash-attn
+Requires-Dist: flash-attn>=2.6.3; extra == "flash-attn"
+Provides-Extra: xformers
+Requires-Dist: xformers; extra == "xformers"
 Provides-Extra: fm
-Requires-Dist: omegaconf>=2.3.0; extra == "fm"
-Requires-Dist: matplotlib; extra == "fm"
-Requires-Dist: numpy<2; extra == "fm"
-Requires-Dist: pandas; extra == "fm"
-Requires-Dist: pillow; extra == "fm"
-Requires-Dist: rich; extra == "fm"
-Requires-Dist: hs2p[asap,cucim,openslide,sam2,tifffile,vips]>=6.1.0; extra == "fm"
-Requires-Dist: wandb; extra == "fm"
-Requires-Dist: torch<2.8,>=2.3; extra == "fm"
-Requires-Dist: torchvision>=0.18.0; extra == "fm"
-Requires-Dist: einops>=0.8.0; extra == "fm"
-Requires-Dist: timm>=1.0.20; extra == "fm"
-Requires-Dist: huggingface_hub<1.0,>=0.30.0; extra == "fm"
-Requires-Dist: environs; extra == "fm"
-Requires-Dist: einops-exts>=0.0.4; extra == "fm"
-Requires-Dist: transformers>=4.53; extra == "fm"
-Requires-Dist: sacremoses; extra == "fm"
-Requires-Dist: xformers>=0.0.31; extra == "fm"
-Requires-Dist: scipy>=1.8.1; extra == "fm"
-Requires-Dist: scikit-image>=0.19.3; extra == "fm"
-Requires-Dist: torchmetrics>=0.10.3; extra == "fm"
-Requires-Dist: fvcore; extra == "fm"
-Requires-Dist: iopath; extra == "fm"
-Requires-Dist: webdataset; extra == "fm"
-Requires-Dist: scikit-survival; extra == "fm"
-Requires-Dist: scikit-learn; extra == "fm"
+Requires-Dist: slide2vec[prism,prism2,titan,waiv]; extra == "fm"
 Requires-Dist: fairscale; extra == "fm"
-Requires-Dist: packaging==23.2; extra == "fm"
-Requires-Dist: ninja==1.11.1.1; extra == "fm"
-Requires-Dist: psutil<6; extra == "fm"
+Provides-Extra: cpu
+Requires-Dist: torch; extra == "cpu"
+Requires-Dist: torchvision; extra == "cpu"
+Provides-Extra: cu128
+Requires-Dist: torch; extra == "cu128"
+Requires-Dist: torchvision; extra == "cu128"
 Provides-Extra: docs
 Requires-Dist: sphinx>=8.1; extra == "docs"
 Requires-Dist: furo; extra == "docs"
@@ -131,6 +88,10 @@ pip install slide2vec
 
 Many models need additional dependencies available through `pip install "slide2vec[fm]"`. See the [model installation guide](https://clemsgrs.github.io/slide2vec/models.html#model-installation) for model-specific extras, separate environments, and upstream packages.
 
+### Reproducible model environments
+
+The repository ships a `uv.lock` file that pins every package for each extra. From a checkout, `uv sync --extra cu128 --extra fm` installs the exact locked stack (use `--extra cpu` for CPU-only PyTorch). Add `--extra flash-attn` for PRISM2 and `gigapath-slide`. The Docker image is built from the same lock; its `SLIDE2VEC_EXTRAS` build argument selects the extras, for example `--build-arg SLIDE2VEC_EXTRAS="cu128"` for the base install only.
+
 For gated models such as Virchow2, request access on the model's Hugging Face page and authenticate with `hf auth login` or an `HF_TOKEN` environment variable.
 
 ## Embed a slide

{slide2vec-7.1.1 → slide2vec-7.1.3}/README.md

@@ -15,6 +15,10 @@ pip install slide2vec
 
 Many models need additional dependencies available through `pip install "slide2vec[fm]"`. See the [model installation guide](https://clemsgrs.github.io/slide2vec/models.html#model-installation) for model-specific extras, separate environments, and upstream packages.
 
+### Reproducible model environments
+
+The repository ships a `uv.lock` file that pins every package for each extra. From a checkout, `uv sync --extra cu128 --extra fm` installs the exact locked stack (use `--extra cpu` for CPU-only PyTorch). Add `--extra flash-attn` for PRISM2 and `gigapath-slide`. The Docker image is built from the same lock; its `SLIDE2VEC_EXTRAS` build argument selects the extras, for example `--build-arg SLIDE2VEC_EXTRAS="cu128"` for the base install only.
+
 For gated models such as Virchow2, request access on the model's Hugging Face page and authenticate with `hf auth login` or an `HF_TOKEN` environment variable.
 
 ## Embed a slide

slide2vec-7.1.3/pyproject.toml

@@ -0,0 +1,264 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "slide2vec"
+version = "7.1.3"
+description = "Embedding of whole slide images with Foundation Models"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [
+    { name = "Clément Grisi", email = "clement.grisi@radboudumc.nl" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "hs2p[asap,cucim,openslide,sam2,tifffile,vips]>=6.1.0",
+    "omegaconf",
+    "matplotlib",
+    "pandas",
+    "pillow",
+    "rich",
+    "torch",
+    "torchvision",
+    # <5: Hibou's remote code imports transformers.onnx and
+    # pytorch_utils.find_pruneable_heads_and_indices, both removed in v5.
+    # >=4.47: PRISM's configuring_prism.py needs sub_configs / base_config_key.
+    "transformers>=4.47,<5",
+    "wandb",
+    "einops",
+    # TITAN remote code (used by the built-in conchv15 preset) imports it.
+    "einops-exts",
+    # first release that registers vit_base_patch16_dinov3
+    "timm>=1.0.20",
+    "huggingface_hub",
+    "packaging",
+]
+
+[project.urls]
+Homepage = "https://github.com/clemsgrs/slide2vec"
+"Bug Tracker" = "https://github.com/clemsgrs/slide2vec/issues"
+
+[project.scripts]
+slide2vec = "slide2vec.cli:entrypoint"
+
+# Rule for extras: lower bounds only. An exact or upper pin is kept only when it
+# is structural (the model's code breaks outside it); the reason sits next to
+# the pin. A model whose stack conflicts with the shared stack gets its own
+# extra and a uv conflict below. numpy<2 comes from hs2p[asap].
+[project.optional-dependencies]
+prism = [
+    # perceiver.py calls torch.nn.attention.sdpa_kernel with a list (absent in 2.2)
+    "torch>=2.3",
+    "environs",
+    "sacremoses",
+]
+prism2 = [
+    "torch>=2.3",
+    # the text (diagnostic) variant calls a Phi3Model helper whose signature
+    # changed in 4.52 and which 4.53 removed; slide2vec.encoders.models.prism2
+    # vendors it, so no upper bound. PRISM2 also imports flash_attn: add the
+    # flash-attn extra (CUDA only, so not pulled in here)
+    "transformers>=4.51,<5",
+]
+titan = [
+    "einops",
+    "einops-exts",
+    "timm>=1.0.3",
+    "transformers>=4.46,<5",
+]
+waiv = [
+    # phaet and mascaret load with zero missing keys at the pinned revisions
+    "transformers>=4.57",
+]
+# gigapath-slide needs flash-attn on GPUs with compute capability above 7
+flash-attn = [
+    "flash-attn>=2.6.3",
+]
+xformers = [
+    # optional: PRISM's PERCEIVER_MEM_EFF_ATTN path; gigapath-slide needs it
+    # on GPUs with compute capability 7 or below. Unpinned: each xformers
+    # build pins its torch.
+    "xformers",
+]
+fm = [
+    "slide2vec[prism,prism2,titan,waiv]",
+    # hard import in MUSK and gigapath-slide
+    "fairscale",
+]
+# torch wheel flavour for uv; when neither is selected torch comes from PyPI
+cpu = [
+    "torch",
+    "torchvision",
+]
+cu128 = [
+    "torch",
+    "torchvision",
+]
+docs = [
+    "sphinx>=8.1",
+    "furo",
+    "myst-parser",
+    "sphinx-copybutton",
+    "sphinx-autodoc-typehints",
+]
+testing = [
+    "pytest>=6.0",
+    "pytest-cov>=2.0",
+    "mypy>=0.910",
+    "flake8>=3.9",
+    "flake8-pyproject>=1.2.3",
+    "tox>=3.24",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=6.0",
+    "pytest-cov>=2.0",
+    "mypy>=0.910",
+    "flake8>=3.9",
+    "flake8-pyproject>=1.2.3",
+    "tox>=3.24",
+    # tests/test_encoder_plugins.py installs a plugin with `python -m pip`;
+    # uv environments ship without pip
+    "pip",
+]
+docs = [
+    "sphinx>=8.1",
+    "furo",
+    "myst-parser",
+    "sphinx-copybutton",
+    "sphinx-autodoc-typehints",
+]
+# encoder packages that are not on PyPI (musk, conch, gigapath-slide, sam2)
+models-git = [
+    "musk",
+    "conch",
+    "gigapath",
+    "sam-2",
+]
+
+[tool.uv]
+# ASAP and cucim are Linux-only. numpy<2 (from hs2p[asap]) has no wheels for
+# Python 3.13+, so the lock covers Python 3.10 to 3.12.
+environments = ["sys_platform == 'linux' and python_full_version < '3.13'"]
+# Lock-only: the cu128 index stops at torch 2.11. Hold the CPU and PyPI forks at
+# the same release so the CPU CI image tests the torch the CUDA image ships.
+# This is not part of the published metadata.
+constraint-dependencies = ["torch<2.12"]
+conflicts = [
+    [
+        { extra = "cpu" },
+        { extra = "cu128" },
+    ],
+]
+
+# flash-attn ships only an sdist whose build imports torch; declare its metadata
+# so uv can lock it without building it
+[[tool.uv.dependency-metadata]]
+name = "flash-attn"
+requires-dist = ["torch", "einops"]
+
+# flash-attn's setup.py imports torch, packaging, wheel and psutil. Build it in
+# an isolated environment that holds the same torch as the runtime environment.
+[tool.uv.extra-build-dependencies]
+flash-attn = [
+    { requirement = "torch", match-runtime = true },
+    "packaging",
+    "psutil",
+    "wheel",
+    "ninja",
+]
+
+[tool.uv.sources]
+torch = [
+    { index = "pytorch-cpu", extra = "cpu" },
+    { index = "pytorch-cu128", extra = "cu128" },
+]
+torchvision = [
+    { index = "pytorch-cpu", extra = "cpu" },
+    { index = "pytorch-cu128", extra = "cu128" },
+]
+musk = { git = "https://github.com/lilab-stanford/MUSK.git" }
+conch = { git = "https://github.com/Mahmoodlab/CONCH.git" }
+gigapath = { git = "https://github.com/prov-gigapath/prov-gigapath.git" }
+sam-2 = { git = "https://github.com/facebookresearch/sam2.git" }
+
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[[tool.uv.index]]
+name = "pytorch-cu128"
+url = "https://download.pytorch.org/whl/cu128"
+explicit = true
+
+[tool.setuptools]
+include-package-data = true
+zip-safe = false
+
+[tool.setuptools.packages.find]
+include = ["slide2vec*"]
+
+[tool.setuptools.package-data]
+slide2vec = ["py.typed", "cufile.json"]
+"slide2vec.configs" = ["*.yaml"]
+
+[tool.pytest.ini_options]
+addopts = "--cov=slide2vec -m 'not gpu_integration'"
+testpaths = [
+    "tests",
+]
+markers = [
+    "heavy: real-weight foundation-model inference on CPU; minutes per test. Excluded from the PR suite except the PRISM consistency test; run all of them through the manual heavy workflow (.github/workflows/nightly-heavy.yaml).",
+    "gpu_integration: real one-GPU versus multi-GPU parity; requires at least two visible CUDA devices. Run explicitly with `CUDA_VISIBLE_DEVICES=0,1 python -m pytest -m gpu_integration --no-cov`.",
+]
+
+[tool.mypy]
+mypy_path = "."
+check_untyped_defs = true
+disallow_any_generics = true
+ignore_missing_imports = true
+no_implicit_optional = true
+show_error_codes = true
+strict_equality = true
+warn_redundant_casts = true
+warn_return_any = true
+warn_unreachable = true
+warn_unused_configs = true
+no_implicit_reexport = true
+
+[tool.flake8]
+max-line-length = 160
+
+[tool.bumpver]
+current_version = "7.1.3"
+version_pattern = "MAJOR.MINOR.PATCH"
+commit = false
+tag = false
+push = false
+files = [
+    "pyproject.toml",
+    "slide2vec/__init__.py",
+    "docs/conf.py",
+]
+
+[tool.bumpver.file_patterns]
+"pyproject.toml" = [
+    '^current_version = "{version}"$',
+    '^version = "{version}"$',
+]
+"slide2vec/__init__.py" = [
+    '^__version__ = "{version}"$',
+]
+"docs/conf.py" = [
+    '^release = "{version}"$',
+]

{slide2vec-7.1.1 → slide2vec-7.1.3}/slide2vec/__init__.py

@@ -36,7 +36,7 @@ from slide2vec.encoders import (
 )
 
 
-__version__ = "7.1.1"
+__version__ = "7.1.3"
 
 __all__ = [
     "Model",

{slide2vec-7.1.1 → slide2vec-7.1.3}/slide2vec/encoders/__init__.py

@@ -16,6 +16,7 @@ from slide2vec.encoders.base import (
     resolve_recommended_dynamic_img_size,
     resolve_requested_output_variant,
 )
+from slide2vec.encoders.code import encoder_code
 from slide2vec.encoders.registry import (
     EncoderCapabilities,
     EncoderProviderDiagnostic,
@@ -42,6 +43,7 @@ __all__ = [
     "reshape_tokens_to_grid",
     "resolve_recommended_dynamic_img_size",
     "resolve_requested_output_variant",
+    "encoder_code",
     "encoder_registry",
     "list_encoder_provider_diagnostics",
     "normalize_patch_size",

slide2vec-7.1.3/slide2vec/encoders/code.py

@@ -0,0 +1,102 @@
+"""The code a registered encoder runs, as the feature identity records it."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import functools
+import hashlib
+from importlib import metadata as importlib_metadata
+import inspect
+import json
+from pathlib import Path
+import re
+import sys
+from typing import Any
+
+from slide2vec.encoders.registry import encoder_registry
+
+
+def encoder_code(name: str) -> dict[str, Any]:
+    """Return the code block of the registered encoder *name*.
+
+    ``object`` is the encoder class's ``module.qualname``. ``fingerprint`` is the
+    version of the non-editable installed distribution, other than slide2vec, whose
+    ``RECORD`` lists the file that defines the class; otherwise the SHA-256 of that
+    file, hashed on every call; ``None`` when there is no file (a class defined in a
+    notebook cell). ``source`` is the registry's ``source``. Reads the registry entry
+    only: the encoder is not instantiated and no weights are loaded.
+    """
+    encoder_cls = encoder_registry.require(name)
+    return {
+        "object": f"{encoder_cls.__module__}.{encoder_cls.__qualname__}",
+        "fingerprint": _fingerprint(encoder_cls),
+        "source": encoder_registry.info(name)["source"],
+    }
+
+
+def _fingerprint(encoder_cls: type) -> str | None:
+    path = _source_file(encoder_cls)
+    if path is None:
+        return None
+    distribution = _installed_distribution(encoder_cls.__module__, path)
+    return _sha256(path) if distribution is None else distribution.version
+
+
+def _installed_distribution(module: str, path: Path) -> importlib_metadata.Distribution | None:
+    """The non-editable installed distribution, other than slide2vec, whose ``RECORD``
+    lists *path*, or ``None``.
+
+    slide2vec is left out so that a built-in encoder's identity changes only when a
+    release changes its file. The distributions of a namespace package share its
+    top-level name and its install directory, so the top-level name only narrows the
+    candidates.
+    """
+    top = module.split(".", 1)[0]
+    for name in _packages_distributions(tuple(sys.path)).get(top, ()):
+        if re.sub(r"[-_.]+", "-", name).lower() == "slide2vec":
+            continue
+        try:
+            distribution = importlib_metadata.distribution(name)
+        except importlib_metadata.PackageNotFoundError:
+            continue
+        if distribution.read_text("RECORD") is None or _is_editable(distribution):
+            continue
+        try:
+            relative = path.relative_to(Path(distribution.locate_file("")).resolve())
+        except ValueError:
+            continue
+        if relative.as_posix() in {file.as_posix() for file in distribution.files or ()}:
+            return distribution
+    return None
+
+
+def _is_editable(distribution) -> bool:
+    """Whether *distribution* is an editable install, as its ``direct_url.json`` records."""
+    try:
+        payload = json.loads(distribution.read_text("direct_url.json") or "{}")
+    except json.JSONDecodeError:
+        return False
+    return isinstance(payload, dict) and bool((payload.get("dir_info") or {}).get("editable"))
+
+
+@functools.lru_cache(maxsize=1)
+def _packages_distributions(path: tuple[str, ...]) -> Mapping[str, list[str]]:
+    """Top-level package -> distributions on the import *path*, scanned once per path."""
+    return importlib_metadata.packages_distributions()
+
+
+def _source_file(encoder_cls: type) -> Path | None:
+    """The file that defines *encoder_cls*, or ``None`` (a notebook cell)."""
+    try:
+        path = Path(inspect.getsourcefile(encoder_cls) or inspect.getfile(encoder_cls))
+    except (TypeError, OSError):
+        return None
+    return path.resolve() if path.is_file() else None
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()

{slide2vec-7.1.1 → slide2vec-7.1.3}/slide2vec/encoders/models/dinov3.py

@@ -36,9 +36,7 @@ def require_timm_for_dinov3() -> None:
     if Version(timm.__version__) < Version(_MIN_TIMM_VERSION):
         raise ImportError(
             f"dinov3-vitb16 requires timm>={_MIN_TIMM_VERSION} (the DINOv3 "
-            f"architectures were added in that release); found timm=={timm.__version__}. "
-            "Note that the 'titan' extra pins timm==1.0.3 and cannot be installed "
-            "alongside dinov3-vitb16."
+            f"architectures were added in that release); found timm=={timm.__version__}."
         )
 
 

{slide2vec-7.1.1 → slide2vec-7.1.3}/slide2vec/encoders/models/moozy/loading.py

@@ -79,7 +79,7 @@ def load_moozy_inference_components(device: torch.device) -> MoozyInferenceCompo
     except Exception as exc:
         raise RuntimeError(
             "huggingface_hub is required for bundled MOOZY inference support. "
-            "Install it with: pip install 'slide2vec[moozy]'"
+            "Install it with: pip install huggingface_hub"
         ) from exc
 
     checkpoint_path = hf_hub_download(repo_id=_HF_REPO_ID, filename=_HF_CHECKPOINT)