pathforge.utils

Registries, optional package guards, constants, and helper utilities.

Registries

class pathforge.utils.registries.BackendCatalogEntry

Bases: object

One backend-aware catalog entry for user-selectable components.

Variables:

• name (str) – User-facing model or extractor name.

• backend (str) – Backend required to use this entry, such as native, torchmil, mil-lab, timm, or lazyslide.

• config_field (str) – Config field used to select this entry.

• source (str) – Origin namespace that provides the entry.

• available (bool) – Whether the required backend is currently installed and the entry can be selected in this environment.

Example

entries = list_mil_models()
torchmil_names = [item.name for item in entries if item.backend == "torchmil"]

name: str

backend: str

config_field: str

source: str

available: bool

__init__(name: str, backend: str, config_field: str, source: str, available: bool) → None

Parameters:

• name (str)

• backend (str)

• config_field (str)

• source (str)

• available (bool)

Return type:

None

pathforge.utils.registries.timm_model_names() → set[str]

Return the TIMM model names visible in the current Python environment.

Return type:

set[str]

pathforge.utils.registries.lazyslide_model_names() → set[str]

Return the LazySlide model names visible in the current Python environment.

Return type:

set[str]

pathforge.utils.registries.registered_feature_extractor_names() → set[str]

Best-effort extraction of names currently registered in PathForge FEATURE_EXTRACTORS.

Return type:

set[str]

pathforge.utils.registries.available_feature_extractor_names() → dict[str, set[str]]

Return extractor names grouped by the backend that provides them.

Return type:

dict[str, set[str]]

pathforge.utils.registries.all_feature_extractor_names() → set[str]

Return the union of PathForge-native and dynamically discovered extractors.

Return type:

set[str]

pathforge.utils.registries.is_feature_extractor_available(name: str) → bool

Used by config validation without importing timm/torchvision at module import time.

Parameters:

name (str)

Return type:

bool

pathforge.utils.registries.populate_dynamic_registries() → None

Populate optional backend registries with entries from installed packages.

IMPORTANT: - This is NOT called automatically at import time. - Call it explicitly in CLI/policy paths that require optional backends.

Return type:

None

pathforge.utils.registries.list_feature_extractors() → list[BackendCatalogEntry]

List user-selectable feature extractors across supported backends.

Returns:

Catalog entries sorted by backend and name.

For optional backends such as timm and lazyslide, only installed catalogs can be enumerated because their model lists come from the backend package itself.

Return type:

list[BackendCatalogEntry]

Example

entries = list_feature_extractors()
lazyslide_only = [item.name for item in entries if item.backend == "lazyslide"]

pathforge.utils.registries.list_mil_models() → list[BackendCatalogEntry]

List user-selectable MIL models across native and adapter backends.

Returns:

Catalog entries sorted by backend and name.

Native PathForge MIL models are always listed. Backend-adapter model catalogs are listed even when their backend is unavailable so the caller can present supported choices together with installation requirements.

Return type:

list[BackendCatalogEntry]

Example

entries = list_mil_models()
mil_lab_models = [item.name for item in entries if item.backend == "mil-lab"]

pathforge.utils.registries.resolve_mil_model_backend(name: str) → str

Return the backend providing a selectable MIL model name.

The generic torchmil and mil-lab keys remain supported for legacy configs. New benchmark grids should use a concrete name returned by list_mil_models().

Parameters:

name (str)

Return type:

str

class pathforge.utils.registry.Registry

Bases: RegistryBase

Minimal string-to-callable registry used for runtime plugin lookup.

__init__() → None

Return type:

None

register(name: str)

Register a plugin with a given key.

Parameters:

name (str)

get(name: str) → Callable[[...], T]

Retrieve a plugin by its key.

Parameters:

name (str)

Return type:

Callable[[…], T]

list_plugins() → Sequence[str]

List all registered plugin keys.

Return type:

Sequence[str]

is_available(key: str) → bool

Check if a plugin is available.

Parameters:

key (str)

Return type:

bool

Available registries:

Registry	Purpose
MODELS	MIL and slide-level model classes.
LOSSES	Loss functions for all task types.
TRAINERS	Trainer implementations (e.g. "lightning").
FEATURE_EXTRACTORS	Feature extraction backends.
SLIDE_PROCESSORS	WSI loading backends.
CLASSIFICATION_METRICS	Classification metric backends.
SURVIVAL_METRICS	Survival metric backends.
SURVIVAL_LOSSES	Survival loss backends.
EXPLAINERS	Heatmap/explainability methods.

Optional Package Guards

class pathforge.utils.optional.torchmil.TorchMILModules

Bases: object

Lazy references to installed TorchMIL modules.

Variables:

• root (types.ModuleType) – Imported torchmil package module.

• models (types.ModuleType) – Imported torchmil.models module. Expected to expose model classes such as ABMIL.

• data (types.ModuleType) – Imported torchmil.data module. Expected to expose collate_fn accepting a list of bag dictionaries and returning a padded batch with X shaped [B, N_max, D] and mask shaped [B, N_max].

• datasets (types.ModuleType) – Imported torchmil.datasets module.

Example

from pathforge.utils.optional.torchmil import load_torchmil_modules

modules = load_torchmil_modules()
batch = modules.data.collate_fn([{"X": x0, "Y": y0}, {"X": x1, "Y": y1}])
model_cls = getattr(modules.models, "ABMIL")

Raises:

RuntimeError – If TorchMIL is not installed.

root: ModuleType

models: ModuleType

data: ModuleType

datasets: ModuleType

__init__(root: ModuleType, models: ModuleType, data: ModuleType, datasets: ModuleType) → None

Parameters:

• root (ModuleType)

• models (ModuleType)

• data (ModuleType)

• datasets (ModuleType)

Return type:

None

pathforge.utils.optional.torchmil.is_torchmil_available() → bool

Return whether torchmil can be imported without importing it eagerly.

Return type:

bool

pathforge.utils.optional.torchmil.is_torchmetrics_available() → bool

Return whether torchmetrics can be imported without importing it eagerly.

Return type:

bool

pathforge.utils.optional.torchmil.is_torchsurv_available() → bool

Return whether torchsurv can be imported without importing it eagerly.

Return type:

bool

pathforge.utils.optional.torchmil.require_torchmil(feature: str) → None

Raise an install hint when a TorchMIL-only feature is requested.

Parameters:

feature (str) – Human-readable feature name, for example "MIL backend 'torchmil'" or "TorchMIL heatmap explainer".

Raises:

RuntimeError – If torchmil is not installed.

Return type:

None

pathforge.utils.optional.torchmil.require_torchmetrics(feature: str = 'Classification metrics backend') → None

Raise an install hint when TorchMetrics-backed classification metrics are used.

Parameters:

feature (str)

Return type:

None

pathforge.utils.optional.torchmil.require_torchsurv(feature: str = 'Continuous survival backend') → None

Raise an install hint when TorchSurv-backed survival functionality is used.

Parameters:

feature (str)

Return type:

None

pathforge.utils.optional.torchmil.load_torchmil_modules() → TorchMILModules

Import TorchMIL modules lazily and return stable module references.

Returns:

Imported root, models, data, and datasets modules.

Return type:

TorchMILModules

Raises:

RuntimeError – If torchmil or an expected TorchMIL submodule is missing.

class pathforge.utils.optional.mil_lab.MILLabModules

Bases: object

Lazy references to installed MIL-Lab modules.

builder: ModuleType

__init__(builder: ModuleType) → None

Parameters:

builder (ModuleType)

Return type:

None

pathforge.utils.optional.mil_lab.is_mil_lab_available() → bool

Return whether MIL-Lab can be imported without importing it eagerly.

Return type:

bool

pathforge.utils.optional.mil_lab.require_mil_lab(feature: str) → None

Raise an install hint when a MIL-Lab-only feature is requested.

Parameters:

feature (str)

Return type:

None

pathforge.utils.optional.mil_lab.load_mil_lab_modules() → MILLabModules

Import MIL-Lab builder modules lazily and return stable references.

Return type:

MILLabModules

Constants

Shared constants used across PathForge.

Logging

I/O Utilities

Serialization

pathforge.utils.serialization.push_to_hub(local_dir: str, repo_id: str, private: bool = True) → None

Create a Hub repository when needed and upload one local artifact folder.

Parameters:

• local_dir (str)

• repo_id (str)

• private (bool)

Return type:

None