slide2vec 5.7.0__tar.gz → 5.8.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 5.7.0
+Version: 5.8.1
 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.1
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=4.4.2
 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.1; extra == "fm"
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=4.4.2; extra == "fm"
 Requires-Dist: wandb; extra == "fm"
 Requires-Dist: torch<2.8,>=2.3; extra == "fm"
 Requires-Dist: torchvision>=0.18.0; extra == "fm"
@@ -207,7 +207,7 @@ embedded = model.embed_slide("/path/to/slide.svs", preprocessing=preprocessing)
 
 Hierarchical outputs have shape `(num_regions, tiles_per_region, feature_dim)` and are written to `hierarchical_embeddings/` when persisted.
 
-See [`docs/python-api.md`](docs/python-api.md) for details.
+See the [hierarchical features guide](https://clemsgrs.github.io/slide2vec/hierarchical.html) for details.
 
 ### Input Manifest
 
@@ -241,7 +241,7 @@ The package writes explicit artifact directories:
 
 `slide2vec` currently ships presets for 28 tile-level models, 4 slide-level models,
 and 1 patient-level model.
-For the full catalog and preset names, see [`docs/models.md`](docs/models.md).
+For the full catalog and preset names, see the [model zoo](https://clemsgrs.github.io/slide2vec/models.html).
 
 ## CLI
 
@@ -254,7 +254,7 @@ slide2vec /path/to/config.yaml
 
 By default, manifest-driven CLI runs use all available GPUs. Set `speed.num_gpus=4` when you want to cap the sharding explicitly.
 
-New to the CLI or doing batch runs to disk? Start with [`docs/cli.md`](docs/cli.md) for the config-driven workflow, overrides, and common run patterns.
+New to the CLI or doing batch runs to disk? Start with the [CLI guide](https://clemsgrs.github.io/slide2vec/cli.html) for the config-driven workflow and common run patterns.
 
 ## Docker
 
@@ -272,8 +272,8 @@ docker run --rm -it \
 
 ## Documentation
 
-- [Documentation website](https://clemsgrs.github.io/slide2vec/) for the polished docs site
-- [`docs/python-api.md`](docs/python-api.md) for the detailed API reference
-- [`docs/cli.md`](docs/cli.md) for the config-driven CLI guide
-- [`docs/models.md`](docs/models.md) for the full supported-model catalog
+- [Documentation website](https://clemsgrs.github.io/slide2vec/)
+- [API guide](https://clemsgrs.github.io/slide2vec/api.html)
+- [CLI guide](https://clemsgrs.github.io/slide2vec/cli.html)
+- [Model zoo](https://clemsgrs.github.io/slide2vec/models.html)
 - [`tutorials/api_walkthrough.ipynb`](tutorials/api_walkthrough.ipynb) for a notebook walkthrough of the API

{slide2vec-5.7.0 → slide2vec-5.8.1}/README.md

@@ -91,7 +91,7 @@ embedded = model.embed_slide("/path/to/slide.svs", preprocessing=preprocessing)
 
 Hierarchical outputs have shape `(num_regions, tiles_per_region, feature_dim)` and are written to `hierarchical_embeddings/` when persisted.
 
-See [`docs/python-api.md`](docs/python-api.md) for details.
+See the [hierarchical features guide](https://clemsgrs.github.io/slide2vec/hierarchical.html) for details.
 
 ### Input Manifest
 
@@ -125,7 +125,7 @@ The package writes explicit artifact directories:
 
 `slide2vec` currently ships presets for 28 tile-level models, 4 slide-level models,
 and 1 patient-level model.
-For the full catalog and preset names, see [`docs/models.md`](docs/models.md).
+For the full catalog and preset names, see the [model zoo](https://clemsgrs.github.io/slide2vec/models.html).
 
 ## CLI
 
@@ -138,7 +138,7 @@ slide2vec /path/to/config.yaml
 
 By default, manifest-driven CLI runs use all available GPUs. Set `speed.num_gpus=4` when you want to cap the sharding explicitly.
 
-New to the CLI or doing batch runs to disk? Start with [`docs/cli.md`](docs/cli.md) for the config-driven workflow, overrides, and common run patterns.
+New to the CLI or doing batch runs to disk? Start with the [CLI guide](https://clemsgrs.github.io/slide2vec/cli.html) for the config-driven workflow and common run patterns.
 
 ## Docker
 
@@ -156,8 +156,8 @@ docker run --rm -it \
 
 ## Documentation
 
-- [Documentation website](https://clemsgrs.github.io/slide2vec/) for the polished docs site
-- [`docs/python-api.md`](docs/python-api.md) for the detailed API reference
-- [`docs/cli.md`](docs/cli.md) for the config-driven CLI guide
-- [`docs/models.md`](docs/models.md) for the full supported-model catalog
+- [Documentation website](https://clemsgrs.github.io/slide2vec/)
+- [API guide](https://clemsgrs.github.io/slide2vec/api.html)
+- [CLI guide](https://clemsgrs.github.io/slide2vec/cli.html)
+- [Model zoo](https://clemsgrs.github.io/slide2vec/models.html)
 - [`tutorials/api_walkthrough.ipynb`](tutorials/api_walkthrough.ipynb) for a notebook walkthrough of the API

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "slide2vec"
-version = "5.7.0"
+version = "5.8.1"
 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.1",
+    "hs2p[asap,cucim,openslide,sam2,vips]>=4.4.2",
     "omegaconf",
     "matplotlib",
     "numpy<2",
@@ -100,7 +100,7 @@ fm = [
     "pandas",
     "pillow",
     "rich",
-    "hs2p[asap,cucim,openslide,sam2,vips]>=4.4.1",
+    "hs2p[asap,cucim,openslide,sam2,vips]>=4.4.2",
     "wandb",
     "torch>=2.3,<2.8",
     "torchvision>=0.18.0",
@@ -180,7 +180,7 @@ no_implicit_reexport = true
 max-line-length = 160
 
 [tool.bumpver]
-current_version = "5.7.0"
+current_version = "5.8.1"
 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.7.0 → slide2vec-5.8.1}/slide2vec/__init__.py

@@ -21,13 +21,19 @@ from slide2vec.artifacts import (
     TileEmbeddingArtifact,
 )
 from slide2vec.runtime.dense_encode import DenseEncodeGeometry, DenseEncodeKit
+from slide2vec.encoders import (
+    EncoderProviderDiagnostic,
+    list_encoder_provider_diagnostics,
+)
 
 
-__version__ = "5.7.0"
+__version__ = "5.8.1"
 
 __all__ = [
     "Model",
     "list_models",
+    "EncoderProviderDiagnostic",
+    "list_encoder_provider_diagnostics",
     "Pipeline",
     "PreprocessingConfig",
     "DenseOptions",

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

@@ -3,6 +3,7 @@ import copy
 import logging
 import math
 import os
+import warnings
 from dataclasses import dataclass, field, replace
 from contextlib import contextmanager
 from pathlib import Path
@@ -23,6 +24,7 @@ from slide2vec.artifacts import (
 from slide2vec.configs.resources import load_config
 from slide2vec.encoders.registry import (
     encoder_registry,
+    list_encoder_provider_diagnostics,
     resolve_preprocessing_fields,
 )
 from slide2vec.encoders.validation import validate_encoder_config
@@ -1146,16 +1148,32 @@ def list_models(level: str | None = None) -> list[str]:
         level: Optional model level filter. Supported values are ``"tile"``,
             ``"slide"``, and ``"patient"``.
     """
-    if level is None:
-        return sorted(encoder_registry.names())
+    normalized_level = None
+    if level is not None:
+        normalized_level = str(level).strip().lower()
+        if normalized_level not in {"tile", "slide", "patient"}:
+            raise ValueError(
+                "list_models(level=...) must be one of: tile, slide, patient"
+            )
 
-    normalized_level = str(level).strip().lower()
-    if normalized_level not in {"tile", "slide", "patient"}:
-        raise ValueError("list_models(level=...) must be one of: tile, slide, patient")
+    names = encoder_registry.names()
+    diagnostics = list_encoder_provider_diagnostics()
+    if diagnostics:
+        detail = "; ".join(
+            f"'{item.provider_key}': {item.concise()}" for item in diagnostics
+        )
+        warnings.warn(
+            f"Skipped Encoder provider{'' if len(diagnostics) == 1 else 's'} {detail}",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+
+    if level is None:
+        return sorted(names)
 
     return sorted(
         name
-        for name in encoder_registry.names()
+        for name in names
         if encoder_registry.info(name)["level"] == normalized_level
     )
 

{slide2vec-5.7.0 → slide2vec-5.8.1}/slide2vec/encoders/__init__.py

@@ -15,9 +15,13 @@ from slide2vec.encoders.base import (
     resolve_requested_output_variant,
 )
 from slide2vec.encoders.registry import (
+    EncoderCapabilities,
+    EncoderProviderDiagnostic,
     encoder_registry,
+    list_encoder_provider_diagnostics,
     normalize_patch_size,
     register_encoder,
+    resolve_encoder_capabilities,
     resolve_encoder_output,
     resolve_patch_size,
     resolve_preprocessing_requirements,
@@ -29,6 +33,8 @@ from slide2vec.encoders import models  # noqa: F401
 
 __all__ = [
     "Encoder",
+    "EncoderCapabilities",
+    "EncoderProviderDiagnostic",
     "PatientEncoder",
     "TileEncoder",
     "SlideEncoder",
@@ -37,8 +43,10 @@ __all__ = [
     "resolve_recommended_dynamic_img_size",
     "resolve_requested_output_variant",
     "encoder_registry",
+    "list_encoder_provider_diagnostics",
     "normalize_patch_size",
     "register_encoder",
+    "resolve_encoder_capabilities",
     "resolve_patch_size",
     "resolve_preprocessing_requirements",
     "resolve_encoder_output",

{slide2vec-5.7.0 → slide2vec-5.8.1}/slide2vec/encoders/registry.py

@@ -1,10 +1,201 @@
 """Encoder registry with enforced metadata schema."""
 
+from dataclasses import dataclass
+from enum import Enum, auto
+from importlib import metadata as importlib_metadata
+import inspect
+from threading import Condition, RLock, get_ident
 from typing import Any
 
+from slide2vec.encoders.base import PatientEncoder, SlideEncoder, TileEncoder
 from slide2vec.runtime.registry import Registry
 
-encoder_registry = Registry("encoders")
+
+_ENCODER_ENTRY_POINT_GROUP = "slide2vec.encoders"
+
+
+class _DiscoveryState(Enum):
+    PENDING = auto()
+    RUNNING = auto()
+    COMPLETE = auto()
+    FAILED = auto()
+
+
+@dataclass(frozen=True)
+class EncoderProviderDiagnostic:
+    """Public, immutable description of one skipped installed provider."""
+
+    provider_key: str
+    provider: str
+    exception_type: str
+    message: str
+
+    def concise(self) -> str:
+        """Format the diagnostic without traceback details."""
+        return f"{self.exception_type}: {self.message}"
+
+
+def _installed_encoder_providers() -> list[importlib_metadata.EntryPoint]:
+    entry_points = importlib_metadata.entry_points()
+    providers = entry_points.select(group=_ENCODER_ENTRY_POINT_GROUP)
+    return sorted(providers, key=lambda provider: (provider.name, provider.value))
+
+
+class EncoderRegistry(Registry):
+    """Encoder registry with one lazy, process-global plugin discovery pass."""
+
+    def __init__(self) -> None:
+        super().__init__("encoders")
+        self._discovery_condition = Condition(RLock())
+        self._discovery_state = _DiscoveryState.PENDING
+        self._discovery_owner: int | None = None
+        self._discovery_error: BaseException | None = None
+        self._provider_diagnostics: tuple[EncoderProviderDiagnostic, ...] = ()
+
+    def _ensure_plugins_discovered(self) -> None:
+        current_thread = get_ident()
+        with self._discovery_condition:
+            while self._discovery_state is _DiscoveryState.RUNNING:
+                if self._discovery_owner == current_thread:
+                    return
+                self._discovery_condition.wait()
+            if self._discovery_state is _DiscoveryState.COMPLETE:
+                return
+            if self._discovery_state is _DiscoveryState.FAILED:
+                assert self._discovery_error is not None
+                raise self._discovery_error
+            self._discovery_state = _DiscoveryState.RUNNING
+            self._discovery_owner = current_thread
+
+        diagnostics: list[EncoderProviderDiagnostic] = []
+        try:
+            for entry_point in _installed_encoder_providers():
+                entries_before_provider = dict(self._entries)
+                try:
+                    entry_point.load()()
+                except BaseException as error:
+                    self._entries = entries_before_provider
+                    message = " ".join(str(error).split()) or "No error message"
+                    diagnostics.append(
+                        EncoderProviderDiagnostic(
+                            provider_key=entry_point.name,
+                            provider=entry_point.value,
+                            exception_type=type(error).__name__,
+                            message=message,
+                        )
+                    )
+        except BaseException as error:
+            with self._discovery_condition:
+                self._discovery_state = _DiscoveryState.FAILED
+                self._discovery_owner = None
+                self._discovery_error = error
+                self._discovery_condition.notify_all()
+            raise
+        else:
+            with self._discovery_condition:
+                self._provider_diagnostics = tuple(diagnostics)
+                self._discovery_state = _DiscoveryState.COMPLETE
+                self._discovery_owner = None
+                self._discovery_condition.notify_all()
+
+    def _before_read(self) -> None:
+        self._ensure_plugins_discovered()
+
+    def provider_diagnostics(self) -> tuple[EncoderProviderDiagnostic, ...]:
+        """Return an immutable snapshot of skipped provider diagnostics."""
+        self._ensure_plugins_discovered()
+        return self._provider_diagnostics
+
+    def _missing_preset_error(self, name: str) -> KeyError:
+        available = ", ".join(sorted(self._entries)) or "(none)"
+        message = f"'{name}' not found in encoders registry. Available: {available}"
+        if self._provider_diagnostics:
+            failures = "; ".join(
+                f"'{item.provider_key}' ({item.concise()})"
+                for item in self._provider_diagnostics
+            )
+            message += f". Skipped Encoder providers: {failures}"
+        return KeyError(message)
+
+    def require(self, name: str) -> type:
+        """Retrieve an Encoder class, including provider context when it is missing."""
+        self._ensure_plugins_discovered()
+        if name not in self._entries:
+            raise self._missing_preset_error(name)
+        return self._entries[name].cls
+
+    def info(self, name: str) -> dict[str, Any]:
+        """Return Encoder metadata, including provider context when it is missing."""
+        self._ensure_plugins_discovered()
+        if name not in self._entries:
+            raise self._missing_preset_error(name)
+        entry = self._entries[name]
+        return {"name": name, **entry.metadata}
+
+
+encoder_registry = EncoderRegistry()
+
+
+def list_encoder_provider_diagnostics() -> tuple[EncoderProviderDiagnostic, ...]:
+    """List deterministic diagnostics for installed providers skipped at discovery."""
+    return encoder_registry.provider_diagnostics()
+
+
+@dataclass(frozen=True)
+class EncoderCapabilities:
+    """Resolved, metadata-only preflight view of one registered Encoder preset."""
+
+    name: str
+    level: str
+    pooled: bool
+    dense: bool
+    attention: bool
+    slide: bool
+    patient: bool
+    patch_size: tuple[int, int] | None
+    tile_encoder: str | None
+    tile_encoder_output_variant: str | None
+
+
+def resolve_encoder_capabilities(encoder_name: str) -> EncoderCapabilities:
+    """Resolve supported extraction contracts without constructing the encoder."""
+    encoder_cls = encoder_registry.require(encoder_name)
+    metadata = encoder_registry.info(encoder_name)
+    _validate_encoder_capability_contract(encoder_name, encoder_cls, metadata)
+    level = resolve_encoder_level(encoder_name, metadata)
+    dense = all(_dense_class_contract(encoder_cls))
+    attention = _supports_attention(encoder_cls)
+    tile_encoder = None
+    tile_encoder_output_variant = None
+    if level in {"slide", "patient"}:
+        tile_encoder, tile_encoder_output_variant = (
+            _resolve_hierarchical_tile_dependency(encoder_name, metadata)
+        )
+        dependency_metadata = encoder_registry.info(tile_encoder)
+        dependency_level = resolve_encoder_level(tile_encoder, dependency_metadata)
+        if dependency_level != "tile":
+            raise ValueError(
+                f"Encoder '{encoder_name}' tile_encoder dependency '{tile_encoder}' "
+                f"must have level='tile', got level='{dependency_level}'."
+            )
+        dependency_output = resolve_tile_dependency_output(
+            encoder_name,
+            metadata=metadata,
+        )
+        tile_encoder_output_variant = str(dependency_output["output_variant"])
+        resolve_encoder_capabilities(tile_encoder)
+    return EncoderCapabilities(
+        name=encoder_name,
+        level=level,
+        pooled=issubclass(encoder_cls, TileEncoder),
+        dense=dense,
+        attention=attention,
+        slide=issubclass(encoder_cls, (SlideEncoder, PatientEncoder)),
+        patient=issubclass(encoder_cls, PatientEncoder),
+        patch_size=resolve_patch_size(encoder_name, metadata) if dense else None,
+        tile_encoder=tile_encoder,
+        tile_encoder_output_variant=tile_encoder_output_variant,
+    )
 
 
 def require_encoder_metadata_field(
@@ -31,6 +222,122 @@ def resolve_encoder_level(
     return level
 
 
+_DENSE_CLASS_MEMBERS = (
+    "encode_tiles_dense",
+    "patch_size",
+    "get_normalization_transform",
+)
+
+
+def _dense_class_contract(encoder_cls: type) -> tuple[bool, ...]:
+    if not issubclass(encoder_cls, TileEncoder):
+        return (False,) * len(_DENSE_CLASS_MEMBERS)
+    return tuple(
+        getattr(encoder_cls, member) is not getattr(TileEncoder, member)
+        for member in _DENSE_CLASS_MEMBERS
+    )
+
+
+def _supports_attention(encoder_cls: type) -> bool:
+    return (
+        issubclass(encoder_cls, TileEncoder)
+        and getattr(encoder_cls, "encode_tiles_attention")
+        is not TileEncoder.encode_tiles_attention
+    )
+
+
+def _format_names(names: list[str]) -> str:
+    if len(names) == 1:
+        return names[0]
+    if len(names) == 2:
+        return " and ".join(names)
+    return ", ".join(names[:-1]) + f", and {names[-1]}"
+
+
+def _validate_encoder_capability_contract(
+    encoder_name: str,
+    encoder_cls: type,
+    metadata: dict[str, Any],
+) -> None:
+    level = resolve_encoder_level(encoder_name, metadata)
+    required_base = {
+        "tile": TileEncoder,
+        "slide": SlideEncoder,
+        "patient": PatientEncoder,
+    }[level]
+    if not issubclass(encoder_cls, required_base):
+        raise ValueError(
+            f"Encoder '{encoder_name}' declares level='{level}', but class "
+            f"{encoder_cls.__name__} must subclass {required_base.__name__}."
+        )
+    if inspect.isabstract(encoder_cls):
+        missing = sorted(getattr(encoder_cls, "__abstractmethods__"))
+        raise ValueError(
+            f"Encoder '{encoder_name}' class {encoder_cls.__name__} is abstract; "
+            f"implement {_format_names(missing)} before registration."
+        )
+    if level in {"slide", "patient"}:
+        require_encoder_metadata_field(encoder_name, metadata, "tile_encoder")
+        require_encoder_metadata_field(
+            encoder_name,
+            metadata,
+            "tile_encoder_output_variant",
+        )
+    dense_members = _dense_class_contract(encoder_cls)
+    has_static_patch_size = metadata.get("patch_size") is not None
+    if any(dense_members) and not all(dense_members):
+        implemented = [
+            member
+            for member, is_implemented in zip(_DENSE_CLASS_MEMBERS, dense_members)
+            if is_implemented
+        ]
+        missing = [
+            member
+            for member, is_implemented in zip(_DENSE_CLASS_MEMBERS, dense_members)
+            if not is_implemented
+        ]
+        raise ValueError(
+            f"Encoder '{encoder_name}' has an incomplete dense class contract: "
+            f"{_format_names(implemented)} "
+            f"{'is' if len(implemented) == 1 else 'are'} overridden, but "
+            f"{_format_names(missing)} "
+            f"{'is' if len(missing) == 1 else 'are'} inherited as unsupported. "
+            "Override all three dense members together and declare patch_size metadata."
+        )
+    if has_static_patch_size and not all(dense_members):
+        raise ValueError(
+            f"Encoder '{encoder_name}' has an inconsistent dense contract: "
+            "patch_size metadata is declared, but the class must also override "
+            "encode_tiles_dense, patch_size, and get_normalization_transform."
+        )
+    if all(dense_members) and not has_static_patch_size:
+        raise ValueError(
+            f"Encoder '{encoder_name}' implements the dense class contract but does "
+            "not declare patch_size metadata. Add the encoder's static patch size "
+            "to @register_encoder."
+        )
+    if has_static_patch_size:
+        patch = metadata["patch_size"]
+        patch_values = patch if isinstance(patch, tuple) else (patch, patch)
+        valid_patch = (
+            len(patch_values) == 2
+            and all(type(value) is int and value > 0 for value in patch_values)
+        )
+        if not valid_patch:
+            raise ValueError(
+                f"Encoder '{encoder_name}' must declare patch_size as a positive int "
+                f"or pair of positive ints; got {patch!r}."
+            )
+    if _supports_attention(encoder_cls) and not (
+        all(dense_members) and has_static_patch_size
+    ):
+        raise ValueError(
+            f"Encoder '{encoder_name}' overrides encode_tiles_attention without a "
+            "complete dense contract. Attention maps require encode_tiles_dense, "
+            "patch_size, get_normalization_transform, and static patch_size metadata."
+        )
+
+
 def register_encoder(
     name: str,
     *,
@@ -66,9 +373,9 @@ def register_encoder(
             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.
+        level: Encoder output level ("tile", "slide", or "patient").
+        tile_encoder: Registered tile encoder dependency for slide/patient models.
+        tile_encoder_output_variant: Fixed tile output variant for slide/patient models.
         supported_spacing_um: The spacing(s) in µm/px the model was trained/validated
             for; :func:`validate_encoder_config` rejects requests outside this set
             unless ``allow_non_recommended_settings=True``. ``None`` marks a
@@ -111,7 +418,13 @@ def register_encoder(
         "precision": precision,
         "source": source,
     }
-    return encoder_registry.register_decorator(name, metadata=metadata)
+
+    def decorator(encoder_cls: type) -> type:
+        _validate_encoder_capability_contract(name, encoder_cls, metadata)
+        encoder_registry.register(name, encoder_cls, metadata=metadata)
+        return encoder_cls
+
+    return decorator
 
 
 def resolve_variable_input_capability(
@@ -372,16 +685,8 @@ def resolve_tile_dependency_output(
         resolved["encoder_name"] = encoder_name
         return resolved
 
-    # Both "slide" and "patient" declare tile_encoder / tile_encoder_output_variant.
-    tile_encoder_name = str(
-        require_encoder_metadata_field(encoder_name, info, "tile_encoder")
-    )
-    tile_encoder_output_variant = str(
-        require_encoder_metadata_field(
-            encoder_name,
-            info,
-            "tile_encoder_output_variant",
-        )
+    tile_encoder_name, tile_encoder_output_variant = (
+        _resolve_hierarchical_tile_dependency(encoder_name, info)
     )
     tile_info = encoder_registry.info(tile_encoder_name)
     resolved = resolve_encoder_output(
@@ -391,3 +696,21 @@ def resolve_tile_dependency_output(
     )
     resolved["encoder_name"] = tile_encoder_name
     return resolved
+
+
+def _resolve_hierarchical_tile_dependency(
+    encoder_name: str,
+    metadata: dict[str, Any],
+) -> tuple[str, str]:
+    """Read the fixed tile preset and output variant for a hierarchical encoder."""
+    tile_encoder_name = str(
+        require_encoder_metadata_field(encoder_name, metadata, "tile_encoder")
+    )
+    tile_encoder_output_variant = str(
+        require_encoder_metadata_field(
+            encoder_name,
+            metadata,
+            "tile_encoder_output_variant",
+        )
+    )
+    return tile_encoder_name, tile_encoder_output_variant