slide2vec 5.1.0__tar.gz → 5.2.0__tar.gz

{slide2vec-5.1.0 → slide2vec-5.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 5.1.0
+Version: 5.2.0
 Summary: Embedding of whole slide images with Foundation Models
 Author-email: Clément Grisi <clement.grisi@radboudumc.nl>
 License-Expression: Apache-2.0

{slide2vec-5.1.0 → slide2vec-5.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "slide2vec"
-version = "5.1.0"
+version = "5.2.0"
 description = "Embedding of whole slide images with Foundation Models"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -167,7 +167,7 @@ no_implicit_reexport = true
 max-line-length = 160
 
 [tool.bumpver]
-current_version = "5.1.0"
+current_version = "5.2.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

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/__init__.py

@@ -11,7 +11,7 @@ from slide2vec.api import (
 from slide2vec.artifacts import HierarchicalEmbeddingArtifact, SlideEmbeddingArtifact, TileEmbeddingArtifact
 
 
-__version__ = "5.1.0"
+__version__ = "5.2.0"
 
 __all__ = [
     "Model",

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/api.py

@@ -21,7 +21,11 @@ from slide2vec.encoders.registry import (
     resolve_preprocessing_defaults,
 )
 from slide2vec.encoders.validation import validate_encoder_config
-from slide2vec.runtime.model_settings import canonicalize_model_name, normalize_precision_name
+from slide2vec.runtime.model_settings import (
+    canonicalize_model_name,
+    normalize_output_dtype,
+    normalize_precision_name,
+)
 from slide2vec.progress import emit_progress
 from slide2vec.runtime.types import LoadedModel
 from slide2vec.utils.utils import cpu_worker_limit, slurm_cpu_limit
@@ -226,6 +230,10 @@ class ExecutionOptions:
     #: Forward-pass dtype — ``"fp16"``, ``"bf16"``, ``"fp32"``,
     #: or ``None`` (auto-determined from the model preset).
     precision: str | None = None
+    #: On-disk feature dtype — ``"fp16"``, ``"fp32"``, or ``None`` to follow
+    #: :attr:`precision` (fp16 → fp16, else fp32). Applies to tile, slide, hierarchical,
+    #: and patient artifacts; ``"bf16"`` is rejected (numpy has no bfloat16).
+    output_dtype: str | None = None
     #: DataLoader prefetch queue depth per worker (default ``4``).
     prefetch_factor: int = 4
     #: Persist tile embeddings to disk when running a slide-level model.
@@ -253,6 +261,7 @@ class ExecutionOptions:
             ),
             num_gpus=1 if run_on_cpu else (int(configured_num_gpus) if configured_num_gpus is not None else None),
             precision="fp32" if run_on_cpu else requested_precision,
+            output_dtype=getattr(cfg.speed, "output_dtype", None),
             prefetch_factor=prefetch_factor,
             save_tile_embeddings=bool(cfg.model.save_tile_embeddings),
             save_slide_embeddings=bool(cfg.model.save_slide_embeddings),
@@ -263,6 +272,7 @@ class ExecutionOptions:
         resolved_num_gpus = _default_num_gpus() if self.num_gpus is None else self.num_gpus
         object.__setattr__(self, "num_gpus", resolved_num_gpus)
         object.__setattr__(self, "precision", normalize_precision_name(self.precision))
+        object.__setattr__(self, "output_dtype", normalize_output_dtype(self.output_dtype))
         if resolved_num_gpus < 1:
             raise ValueError("ExecutionOptions.num_gpus must be at least 1")
         if self.prefetch_factor < 1:

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/artifacts.py

@@ -7,6 +7,8 @@ import numpy as np
 import torch
 from hs2p.fileops import is_flattened_annotation
 
+from slide2vec.runtime.model_settings import output_torch_dtype
+
 
 @dataclass(frozen=True, kw_only=True)
 class TileEmbeddingArtifact:
@@ -74,6 +76,26 @@ def _validate_output_format(output_format: str) -> str:
     return normalized
 
 
+_OUTPUT_NUMPY_DTYPE = {"fp16": np.float16, "fp32": np.float32}
+
+
+def cast_feature_dtype(data: Any, precision: str) -> Any:
+    """Cast features to the on-disk ``precision`` (``"fp16"`` / ``"fp32"``), keeping their kind.
+
+    Torch tensors are cast via ``.to`` and arrays via ``astype``; ``None`` (no features)
+    passes through. This is what makes the pooled tile/slide/hierarchical/patient artifacts
+    land in a deterministic dtype, mirroring the dense path's ``output_dtype``. The precision
+    is resolved upstream by :func:`slide2vec.runtime.model_settings.resolve_output_precision`,
+    so only ``"fp16"`` / ``"fp32"`` reach here.
+    """
+    if data is None:
+        return data
+    torch_dtype = output_torch_dtype(precision)  # validates precision (shared string→dtype map)
+    if torch.is_tensor(data):
+        return data.to(torch_dtype)
+    return np.asarray(data).astype(_OUTPUT_NUMPY_DTYPE[precision], copy=False)
+
+
 def _ensure_array(data: Any) -> np.ndarray:
     if isinstance(data, np.ndarray):
         return data

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/configs/default.yaml

@@ -88,6 +88,7 @@ tiling:
 
 speed:
   precision: # model inference precision ["fp32", "fp16", "bf16"]; if not set, determined automatically based on model recommendations
+  output_dtype: # on-disk feature dtype ["fp16", "fp32"]; if not set, follows speed.precision (fp16 -> fp16, otherwise fp32)
   num_dataloader_workers: # number of DataLoader worker processes per GPU rank for reading tiles during embedding; defaults to auto (job CPU budget split across GPUs, except cuCIM on-the-fly uses per-GPU budget // speed.num_cucim_workers)
   num_gpus: # number of GPUs to use for feature extraction; defaults to all available GPUs
   num_preprocessing_workers: # number of workers for hs2p tiling (WSI reading, JPEG encoding, tar writing); defaults to the runtime CPU budget capped at 64

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/encoders/__init__.py

@@ -16,8 +16,10 @@ from slide2vec.encoders.base import (
 )
 from slide2vec.encoders.registry import (
     encoder_registry,
+    normalize_patch_size,
     register_encoder,
     resolve_encoder_output,
+    resolve_patch_size,
     resolve_preprocessing_requirements,
     resolve_tile_dependency_output,
 )
@@ -35,7 +37,9 @@ __all__ = [
     "resolve_recommended_dynamic_img_size",
     "resolve_requested_output_variant",
     "encoder_registry",
+    "normalize_patch_size",
     "register_encoder",
+    "resolve_patch_size",
     "resolve_preprocessing_requirements",
     "resolve_encoder_output",
     "resolve_tile_dependency_output",

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/encoders/models/conch.py

@@ -78,6 +78,7 @@ def _encode_trunk_dense(*, trunk, batch: Tensor, encoder_name: str) -> Tensor:
     output_variants={"default": {"encode_dim": 512}},
     default_output_variant="default",
     input_size=448,
+    patch_size=16,
     supported_spacing_um=0.5,
     precision="fp32",
     source="MahmoodLab/conch",
@@ -163,6 +164,7 @@ class CONCH(TileEncoder):
     output_variants={"default": {"encode_dim": 768}},
     default_output_variant="default",
     input_size=448,
+    patch_size=16,
     supported_spacing_um=0.5,
     precision="fp16",
     source="MahmoodLab/TITAN",

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/encoders/models/gigapath.py

@@ -27,6 +27,7 @@ _GIGAPATH_STD = (0.229, 0.224, 0.225)
     output_variants={"default": {"encode_dim": 1536}},
     default_output_variant="default",
     input_size=256,
+    patch_size=14,
     supported_spacing_um=0.5,
     precision="fp16",
     source="prov-gigapath/prov-gigapath",

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/encoders/models/hibou.py

@@ -151,6 +151,7 @@ class _HibouBase(TileEncoder):
     output_variants={"default": {"encode_dim": 768}},
     default_output_variant="default",
     input_size=224,
+    patch_size=14,
     supported_spacing_um=0.5,
     precision="fp16",
     source="histai/hibou-b",
@@ -167,6 +168,7 @@ class HibouB(_HibouBase):
     output_variants={"default": {"encode_dim": 1024}},
     default_output_variant="default",
     input_size=224,
+    patch_size=14,
     supported_spacing_um=0.5,
     precision="fp16",
     source="histai/hibou-L",

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/encoders/models/hoptimus.py

@@ -72,6 +72,7 @@ class _HOptimusBase(TimmTileEncoder):
     output_variants={"default": {"encode_dim": 1536}},
     default_output_variant="default",
     input_size=224,
+    patch_size=14,
     supported_spacing_um=0.5,
     precision="fp16",
     source="bioptimus/H-optimus-0",
@@ -108,6 +109,7 @@ class HOptimus0(TimmTileEncoder):
     output_variants={"default": {"encode_dim": 1536}},
     default_output_variant="default",
     input_size=224,
+    patch_size=14,
     supported_spacing_um=0.5,
     precision="fp16",
     source="bioptimus/H-optimus-1",
@@ -145,6 +147,7 @@ class HOptimus1(TimmTileEncoder):
     },
     default_output_variant="cls_patch_mean",
     input_size=224,
+    patch_size=14,
     supported_spacing_um=0.5,
     precision="fp16",
     source="bioptimus/H0-mini",

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/encoders/models/lunit.py

@@ -9,6 +9,7 @@ from slide2vec.encoders.registry import register_encoder
     output_variants={"default": {"encode_dim": 384}},
     default_output_variant="default",
     input_size=224,
+    patch_size=8,
     supported_spacing_um=0.5,
     precision="fp32",
     source="1aurent/vit_small_patch8_224.lunit_dino",

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/encoders/models/midnight.py

@@ -27,6 +27,7 @@ from slide2vec.encoders.registry import register_encoder
     output_variants={"default": {"encode_dim": 3072}},
     default_output_variant="default",
     input_size=224,
+    patch_size=14,
     supported_spacing_um=[0.25, 0.5, 1.0, 2.0],
     precision="fp16",
     source="kaiko-ai/midnight",

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/encoders/models/musk.py

@@ -35,6 +35,7 @@ def _as_hw(value: int | tuple[int, int] | list[int]) -> tuple[int, int]:
     },
     default_output_variant="ms_aug",
     input_size=384,
+    patch_size=16,
     supported_spacing_um=[0.25, 0.5, 1.0],
     precision="fp16",
     source="xiangjx/musk",

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/encoders/models/phikon.py

@@ -148,6 +148,7 @@ class _PhikonBase(TileEncoder):
     output_variants={"default": {"encode_dim": 768}},
     default_output_variant="default",
     input_size=224,
+    patch_size=16,
     supported_spacing_um=0.5,
     precision="fp32",
     source="owkin/phikon",
@@ -165,6 +166,7 @@ class Phikon(_PhikonBase):
     output_variants={"default": {"encode_dim": 1024}},
     default_output_variant="default",
     input_size=224,
+    patch_size=16,
     supported_spacing_um=0.5,
     precision="fp32",
     source="owkin/phikon-v2",

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/encoders/models/prost40m.py

@@ -9,6 +9,7 @@ from slide2vec.encoders.registry import register_encoder
     output_variants={"default": {"encode_dim": 384}},
     default_output_variant="default",
     input_size=224,
+    patch_size=16,
     supported_spacing_um=0.5,
     precision="fp32",
     source="waticlems/Prost40M",

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/encoders/models/uni.py

@@ -13,6 +13,7 @@ from slide2vec.encoders.registry import register_encoder
     output_variants={"default": {"encode_dim": 1024}},
     default_output_variant="default",
     input_size=224,
+    patch_size=16,
     supported_spacing_um=0.5,
     precision="fp16",
     source="MahmoodLab/UNI",
@@ -32,6 +33,7 @@ class UNI(TimmTileEncoder):
     output_variants={"default": {"encode_dim": 1536}},
     default_output_variant="default",
     input_size=224,
+    patch_size=14,
     supported_spacing_um=0.5,
     precision="fp16",
     source="MahmoodLab/UNI2-h",

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/encoders/models/virchow.py

@@ -50,6 +50,7 @@ class _VirchowBase(TimmTileEncoder):
     },
     default_output_variant="cls_patch_mean",
     input_size=224,
+    patch_size=14,
     supported_spacing_um=0.5,
     precision="fp16",
     source="paige-ai/Virchow",
@@ -67,6 +68,7 @@ class Virchow(_VirchowBase):
     },
     default_output_variant="cls_patch_mean",
     input_size=224,
+    patch_size=14,
     supported_spacing_um=[0.25, 0.5, 1.0, 2.0],
     precision="fp16",
     source="paige-ai/Virchow2",

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/encoders/registry.py

@@ -37,6 +37,7 @@ def register_encoder(
     output_variants: dict[str, dict[str, Any]],
     default_output_variant: str,
     input_size: int | None = None,
+    patch_size: int | tuple[int, int] | None = None,
     level: str = "tile",
     tile_encoder: str | None = None,
     tile_encoder_output_variant: str | None = None,
@@ -51,6 +52,12 @@ def register_encoder(
         output_variants: Supported named encoder outputs with concrete metadata.
         default_output_variant: Default output variant name.
         input_size: Recommended encoder input image size in pixels.
+        patch_size: Backbone patch size, as ``int`` (square) or ``(patch_h,
+            patch_w)``. Optional: only dense-capable ViT tile encoders have a
+            meaningful patch grid. Declared statically so the dense token grid /
+            cache key can be resolved via :func:`resolve_patch_size` WITHOUT
+            instantiating the (multi-GB) encoder; the model-load path asserts this
+            static value still equals the loaded model's runtime ``patch_size``.
         level: Encoder output level ("tile" or "slide").
         tile_encoder: Registered tile encoder dependency for slide-level models.
         tile_encoder_output_variant: Fixed tile-encoder output variant for slide models.
@@ -67,6 +74,7 @@ def register_encoder(
         "default_output_variant": default_output_variant,
         "level": level,
         "input_size": input_size,
+        "patch_size": patch_size,
         "tile_encoder": tile_encoder,
         "tile_encoder_output_variant": tile_encoder_output_variant,
         "supported_spacing_um": supported_spacing_um,
@@ -76,6 +84,41 @@ def register_encoder(
     return encoder_registry.register_decorator(name, metadata=metadata)
 
 
+def normalize_patch_size(value: int | tuple[int, int]) -> tuple[int, int]:
+    """Normalize a patch size to a ``(patch_h, patch_w)`` int tuple.
+
+    This is the SAME representation the runtime ``encoder.patch_size`` instance
+    property returns, so static and runtime values compare/serialize identically
+    (a downstream dense cache key depends on this byte-for-byte equality).
+    """
+    if isinstance(value, int):
+        return (value, value)
+    patch_h, patch_w = value
+    return (int(patch_h), int(patch_w))
+
+
+def resolve_patch_size(
+    encoder_name: str,
+    metadata: dict[str, Any] | None = None,
+) -> tuple[int, int]:
+    """Resolve an encoder's static patch size WITHOUT constructing the model.
+
+    Reads the ``patch_size`` declared on the encoder's ``@register_encoder`` and
+    normalizes it to a ``(patch_h, patch_w)`` int tuple (matching the runtime
+    ``encoder.patch_size``). Raises a clear error for encoders that do not declare
+    one (non-dense encoders) rather than returning a wrong value.
+    """
+    info = metadata if metadata is not None else encoder_registry.info(encoder_name)
+    patch = info.get("patch_size")
+    if patch is None:
+        raise ValueError(
+            f"Encoder '{encoder_name}' does not declare a patch_size in its registry "
+            "metadata. patch_size is only defined for dense-capable ViT tile encoders; "
+            "non-dense encoders have no recoverable patch grid."
+        )
+    return normalize_patch_size(patch)
+
+
 def resolve_preprocessing_requirements(
     encoder_name: str,
     metadata: dict[str, Any] | None = None,

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/inference.py

@@ -59,6 +59,7 @@ from slide2vec.artifacts import (
 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
@@ -121,6 +122,21 @@ def load_model(
         extra_kwargs["allow_non_recommended_settings"] = allow_non_recommended_settings
     encoder = encoder_cls(output_variant=output_variant, **extra_kwargs)
 
+    # Drift guard: the static patch_size declared on @register_encoder is read
+    # (without loading the model) to resolve the dense cache key. Assert it still
+    # equals the loaded model's runtime patch_size so the static metadata can never
+    # silently diverge from the architecture and corrupt that key.
+    if info.get("patch_size") is not None:
+        static_patch_size = resolve_patch_size(name, metadata=info)
+        runtime_patch_size = encoder.patch_size
+        if tuple(runtime_patch_size) != static_patch_size:
+            raise ValueError(
+                f"Encoder '{name}' declares a static patch_size {static_patch_size} "
+                f"(registry metadata) but the loaded model reports "
+                f"{tuple(runtime_patch_size)}. The static value seeds the dense cache "
+                "key; fix the @register_encoder patch_size to match the architecture."
+            )
+
     tile_encoder = None
     if resolved_level == "tile":
         transforms = encoder.get_transform()

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/runtime/dense_regions.py

@@ -40,8 +40,30 @@ import torch.nn.functional as F
 from PIL import Image
 
 from slide2vec.runtime.dense_sliding import encode_dense_sliding
+from slide2vec.runtime.model_settings import output_torch_dtype, resolve_output_precision
 from slide2vec.runtime.slide_encode import slide_encode_autocast_ctx
 
+
+def _resolve_output_dtype(output_dtype: "torch.dtype | None", precision: str) -> "torch.dtype":
+    """Resolve the dtype emitted grids are materialized in.
+
+    Defaults (``output_dtype is None``) to the model's compute precision — fp16 runs
+    yield fp16 grids — so the engine no longer force-upcasts everything to float32.
+    numpy has no bfloat16, so a bf16 compute precision widens to float32 (its lossless
+    container) and an *explicit* ``torch.bfloat16`` request is rejected: the grid is
+    materialized via ``.numpy()`` and bfloat16 cannot cross that boundary.
+    """
+    if output_dtype is None:
+        # Shared rule with the pooled write path: fp16 compute -> fp16, else fp32.
+        return output_torch_dtype(resolve_output_precision(None, precision))
+    if output_dtype == torch.bfloat16:
+        raise ValueError(
+            "output_dtype=torch.bfloat16 cannot be materialized as a numpy grid; "
+            "request torch.float16 or torch.float32"
+        )
+    return output_dtype
+
+
 _PAD_MODES = {"reflect", "constant", "zero", "replicate"}
 
 
@@ -161,14 +183,16 @@ def iter_regions_dense(
     attention_include_registers: bool = False,
     batch_size: int = 1,
     precision: str = "fp32",
+    output_dtype: "torch.dtype | None" = None,
     dense_transform: Callable | None = None,
 ) -> Iterator[np.ndarray]:
     """Stream slide regions at ``coordinates`` into dense grids, one per coordinate.
 
-    Yields one ``(d, grid_h, grid_w)`` ``float32`` grid per coordinate, in coordinate
-    order. Regions are read and encoded one ``batch_size`` chunk at a time, so resident
-    host memory is bounded by ``batch_size`` rather than by a slide's ROI count (the loop
-    holds at most one batch of grids resident — no per-slide accumulation).
+    Yields one ``(d, grid_h, grid_w)`` grid per coordinate, in coordinate order, in the
+    model's compute ``precision`` by default (fp16 runs yield fp16 grids; see
+    ``output_dtype``). Regions are read and encoded one ``batch_size`` chunk at a time, so
+    resident host memory is bounded by ``batch_size`` rather than by a slide's ROI count
+    (the loop holds at most one batch of grids resident — no per-slide accumulation).
 
     Injectable core: takes a constructed dense-capable ``model`` (with
     ``encode_tiles_dense`` / ``encode_tiles_attention`` / ``patch_size`` /
@@ -194,8 +218,12 @@ def iter_regions_dense(
             sliding is internal to extraction.
         overlap: fractional window overlap in ``[0, 1)`` for the sliding path (ignored when
             ``window_size is None``); the stride is ``window * (1 - overlap)``.
+        output_dtype: torch dtype the grids are materialized in. ``None`` (default) follows
+            the compute ``precision`` — fp16 → fp16, fp32 → fp32, bf16 → fp32 (numpy has no
+            bfloat16). Pass e.g. ``torch.float32`` to force a lossless cache regardless of
+            precision; an explicit ``torch.bfloat16`` is rejected (cannot cross ``.numpy()``).
 
-    Yields ``float32`` grids in coordinate order; empty ``coordinates`` yields nothing.
+    Yields grids in coordinate order in ``output_dtype``; empty ``coordinates`` yields nothing.
     ``feature_kind`` selects ``encode_tiles_dense`` (patch grid) vs
     ``encode_tiles_attention`` (CLS-attention grid); both produce a ``(C, gh, gw)`` grid and
     share this path. Each yielded grid is a standalone contiguous copy, so it does not pin
@@ -203,6 +231,7 @@ def iter_regions_dense(
     """
     if pad_mode not in _PAD_MODES:
         raise ValueError(f"unsupported pad_mode {pad_mode!r}; expected one of {sorted(_PAD_MODES)}")
+    resolved_output_dtype = _resolve_output_dtype(output_dtype, precision)
     geometry = compute_dense_geometry(target_size=target_size, patch_size=model.patch_size)
     if dense_transform is None:
         dense_transform = model.get_dense_transform()
@@ -262,7 +291,7 @@ def iter_regions_dense(
                     raise ValueError(
                         f"{feature_kind} encode returned a {out.ndim}-D tensor; expected (B, d, gh, gw)."
                     )
-                batch_np = out.detach().float().cpu().numpy()
+                batch_np = out.detach().to(resolved_output_dtype).cpu().numpy()
                 for i in range(batch_np.shape[0]):
                     # Standalone C-contiguous copy: a per-row view would pin the whole
                     # batch alive (the blended sliding output is contiguous, so a view of

{slide2vec-5.1.0 → slide2vec-5.2.0}/slide2vec/runtime/embedding.py

@@ -10,11 +10,13 @@ from slide2vec.artifacts import (
     HierarchicalEmbeddingArtifact,
     SlideEmbeddingArtifact,
     TileEmbeddingArtifact,
+    cast_feature_dtype,
     write_hierarchical_embeddings,
     write_slide_embeddings,
     write_tile_embeddings,
 )
 from slide2vec.runtime.hierarchical import resolve_hierarchical_geometry
+from slide2vec.runtime.model_settings import resolve_output_precision
 
 
 def tiling_result_annotation(tiling_result) -> str | None:
@@ -114,12 +116,14 @@ def write_tile_embedding_artifact(
 ) -> TileEmbeddingArtifact:
     if execution.output_dir is None:
         raise ValueError("ExecutionOptions.output_dir is required to persist tile embeddings")
+    precision = resolve_output_precision(execution.output_dtype, execution.precision)
+    features = cast_feature_dtype(features, precision)
     return write_tile_embeddings(
         sample_id,
         features,
         output_dir=execution.output_dir,
         output_format=execution.output_format,
-        metadata=metadata,
+        metadata={**metadata, "feature_dtype": precision},
         tile_index=np.arange(_num_rows(features), dtype=np.int64),
         annotation=annotation,
     )
@@ -142,13 +146,14 @@ def write_slide_embedding_artifact(
 ) -> SlideEmbeddingArtifact:
     if execution.output_dir is None:
         raise ValueError("ExecutionOptions.output_dir is required to persist slide embeddings")
+    precision = resolve_output_precision(execution.output_dtype, execution.precision)
     return write_slide_embeddings(
         sample_id,
-        embedding,
+        cast_feature_dtype(embedding, precision),
         output_dir=execution.output_dir,
         output_format=execution.output_format,
-        metadata=metadata,
-        latents=latents,
+        metadata={**metadata, "feature_dtype": precision},
+        latents=cast_feature_dtype(latents, precision),
         annotation=annotation,
     )
 
@@ -163,11 +168,12 @@ def write_hierarchical_embedding_artifact(
 ) -> HierarchicalEmbeddingArtifact:
     if execution.output_dir is None:
         raise ValueError("ExecutionOptions.output_dir is required to persist hierarchical embeddings")
+    precision = resolve_output_precision(execution.output_dtype, execution.precision)
     return write_hierarchical_embeddings(
         sample_id,
-        features,
+        cast_feature_dtype(features, precision),
         output_dir=execution.output_dir,
         output_format=execution.output_format,
-        metadata=metadata,
+        metadata={**metadata, "feature_dtype": precision},
         annotation=annotation,
     )

slide2vec-5.2.0/slide2vec/runtime/model_settings.py

@@ -0,0 +1,97 @@
+import logging
+from typing import Any
+
+logger = logging.getLogger("slide2vec")
+
+
+PRECISION_ALIASES = {
+    "fp32": "fp32",
+    "float32": "fp32",
+    "32": "fp32",
+    "fp16": "fp16",
+    "float16": "fp16",
+    "16": "fp16",
+    "half": "fp16",
+    "bf16": "bf16",
+    "bfloat16": "bf16",
+}
+
+MODEL_NAME_ALIASES = {
+    "conch-v1.5": "conchv15",
+    "conch_v15": "conchv15",
+    "conchv1.5": "conchv15",
+    "conchv1_5": "conchv15",
+    "phikon-v2": "phikonv2",
+    "hibou-b": "hibou-b",
+    "hibou-l": "hibou-l",
+    "h-optimus-0-mini": "h0-mini",
+    "prov-gigapath": "gigapath",
+    "prov-gigapath-tile": "gigapath",
+    "prov-gigapath-slide": "gigapath-slide",
+    "kaiko-midnight": "midnight",
+}
+
+
+def normalize_precision_name(value: Any) -> str | None:
+    if value is None:
+        return None
+    normalized = str(value).strip().lower()
+    if normalized not in PRECISION_ALIASES:
+        supported = ", ".join(sorted(PRECISION_ALIASES))
+        raise ValueError(f"Unsupported precision {value!r}. Expected one of: {supported}")
+    return PRECISION_ALIASES[normalized]
+
+
+def normalize_output_dtype(value: Any) -> str | None:
+    """Normalize a requested on-disk feature dtype to ``"fp16"`` / ``"fp32"`` (or ``None``).
+
+    ``None`` means *follow the compute precision* (see :func:`resolve_output_precision`).
+    ``bf16`` is rejected: tile/slide/hierarchical/patient artifacts serialize through numpy,
+    which has no bfloat16 — the same boundary the dense path guards.
+    """
+    normalized = normalize_precision_name(value)
+    if normalized == "bf16":
+        raise ValueError(
+            "Unsupported output dtype 'bf16'. Feature artifacts serialize through numpy "
+            "(no bfloat16); choose 'fp16' or 'fp32', or leave unset to follow precision."
+        )
+    return normalized
+
+
+def resolve_output_precision(output_dtype: Any, compute_precision: Any) -> str:
+    """Resolve the concrete on-disk feature precision (``"fp16"`` or ``"fp32"``).
+
+    ``output_dtype is None`` follows ``compute_precision``: an fp16 forward keeps fp16
+    features, while bf16 / fp32 (and an unset or unknown compute precision) widen to fp32 —
+    fp32 is bf16's lossless container and the only float dtype a numpy artifact can hold.
+    A non-null ``output_dtype`` is honored verbatim (after :func:`normalize_output_dtype`).
+    This is the single source of truth shared by the pooled write path and the dense
+    ``iter_regions_dense`` path.
+    """
+    normalized = normalize_output_dtype(output_dtype)
+    if normalized is not None:
+        return normalized
+    return "fp16" if normalize_precision_name(compute_precision) == "fp16" else "fp32"
+
+
+def output_torch_dtype(precision: str):
+    """The torch dtype an on-disk feature artifact materializes in for ``precision``.
+
+    ``precision`` is a value returned by :func:`resolve_output_precision` (``"fp16"`` or
+    ``"fp32"``); anything else is a programming error. This is the single string→dtype
+    mapping shared by the pooled write path (:func:`slide2vec.artifacts.cast_feature_dtype`)
+    and the dense ``iter_regions_dense`` path, so both agree on the materialized dtype.
+    torch is imported lazily to keep this module importable without it.
+    """
+    import torch
+
+    mapping = {"fp16": torch.float16, "fp32": torch.float32}
+    if precision not in mapping:
+        raise ValueError(f"Unsupported output precision {precision!r}; expected 'fp16' or 'fp32'.")
+    return mapping[precision]
+
+
+def canonicalize_model_name(name: str) -> str:
+    normalized = name.strip().lower()
+    return MODEL_NAME_ALIASES.get(normalized, normalized)
+