slide2vec 5.8.1__tar.gz → 5.9.0__tar.gz

{slide2vec-5.8.1 → slide2vec-5.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 5.8.1
+Version: 5.9.0
 Summary: Embedding of whole slide images with Foundation Models
 Author-email: Clément Grisi <clement.grisi@radboudumc.nl>
 License-Expression: Apache-2.0
@@ -15,7 +15,7 @@ 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,vips]>=4.4.2
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=4.4.3
 Requires-Dist: omegaconf
 Requires-Dist: matplotlib
 Requires-Dist: numpy<2
@@ -75,7 +75,7 @@ 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,vips]>=4.4.2; extra == "fm"
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=4.4.3; extra == "fm"
 Requires-Dist: wandb; extra == "fm"
 Requires-Dist: torch<2.8,>=2.3; extra == "fm"
 Requires-Dist: torchvision>=0.18.0; extra == "fm"

{slide2vec-5.8.1 → slide2vec-5.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "slide2vec"
-version = "5.8.1"
+version = "5.9.0"
 description = "Embedding of whole slide images with Foundation Models"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -21,7 +21,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "hs2p[asap,cucim,openslide,sam2,vips]>=4.4.2",
+    "hs2p[asap,cucim,openslide,sam2,vips]>=4.4.3",
     "omegaconf",
     "matplotlib",
     "numpy<2",
@@ -100,7 +100,7 @@ fm = [
     "pandas",
     "pillow",
     "rich",
-    "hs2p[asap,cucim,openslide,sam2,vips]>=4.4.2",
+    "hs2p[asap,cucim,openslide,sam2,vips]>=4.4.3",
     "wandb",
     "torch>=2.3,<2.8",
     "torchvision>=0.18.0",
@@ -158,7 +158,7 @@ testpaths = [
     "tests",
 ]
 markers = [
-    "heavy: real-weight foundation-model inference on CPU; minutes per test. Excluded from the PR suite via `-m 'not heavy'`; run on the scheduled/manual heavy workflow (.github/workflows/nightly-heavy.yaml).",
+    "heavy: real-weight foundation-model inference on CPU; minutes per test. Included in the PR suite and available separately 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`.",
 ]
 
@@ -180,14 +180,15 @@ no_implicit_reexport = true
 max-line-length = 160
 
 [tool.bumpver]
-current_version = "5.8.1"
+current_version = "5.9.0"
 version_pattern = "MAJOR.MINOR.PATCH"
-commit = false       # We do version bumping in CI, not as a commit
-tag = false          # Git tag already exists — we don't auto-tag
-push = false         # Don't push anything in CI
+commit = false
+tag = false
+push = false
 files = [
     "pyproject.toml",
-    "slide2vec/__init__.py"
+    "slide2vec/__init__.py",
+    "docs/conf.py",
 ]
 
 [tool.bumpver.file_patterns]
@@ -198,3 +199,6 @@ files = [
 "slide2vec/__init__.py" = [
     '^__version__ = "{version}"$',
 ]
+"docs/conf.py" = [
+    '^release = "{version}"$',
+]

{slide2vec-5.8.1 → slide2vec-5.9.0}/slide2vec/__init__.py

@@ -27,7 +27,7 @@ from slide2vec.encoders import (
 )
 
 
-__version__ = "5.8.1"
+__version__ = "5.9.0"
 
 __all__ = [
     "Model",

{slide2vec-5.8.1 → slide2vec-5.9.0}/slide2vec/api.py

@@ -7,7 +7,7 @@ import warnings
 from dataclasses import dataclass, field, replace
 from contextlib import contextmanager
 from pathlib import Path
-from typing import Any, Mapping, Protocol, Sequence
+from typing import Any, Callable, Mapping, Protocol, Sequence
 
 import torch
 from hs2p import SlideSpec
@@ -128,15 +128,12 @@ def resolve_masks(masks: Mapping[str, Any] | None) -> dict[str, Any]:
 
 def _masks_to_plain_dict(node: Any) -> dict[str, Any]:
     """Normalize a masks config node (OmegaConf, mapping, or namespace) to a plain dict."""
+    from omegaconf import OmegaConf
+
     if node is None:
         return {}
-    try:
-        from omegaconf import OmegaConf
-
-        if OmegaConf.is_config(node):
-            return copy.deepcopy(OmegaConf.to_container(node, resolve=True))  # type: ignore[return-value]
-    except ImportError:
-        pass
+    if OmegaConf.is_config(node):
+        return copy.deepcopy(OmegaConf.to_container(node, resolve=True))  # type: ignore[return-value]
     if isinstance(node, Mapping):
         return copy.deepcopy(dict(node))
     return copy.deepcopy(dict(vars(node)))
@@ -243,7 +240,6 @@ class PreprocessingConfig:
             "preview",
             _deep_merge_dicts(DEFAULT_PREPROCESSING["preview"], self.preview),
         )
-        # Complete a (possibly partial) masks mapping against the shipped default.
         object.__setattr__(self, "masks", resolve_masks(self.masks))
 
     @classmethod
@@ -710,6 +706,7 @@ class Model:
         *,
         preprocessing: PreprocessingConfig | None = None,
         execution: ExecutionOptions | None = None,
+        on_slide_persisted: Callable[[TileEmbeddingArtifact | HierarchicalEmbeddingArtifact], None] | None = None,
     ) -> list[TileEmbeddingArtifact] | list[HierarchicalEmbeddingArtifact]:
         from slide2vec.inference import embed_tiles
 
@@ -724,6 +721,7 @@ class Model:
                 tiling_results,
                 execution=resolved,
                 preprocessing=resolved_preprocessing,
+                on_slide_persisted=on_slide_persisted,
             )
 
     def aggregate_tiles(
@@ -1217,6 +1215,7 @@ class Pipeline:
         coordinates_dir: str | Path,
         *,
         slides: SlideSequence | None = None,
+        on_slide_persisted: Callable[[TileEmbeddingArtifact | HierarchicalEmbeddingArtifact], None] | None = None,
     ) -> RunResult:
         from slide2vec.inference import run_pipeline_with_coordinates
 
@@ -1229,6 +1228,7 @@ class Pipeline:
                 slides=slides,
                 preprocessing=resolved_preprocessing,
                 execution=self.execution,
+                on_slide_persisted=on_slide_persisted,
             )
 
 

{slide2vec-5.8.1 → slide2vec-5.9.0}/slide2vec/data/tile_reader.py

@@ -52,7 +52,6 @@ def _open_wsi_backend(image_path: str, backend: str, gpu_decode: bool):
         return VIPSReader(image_path)
     elif backend == "asap":
         from hs2p.wsi.backends.asap import ASAPReader
-        from slide2vec.utils.log_utils import suppress_c_stderr
         with suppress_c_stderr():
             return ASAPReader(image_path)
     else:

{slide2vec-5.8.1 → slide2vec-5.9.0}/slide2vec/distributed/__init__.py

@@ -133,7 +133,6 @@ class _TorchDistributedEnvironment:
 
     # Single node job with preset environment (i.e. torchrun)
     def _set_from_preset_env(self):
-        # logger.info("Initialization from preset environment")
         self.rank = int(os.environ["RANK"])
         self.world_size = int(os.environ["WORLD_SIZE"])
         assert self.rank < self.world_size
@@ -143,7 +142,6 @@ class _TorchDistributedEnvironment:
 
     # Single node and GPU job (i.e. local script run)
     def _set_from_local(self):
-        # logger.info("Initialization from local")
         self.rank = 0
         self.world_size = 1
         self.local_rank = 0
@@ -196,7 +194,6 @@ def enable(
     if set_cuda_current_device:
         torch.cuda.set_device(torch_env.local_rank)
 
-    # Finalize setup
     _RANK = torch_env.rank
     _WORLD_SIZE = torch_env.world_size
     _LOCAL_RANK = torch_env.local_rank

{slide2vec-5.8.1 → slide2vec-5.9.0}/slide2vec/encoders/models/gigapath.py

@@ -48,13 +48,8 @@ class GigaPath(TimmTileEncoder):
         )
 
     def get_transform(self) -> Callable:
-        # POOLED transform only: center-crops the 256px tile to the model's 224px
-        # native input (paper recipe, center 224 @ native 0.5 mpp). Dense extraction
-        # must NOT route through this — it needs the full uncropped tile so the grid
-        # covers the whole source tile. The dense path supplies its own no-crop
-        # transform (Resize(256), no CenterCrop) → a 16x16 grid over the full tile;
-        # encode_tiles_dense itself is transform-agnostic (inherited from
-        # TimmTileEncoder) and operates on whatever batch the dense pipeline feeds.
+        # Pooled recipe: center 224px at native spacing. Dense extraction uses
+        # get_normalization_transform() to preserve the caller's tile geometry.
         return v2.Compose([
             v2.ToImage(),
             v2.Resize(256, interpolation=v2.InterpolationMode.BICUBIC, antialias=True),
@@ -123,6 +118,9 @@ class GigaPathSlideEncoder(SlideEncoder):
             tile_features = tile_features.unsqueeze(0)
         if coordinates.ndim == 2:
             coordinates = coordinates.unsqueeze(0)
+        # prov-gigapath's reference usage feeds fp32 tile embeddings under autocast;
+        # fp16 input risks dtype mismatches in ops autocast does not cover.
+        tile_features = tile_features.float()
         # gigapath_slide_enc12l768d.forward always returns a list of per-layer
         # embeddings (a single element when all_layer_embed is False); the final
         # slide embedding is the last layer, matching prov-gigapath's own usage.

{slide2vec-5.8.1 → slide2vec-5.9.0}/slide2vec/encoders/models/moozy/slide.py

@@ -50,7 +50,7 @@ class MOOZYSlideEncoder(nn.Module):
                     dropout=dropout,
                     attn_dropout=attn_dropout,
                     alibi=self.pos_bias,
-                    drop_path_rate=dpr[i] if i < len(dpr) else 0.0,
+                    drop_path_rate=dpr[i],
                     qk_norm=qk_norm,
                     layerscale_init=layerscale_init,
                 )
@@ -109,26 +109,18 @@ class MOOZYSlideEncoder(nn.Module):
         x = torch.cat(tokens, dim=1)
 
         coords_xy = coords_xy.to(device=x.device, dtype=torch.float32).reshape(bsz, n_tokens, 2)
-        zeros_cls = torch.zeros(bsz, 1, 2, dtype=coords_xy.dtype, device=coords_xy.device)
-        if self.num_registers > 0:
-            zeros_reg = torch.zeros(bsz, self.num_registers, 2, dtype=coords_xy.dtype, device=coords_xy.device)
-            positions = torch.cat([zeros_cls, zeros_reg, coords_xy], dim=1)
-        else:
-            positions = torch.cat([zeros_cls, coords_xy], dim=1)
-
-        valid_flat = ~invalid_flat
-        reg_valid = (
-            torch.ones(bsz, self.num_registers, dtype=torch.bool, device=x.device)
-            if self.num_registers > 0
-            else torch.zeros(bsz, 0, dtype=torch.bool, device=x.device)
+        num_prefix = 1 + self.num_registers
+        prefix_positions = torch.zeros(
+            bsz, num_prefix, 2, dtype=coords_xy.dtype, device=coords_xy.device
         )
-        valid_with_cls = torch.cat([torch.ones(bsz, 1, dtype=torch.bool, device=x.device), reg_valid, valid_flat], dim=1)
+        positions = torch.cat([prefix_positions, coords_xy], dim=1)
+        prefix_valid = torch.ones(bsz, num_prefix, dtype=torch.bool, device=x.device)
+        valid_with_cls = torch.cat([prefix_valid, ~invalid_flat], dim=1)
 
         if mask is None and bsz == 1:
             keep = valid_with_cls[0]
-            if keep.sum() > 0:
-                x = x[:, keep, :]
-                positions = positions[:, keep, :]
+            x = x[:, keep, :]
+            positions = positions[:, keep, :]
             attn_mask = None
         else:
             pair_valid = valid_with_cls.unsqueeze(2) & valid_with_cls.unsqueeze(1)

slide2vec-5.9.0/slide2vec/encoders/models/titan.py

@@ -0,0 +1,180 @@
+"""TITAN slide encoder implementation."""
+
+import math
+import sys
+
+import numpy as np
+import torch
+from transformers import AutoModel
+
+from slide2vec.encoders.base import SlideEncoder, preferred_default_device, resolve_requested_output_variant
+from slide2vec.encoders.registry import register_encoder
+
+# Pinned so the remote-code patches below stay valid (and so runs are reproducible —
+# an unpinned from_pretrained re-downloads whatever is at the repo HEAD).
+_TITAN_REVISION = "dac6773d9961cfc75503440676ff157a2c6e8d2e"
+
+
+def _alibi_slopes(n: int) -> list[float]:
+    # verbatim ALiBi slope schedule from TITAN's get_alibi at the pinned revision
+    if math.log2(n).is_integer():
+        p = 2 ** (-(2 ** -(math.log2(n) - 3)))
+        return [p * (p ** i) for i in range(n)]
+    nearest = 2 ** math.floor(math.log2(n))
+    base = _alibi_slopes(nearest)
+    extra = _alibi_slopes(2 * nearest)[0::2][: n - nearest]
+    return base + extra
+
+
+def _lean_alibi_bias(module, w, h, bg_mask, device, dtype):
+    """Bitwise-identical replacement for TITAN's get_alibi + the caller's cast/move.
+
+    The reference builds the [1, heads, N, N] bias through N x N float64 numpy on
+    the CPU (>100 GB of host RAM for slides in the tens of thousands of tiles) and
+    hands SDPA an unaligned bias that forces the math kernel, which materializes a
+    second N^2 tensor on the GPU. This builds the same values on-device in fp16, in
+    row chunks, with rows padded to a multiple of 8 elements so the memory-efficient
+    SDPA kernel accepts the bias — peak memory drops from ~4x to ~1x the bias size.
+    """
+    ii, jj = torch.meshgrid(
+        torch.arange(w, device=device), torch.arange(h, device=device), indexing="ij"
+    )
+    if bg_mask is not None:
+        mask = bg_mask.to(device).squeeze(0)
+        ii, jj = ii[mask], jj[mask]
+    points = torch.stack([ii.reshape(-1), jj.reshape(-1)], dim=1).float()
+    n = points.shape[0]
+    length = n + 1  # +1 for the cls token; its bias row/col stays zero
+    padded = ((length + 7) // 8) * 8
+    slopes = torch.tensor(
+        _alibi_slopes(module.num_heads), device=device, dtype=torch.float32
+    ).view(module.num_heads, 1, 1)
+    bias = torch.zeros(1, module.num_heads, length, padded, device=device, dtype=dtype)
+    # chunk intermediate is (heads, step, n) fp32 — stays under ~1.5 GB even at 53k tiles
+    step = 512
+    for start in range(0, n, step):
+        diff = points[start : start + step].unsqueeze(1) - points.unsqueeze(0)
+        dist = diff.square().sum(-1).sqrt()
+        bias[0, :, 1 + start : 1 + start + dist.shape[0], 1:length] = (
+            dist.unsqueeze(0) * slopes * -1
+        ).to(dtype)
+    return bias[..., :length]
+
+
+def _patch_titan_remote_code(model) -> bool:
+    """Patch TITAN's remote code for fp16 input and bounded bias memory.
+
+    Two patches on the dynamically loaded module (it exists only after
+    from_pretrained): preprocess_features runs its grid index_add_ in fp32 (the op
+    rejects fp16 features) but returns the grid in the features' own dtype — an
+    exact roundtrip that keeps the whole forward on the fp16 path — and
+    forward_features' single-slide alibi branch swaps in _lean_alibi_bias.
+    Returns False without patching if the module does not look like the pinned
+    revision; the caller then falls back to fp32 features (correct, but with the
+    reference implementation's memory behavior).
+    """
+    try:
+        vision_encoder = model.vision_encoder
+        vit = sys.modules[type(vision_encoder).__module__]
+        if getattr(vit, "_slide2vec_titan_patched", False):
+            return True
+        for attr in ("pos_encode_type", "num_heads", "patch_embed", "_pos_embed", "norm_pre", "blocks", "norm"):
+            if not hasattr(vision_encoder, attr):
+                return False
+        if not callable(getattr(vit, "preprocess_features", None)):
+            return False
+    except Exception:
+        return False
+
+    orig_preprocess = vit.preprocess_features
+
+    def preprocess_features(features, coords, patch_size_lv0):
+        grid, coords_grid, bg_mask = orig_preprocess(features.float(), coords, patch_size_lv0)
+        return grid.to(features.dtype), coords_grid, bg_mask
+
+    orig_forward_features = type(vision_encoder).forward_features
+
+    def forward_features(self, x, coords=None, mask=None, bg_mask=None):
+        # single-slide alibi path only; anything else falls through to the original
+        if self.pos_encode_type != "alibi" or x.shape[0] != 1 or self.masked_im_modeling:
+            return orig_forward_features(self, x, coords=coords, mask=mask, bg_mask=bg_mask)
+        B, nc, w, h = x.shape
+        # bias dtype = input grid dtype, as in the original, which builds the bias
+        # before patch_embed; post-norm activations can be fp32 under autocast
+        in_dtype = x.dtype
+        x = x.flatten(2, 3).transpose(1, 2)
+        x = self.patch_embed(x)
+        x = self._pos_embed(x, coords, w, h)
+        x = self.norm_pre(x)
+        if bg_mask is not None:
+            keep = torch.cat(
+                (torch.ones((1, 1), dtype=torch.bool, device=x.device), bg_mask.view(1, -1)),
+                dim=1,
+            )
+            x = x[keep].unsqueeze(0)
+        attn_bias = _lean_alibi_bias(self, w, h, bg_mask, device=x.device, dtype=in_dtype)
+        x = self.blocks(x, attn_bias, bg_mask)
+        x = self.norm(x)
+        return x
+
+    vit.preprocess_features = preprocess_features
+    type(vision_encoder).forward_features = forward_features
+    vit._slide2vec_titan_patched = True
+    return True
+
+
+@register_encoder(
+    "titan",
+    level="slide",
+    tile_encoder="conchv15",
+    tile_encoder_output_variant="default",
+    output_variants={"default": {"encode_dim": 768}},
+    default_output_variant="default",
+    supported_spacing_um=0.5,
+    precision="fp16",
+    source="MahmoodLab/TITAN",
+)
+class TitanSlideEncoder(SlideEncoder):
+    def __init__(self, *, output_variant: str | None = None):
+        self._model = AutoModel.from_pretrained(
+            "MahmoodLab/TITAN", revision=_TITAN_REVISION, trust_remote_code=True
+        ).eval()
+        self._remote_code_patched = _patch_titan_remote_code(self._model)
+        self._device = preferred_default_device()
+        self._output_variant = resolve_requested_output_variant(output_variant)
+
+    @property
+    def encode_dim(self) -> int:
+        return 768
+
+    @property
+    def device(self) -> torch.device:
+        return self._device
+
+    def to(self, device: torch.device | str) -> "TitanSlideEncoder":
+        self._device = torch.device(device)
+        self._model = self._model.to(self._device)
+        return self
+
+    def encode_slide(
+        self,
+        tile_features: torch.Tensor,
+        coordinates: torch.Tensor | None = None,
+        *,
+        tile_size_lv0: int | None = None,
+    ) -> torch.Tensor:
+        if coordinates is None or tile_size_lv0 is None:
+            raise ValueError("TITAN slide encoding requires coordinates and tile_size_lv0")
+        if tile_features.ndim == 2:
+            tile_features = tile_features.unsqueeze(0)
+        if coordinates.ndim == 2:
+            coordinates = coordinates.unsqueeze(0)
+        if not self._remote_code_patched:
+            # fallback for unrecognized remote code: fp32 features satisfy its fp32
+            # grid index_add_, at the cost of the reference memory behavior
+            tile_features = tile_features.float()
+        return self._model.encode_slide_from_patch_features(
+            tile_features,
+            coordinates.long(),
+            np.int64(tile_size_lv0),
+        ).squeeze(0)

{slide2vec-5.8.1 → slide2vec-5.9.0}/slide2vec/inference.py

@@ -1,26 +1,14 @@
-import json
-import importlib
 import os
-import tempfile
-import threading
-import time
-from contextlib import contextmanager, nullcontext
-from dataclasses import replace
 from pathlib import Path
-from types import SimpleNamespace
 from typing import Any, Callable, Sequence
 
-import logging
-import pandas as pd
 import torch
-from hs2p import SlideSpec, tile_slides
-from hs2p.utils.stderr import run_with_filtered_stderr
+from hs2p import SlideSpec
 
 from slide2vec.runtime import (
     artifacts_collect,
     batching,
     cpu_budget,
-    distributed,
     distributed_stage,
     embedding,
     embedding_persist,
@@ -31,11 +19,9 @@ from slide2vec.runtime import (
     persist_callbacks,
     persistence,
     process_list,
-    serialization,
     slide_encode,
     tiling,
     tiling_pipeline,
-    worker_io,
 )
 from slide2vec.api import (
     EmbeddedPatient,
@@ -43,43 +29,21 @@ from slide2vec.api import (
     ExecutionOptions,
     PreprocessingConfig,
     RunResult,
-    _resolve_hierarchical_preprocessing,
 )
 from slide2vec.artifacts import (
     HierarchicalEmbeddingArtifact,
-    PatientEmbeddingArtifact,
     SlideEmbeddingArtifact,
     TileEmbeddingArtifact,
-    write_hierarchical_embeddings,
     load_array,
-    write_patient_embeddings,
-    write_tile_embedding_metadata,
 )
 from slide2vec.encoders.registry import (
     encoder_registry,
-    resolve_encoder_output,
     resolve_patch_size,
-    resolve_preprocessing_defaults,
 )
 from slide2vec.runtime.model_settings import canonicalize_model_name
 from slide2vec.runtime.types import LoadedModel
 from slide2vec.runtime.encoder_input_contract import EncoderInputContract
-from slide2vec.progress import (
-    emit_progress,
-    read_tiling_progress_snapshot,
-)
-from slide2vec.utils.log_utils import suppress_c_stderr
-from slide2vec.data.dataset import BatchTileCollator, TileIndexDataset
-from slide2vec.data.tile_reader import OnTheFlyBatchTileCollator, OnTheFlyHierarchicalBatchCollator
-from slide2vec.utils.tiling_io import (
-    load_embedding_process_df,
-    load_patient_id_mapping,
-    load_slide_manifest,
-    load_tiling_process_df,
-    load_tiling_result_from_row,
-    _optional_float,
-)
-from slide2vec.utils.utils import cpu_worker_limit, slurm_cpu_limit
+from slide2vec.progress import emit_progress
 
 from slide2vec.runtime.hierarchical import num_embedding_items
 
@@ -126,13 +90,15 @@ def load_model(
     info = encoder_registry.info(name)
     resolved_level = info["level"]
 
-    if token is None and "HF_TOKEN" in os.environ:
-        token = os.environ["HF_TOKEN"]
-
+    # Never call ``huggingface_hub.login()`` here. Every encoder resolves its auth
+    # through the process-global ``huggingface_hub.get_token()``, which reads
+    # ``HF_TOKEN`` from the environment ahead of any stored token file, so an
+    # exported ``HF_TOKEN`` is all the hub needs. ``login()`` additionally rewrites a
+    # shared ``stored_tokens`` file without a lock; under distributed extraction every
+    # rank re-runs load_model per chunk and the concurrent truncate/re-read races,
+    # crashing runs with ``ValueError: Token ... not found``.
     if token is not None:
-        from huggingface_hub import login as hf_login
-
-        hf_login(token=token, add_to_git_credential=False)
+        os.environ["HF_TOKEN"] = token
 
     encoder_cls = encoder_registry.require(name)
     # Pass allow_non_recommended_settings ONLY to encoders whose constructor accepts it
@@ -625,6 +591,7 @@ def embed_tiles(
     *,
     execution: ExecutionOptions,
     preprocessing: PreprocessingConfig | None = None,
+    on_slide_persisted: Callable[[TileEmbeddingArtifact | HierarchicalEmbeddingArtifact], None] | None = None,
 ) -> list[TileEmbeddingArtifact] | list[HierarchicalEmbeddingArtifact]:
     if execution.output_dir is None:
         raise ValueError("ExecutionOptions.output_dir is required to persist tile embeddings")
@@ -694,6 +661,8 @@ def embed_tiles(
                 annotation=embedding.tiling_result_annotation(tiling_result),
             )
         artifacts.append(artifact)
+        if on_slide_persisted is not None:
+            on_slide_persisted(artifact)
     return artifacts
 
 
@@ -714,11 +683,7 @@ def aggregate_tiles(
     outputs: list[SlideEmbeddingArtifact] = []
     for artifact in tile_artifacts:
         metadata = artifact.metadata
-        if "coordinates_npz_path" not in metadata or "coordinates_meta_path" not in metadata:
-            raise ValueError(
-                f"Tile artifact for {artifact.sample_id} is missing tiling metadata paths required for slide aggregation"
-            )
-        if not metadata["coordinates_npz_path"] or not metadata["coordinates_meta_path"]:
+        if not metadata.get("coordinates_npz_path") or not metadata.get("coordinates_meta_path"):
             raise ValueError(
                 f"Tile artifact for {artifact.sample_id} is missing tiling metadata paths required for slide aggregation"
             )
@@ -735,13 +700,12 @@ def aggregate_tiles(
             tiling_result,
             execution=execution,
         )
-        latents = None
         slide_artifact = embedding.write_slide_embedding_artifact(
             artifact.sample_id,
             slide_embedding,
             execution=execution,
             metadata=embedding.build_slide_embedding_metadata(model, image_path=metadata["image_path"]),
-            latents=latents,
+            latents=None,
         )
         outputs.append(slide_artifact)
     return outputs
@@ -921,9 +885,8 @@ def run_pipeline(
             execution=execution,
             process_list_path=process_list_path,
         )
-        embedded_slides: list[EmbeddedSlide] = []
         if pending_slides:
-            embedded_slides = embedding_pipeline.compute_embedded_slides(
+            embedding_pipeline.compute_embedded_slides(
                 model,
                 pending_slides,
                 pending_tiling_results,
@@ -972,6 +935,7 @@ def run_pipeline_with_coordinates(
     slides=None,
     preprocessing: PreprocessingConfig | None = None,
     execution: ExecutionOptions,
+    on_slide_persisted: Callable[[TileEmbeddingArtifact | HierarchicalEmbeddingArtifact], None] | None = None,
 ) -> RunResult:
     if execution.output_dir is None:
         raise ValueError("ExecutionOptions.output_dir is required for Pipeline.run_with_coordinates(...)")
@@ -1031,6 +995,7 @@ def run_pipeline_with_coordinates(
                 execution=execution,
                 output_dir=output_dir,
                 tiling_input_dir=Path(coordinates_dir),
+                on_slide_persisted=on_slide_persisted,
             )
             return RunResult(
                 tile_artifacts=tile_artifacts,
@@ -1043,6 +1008,7 @@ def run_pipeline_with_coordinates(
             preprocessing=resolved_preprocessing,
             execution=execution,
             process_list_path=process_list_path,
+            on_artifact=on_slide_persisted,
         )
         embedding_pipeline.compute_embedded_slides(
             model,