Slide Retrieval¶

Public contracts for building retrieval representations, searching reference collections, and rendering retrieval results.

Types and configuration¶

class pathforge.slide_retrieval.types.RetrievalItemMetadata[source]¶

Bases: MutableMapping[str, Any]

Backward-compatible metadata container for retrieval items.

category: str | None¶

patient_id: str | None¶

case_id: str | None¶

member_ids: list[str]¶

extra: dict[str, Any]¶

__init__(category: str | None = None, patient_id: str | None = None, case_id: str | None = None, member_ids: list[str] = <factory>, extra: dict[str, ~typing.Any]=<factory>) → None¶

Parameters:

category (str | None)
patient_id (str | None)
case_id (str | None)
member_ids (list[str])
extra (dict[str, Any])

Return type:

None

class pathforge.slide_retrieval.types.RetrievalItemIdentity[source]¶

Bases: object

Minimal runtime identity for one retrieval item.

sample_id: str¶

exclusion_key: str | None¶

to_dict() → dict[str, Any][source]¶

Return type:: dict[str, Any]

classmethod from_dict(data: Mapping[str, Any] | None, *, fallback_sample_id: str | None = None) → RetrievalItemIdentity[source]¶

Parameters:

data (Mapping[str, Any] | None)
fallback_sample_id (str | None)

Return type:

RetrievalItemIdentity

__init__(sample_id: str, exclusion_key: str | None = None) → None¶

Parameters:

sample_id (str)
exclusion_key (str | None)

Return type:

None

class pathforge.slide_retrieval.types.SlideRetrievalManifest[source]¶

Bases: object

Save-only manifest for one retrieval run.

tiling_id: str¶

aggregation_level: str¶

feature_extraction: str¶

slide_representation: str¶

search_method: str¶

representation_id: str¶

exclusion_level: Literal['none', 'slide', 'case', 'patient']¶

num_queries: int¶

num_reference_items: int¶

top_k_saved: int¶

slide_representation_params: dict[str, Any]¶

search_params: dict[str, Any]¶

combo_cfg: dict[str, Any]¶

query_sample_ids: list[str]¶

reference_sample_ids: list[str]¶

to_dict() → dict[str, Any][source]¶

Return type:: dict[str, Any]

build_run_hash(length: int = 8) → str[source]¶

Parameters:: length (int)
Return type:: str

__init__(tiling_id: str, aggregation_level: str, feature_extraction: str, slide_representation: str, search_method: str, representation_id: str, exclusion_level: ~typing.Literal['none', 'slide', 'case', 'patient'], num_queries: int, num_reference_items: int, top_k_saved: int, slide_representation_params: dict[str, ~typing.Any] = <factory>, search_params: dict[str, ~typing.Any] = <factory>, combo_cfg: dict[str, ~typing.Any] = <factory>, query_sample_ids: list[str] = <factory>, reference_sample_ids: list[str] = <factory>) → None¶

Parameters:

tiling_id (str)
aggregation_level (str)
feature_extraction (str)
slide_representation (str)
search_method (str)
representation_id (str)
exclusion_level (Literal['none', 'slide', 'case', 'patient'])
num_queries (int)
num_reference_items (int)
top_k_saved (int)
slide_representation_params (dict[str, Any])
search_params (dict[str, Any])
combo_cfg (dict[str, Any])
query_sample_ids (list[str])
reference_sample_ids (list[str])

Return type:

None

class pathforge.slide_retrieval.hyperparams.HyperParam[source]¶

Bases: object

Declarative hyperparameter marker for slide-retrieval strategies.

Example: .. code-block:: python

class ExampleStrategy:
k = HyperParam(int, default=5, min=1, help=”Retrieval depth.”)

hp_type: type[Any] | None¶

default: Any¶

min: int | float | None¶

max: int | float | None¶

choices: tuple[Any, ...] | None¶

help: str¶

to_spec() → dict[str, Any][source]¶

Convert the declaration to the legacy registry-friendly metadata shape.

Outputs: - dict[str, Any] with only populated metadata fields.

Return type:: dict[str, Any]

Parameters:

hp_type (type[Any] | None)
default (Any)
min (int | float | None)
max (int | float | None)
choices (tuple[Any, ...] | None)
help (str)

Return type:

None

pathforge.slide_retrieval.hyperparams.collect_hyperparams(strategy_cls: type[Any]) → dict[str, HyperParam][source]¶

Collect hyperparameters across a strategy class hierarchy.

Child declarations override parent declarations with the same name.

Parameters:: strategy_cls (type[Any])
Return type:: dict[str, HyperParam]

pathforge.slide_retrieval.hyperparams.resolve_hyperparam(*, name: str, declaration: HyperParam, params: dict[str, Any]) → Any[source]¶

Resolve one effective hyperparameter value from user params and defaults.

Parameters:

name (str) – Hyperparameter field name.
declaration (HyperParam) – Declarative metadata for the hyperparameter.
params (dict[str, Any]) – Runtime override mapping.

Returns:

Validated and normalized effective value.

Return type:

Any

pathforge.slide_retrieval.io.build_slide_retrieval_inference_output_root(*, inference_run_root: str | Path, tiling_id: str, feature_name: str, slide_representation: str, search_method: str, run_hash: str) → Path[source]¶

Build the flat inference output root for one slide-retrieval combo.

The output path contains a tiling/feature directory followed by a representation/search directory with a 12-character run hash.

Parameters:

inference_run_root (str | Path)
tiling_id (str)
feature_name (str)
slide_representation (str)
search_method (str)
run_hash (str)

Return type:

Path

pathforge.slide_retrieval.io.build_slide_retrieval_output_root(*, project_root: str, tiling_id: str, feature_name: str, slide_representation: str, search_method: str) → Path[source]¶

Build the canonical search-specific output root for one slide-retrieval combo.

Inputs: - project_root: experiment project root. - tiling_id: canonical tiling identifier. - feature_name: canonical stored feature name. - slide_representation: retrieval representation strategy name. - search_method: search strategy name.

Returns: - Path to the search-specific slide-retrieval output root.

Parameters:

project_root (str)
tiling_id (str)
feature_name (str)
slide_representation (str)
search_method (str)

Return type:

Path

pathforge.slide_retrieval.io.build_slide_retrieval_representation_root(*, project_root: str, tiling_id: str, feature_name: str, slide_representation: str) → Path[source]¶

Build the canonical representation-specific root for slide-retrieval outputs.

Layout: - eval_slide_retrieval/<tiling+feature>/<retrieval_representation>/

Parameters:

project_root (str)
tiling_id (str)
feature_name (str)
slide_representation (str)

Return type:

Path

pathforge.slide_retrieval.io.load_sample_patch_coords(*, sample: Any, tile_id: str, dtype: dtype | type[integer[Any]] = np.int32) → ndarray[source]¶

Load patch coordinates for one sample from its retrieval artifact.

Parameters:

sample (Any)
tile_id (str)
dtype (dtype | type[integer[Any]])

Return type:

ndarray

pathforge.slide_retrieval.io.load_slide_retrieval_representation(*, retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, entry_id: str | None) → RetrievalRepresentation | None[source]¶

Load a stored slide-retrieval representation from disk.

Parameters:

retrieval_artifact (FileHandleH5)
tile_id (str)
representation_id (str)
entry_id (str | None)

Return type:

RetrievalRepresentation | None

pathforge.slide_retrieval.io.save_slide_retrieval_representation(*, retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, entry_id: str | None, representation: RetrievalRepresentation, params: dict[str, Any] | None = None) → None[source]¶

Persist a slide-retrieval representation to disk.

Parameters:

retrieval_artifact (FileHandleH5)
tile_id (str)
representation_id (str)
entry_id (str | None)
representation (RetrievalRepresentation)
params (dict[str, Any] | None)

Return type:

None

pathforge.slide_retrieval.io.write_slide_retrieval_manifest(path: str | Path, manifest: SlideRetrievalManifest | Mapping[str, Any]) → None[source]¶

Write the slide-retrieval run manifest as JSON.

Parameters:

path (str | Path)
manifest (SlideRetrievalManifest | Mapping[str, Any])

Return type:

None

pathforge.slide_retrieval.io.write_slide_retrieval_results_csv(path: str | Path, results: list[SearchResult]) → None[source]¶

Backward-compatible wrapper that now writes Excel ranked results.

Parameters:

path (str | Path)
results (list[SearchResult])

Return type:

None

pathforge.slide_retrieval.io.write_slide_retrieval_results_xlsx(path: str | Path, results: list[SearchResult]) → None[source]¶

Write ranked slide-retrieval query results to an Excel workbook.

Parameters:

path (str | Path)
results (list[SearchResult])

Return type:

None

pathforge.slide_retrieval.io.resolve_slide_retrieval_results_path(path: str | Path) → Path[source]¶

Resolve the ranked-results file for a run, preferring Excel over legacy CSV.

Parameters:: path (str | Path)
Return type:: Path

pathforge.slide_retrieval.io.read_slide_retrieval_results_csv(path: str | Path) → list[SearchResult][source]¶

Read one saved slide-retrieval ranked-results CSV.

Inputs: - path: CSV path written by write_slide_retrieval_results_csv.

Returns: - List of SearchResult objects with ranked hits reconstructed from CSV.

Parameters:: path (str | Path)
Return type:: list[SearchResult]

pathforge.slide_retrieval.io.write_metrics_csv(path: str | Path, metrics: Mapping[str, Mapping[str, Any]]) → None[source]¶

Write legacy flat metric rows for retrieval metrics.

Inputs: - path: destination CSV path. - metrics: mapping from metric name to JSON-like payload.

Returns: - None. Writes one flat row per metric scope.

Parameters:

path (str | Path)
metrics (Mapping[str, Mapping[str, Any]])

Return type:

None

Representation strategies¶

class pathforge.slide_retrieval.representation_strategies.base.BaseRetrievalRepresentationStrategy[source]¶

Bases: object

Base class for retrieval representation strategies.

name: str = ''¶

supported_feature_levels: frozenset[Literal['patch', 'slide']] = frozenset({})¶

output_representation_kind: Literal['single_vector', 'multi_vector', 'patch_vector'] | str = ''¶

__init__(params: dict[str, Any] | None = None, **kwargs: Any) → None[source]¶

Parameters:

params (dict[str, Any] | None)
kwargs (Any)

Return type:

None

classmethod hyperparam_spec() → dict[str, dict[str, Any]][source]¶

Return the hyperparameter schema for this strategy.

Return type:: dict[str, dict[str, Any]]

hyperparam_values() → dict[str, Any][source]¶

Return the effective hyperparameter values for this instance.

Return type:: dict[str, Any]

supports_feature_level(feature_level: str) → bool[source]¶

Return whether this strategy supports the provided feature level.

Parameters:: feature_level (str)
Return type:: bool

validate_feature_level(feature_level: str) → None[source]¶

Validate that this strategy supports the provided feature level.

Parameters:: feature_level (str)
Return type:: None

static as_numpy_feature_matrix(bag: Tensor | ndarray | Any) → ndarray[source]¶

Convert one tensor-like bag into a 2D float32 NumPy matrix.

Inputs: - bag: tensor-like matrix with shape (N, D).

Returns: - np.ndarray[float32] with shape (N, D).

Parameters:: bag (Tensor | ndarray | Any)
Return type:: ndarray

load_sample(*, index: int, sample: BagSample, base_dataset: BagDataset) → dict[str, Any][source]¶

Load the default retrieval inputs for one sample.

Parameters:

index (int) – Integer position inside the bound retrieval dataset.
sample (BagSample) – Bag sample carrying membership and artifact paths.
base_dataset (BagDataset) – Dataset exposing load_bag.

Returns:

Minimal payload required by run. Subclasses may add retrieval-specific inputs.

Return type:

dict[str, Any]

Example:

payload = strategy.load_sample(
    index=0,
    sample=sample,
    base_dataset=bag_dataset,
)

run(bag: Tensor, sample=None, **kwargs) → RetrievalRepresentation[source]¶

Compute a retrieval representation from one bag.

Parameters:: bag (Tensor)
Return type:: RetrievalRepresentation

class pathforge.slide_retrieval.representation_strategies.types.RetrievalRepresentation[source]¶

Bases: object

Container for one computed retrieval representation.

sample_id: str¶

data: Any¶

representation_type: str¶

metadata: RetrievalItemMetadata¶

exclusion_key: str | None¶

additional_data: dict[str, Any]¶

property row_count: int¶

Return the number of vectors represented by data.

Patch and multi-vector representations are two-dimensional matrices; single-vector representations deliberately report one row so callers can apply their explicit aggregation policy.

__init__(sample_id: str, data: Any, representation_type: str = 'patch_vector', metadata: RetrievalItemMetadata = <factory>, exclusion_key: str | None = None, additional_data: dict[str, ~typing.Any]=<factory>) → None¶

Parameters:

sample_id (str)
data (Any)
representation_type (str)
metadata (RetrievalItemMetadata)
exclusion_key (str | None)
additional_data (dict[str, Any])

Return type:

None

pathforge.slide_retrieval.representation_strategies.registry.register_representation_strategy(name: str) → Callable[[type['BaseRetrievalRepresentationStrategy']], type['BaseRetrievalRepresentationStrategy']][source]¶

Decorator to register a retrieval representation strategy class.

Parameters:: name (str)
Return type:: Callable[[type[‘BaseRetrievalRepresentationStrategy’]], type[‘BaseRetrievalRepresentationStrategy’]]

pathforge.slide_retrieval.representation_strategies.registry.build_representation_strategy(name: str, *args, **kwargs) → BaseRetrievalRepresentationStrategy[source]¶

Resolve and instantiate a registered retrieval representation strategy.

Parameters:: name (str)
Return type:: BaseRetrievalRepresentationStrategy

pathforge.slide_retrieval.representation_strategies.registry.get_representation_strategy(name: str) → type['BaseRetrievalRepresentationStrategy'][source]¶

Get a registered retrieval representation strategy class by name.

Parameters:: name (str)
Return type:: type[‘BaseRetrievalRepresentationStrategy’]

pathforge.slide_retrieval.representation_strategies.registry.get_representation_strategy_output_kind(name: str) → str[source]¶

Return the output representation kind declared by a strategy class.

Parameters:: name (str)
Return type:: str

pathforge.slide_retrieval.representation_strategies.registry.get_representation_strategy_supported_feature_levels(name: str) → frozenset[str][source]¶

Return feature levels supported by a representation strategy class.

Parameters:: name (str)
Return type:: frozenset[str]

pathforge.slide_retrieval.representation_strategies.registry.is_representation_strategy_available(name: str) → bool[source]¶

Check whether a retrieval representation is registered.

Parameters:: name (str)
Return type:: bool

pathforge.slide_retrieval.representation_strategies.registry.list_representation_strategies() → list[str][source]¶

Return all registered retrieval representation names in sorted order.

Return type:: list[str]

pathforge.slide_retrieval.representation_strategies.registry.import_representation_strategy_modules(package_name: str = 'pathforge.slide_retrieval.representation_strategies') → None[source]¶

Import the canonical retrieval representation strategy package.

Inputs: - package_name: str package root containing the strategies subpackage.

Returns: - None. Import side effects register all retrieval representation strategies.

Example: .. code-block:: python

import_representation_strategy_modules()

Parameters:: package_name (str)
Return type:: None

pathforge.slide_retrieval.representation_strategies.registry.get_representation_strategy_hyperparams(name: str) → dict[str, Any][source]¶

Return the hyperparameter schema for a registered retrieval representation.

Parameters:: name (str)
Return type:: dict[str, Any]

pathforge.slide_retrieval.representation_strategies.registry.get_representation_strategy_defaults(name: str) → dict[str, Any][source]¶

Return the default hyperparameter values for a registered retrieval representation.

Parameters:: name (str)
Return type:: dict[str, Any]

pathforge.slide_retrieval.representation_strategies.registry.get_representation_strategy_values(name: str, params: dict[str, Any] | None = None) → dict[str, Any][source]¶

Return effective hyperparameter values without instantiating the strategy.

Parameters:

name (str)
params (dict[str, Any] | None)

Return type:

dict[str, Any]

pathforge.slide_retrieval.representation_strategies.registry.describe_all_representations_strategies() → dict[str, dict[str, dict[str, Any]]][source]¶

Return the hyperparameter schema for all registered retrieval representations.

Return type:: dict[str, dict[str, dict[str, Any]]]

pathforge.slide_retrieval.representation_strategies.storage.build_retrieval_representation_artifact_path(artifacts_dir: str | Path, aggregation_level: str, sample_id: str) → Path[source]¶

Build the H5 artifact path for one retrieval representation sample.

Parameters:

artifacts_dir (str | Path)
aggregation_level (str)
sample_id (str)

Return type:

Path

pathforge.slide_retrieval.representation_strategies.storage.build_retrieval_representation_id(feature_extraction: str, retrieval_representation: str, params: dict[str, Any] | None = None) → str[source]¶

Build a stable retrieval representation ID.

The identifier shape matches the repository canonical helper contract: {feature_extraction}__{retrieval_representation}__{params_hash16}.

Parameters:

feature_extraction (str)
retrieval_representation (str)
params (dict[str, Any] | None)

Return type:

str

pathforge.slide_retrieval.representation_strategies.storage.build_retrieval_representation_entry_id(slide_ids: list[str], *, aggregation_level: str | None = None) → str | None[source]¶

Build an optional entry ID from member slide IDs.

For slide-level aggregation this returns None, meaning the representation data is stored directly under {representation_id} without an intermediate member-entry layer.

Parameters:

slide_ids (list[str])
aggregation_level (str | None)

Return type:

str | None

pathforge.slide_retrieval.representation_strategies.mean_rgb.resolve_sample_patch_mean_rgb(*, sample: Any, bag_id: str, config: Any) → ndarray[source]¶

Load or materialize row-aligned patch mean RGB descriptors for one sample.

Parameters:

sample (Any) – Object exposing slide IDs, artifact paths, and metadata.
bag_id (str) – Canonical tiling identifier used in the slide H5 layout.
config (Any) – Configuration containing slide-processing and dataset entries.

Returns:

float32 array shaped (N, 3) and aligned with the retrieval bag.

Return type:

ndarray

Example:

mean_rgb = resolve_sample_patch_mean_rgb(
    sample=sample,
    bag_id="256px_0.5mpp",
    config=cfg,
)

pathforge.slide_retrieval.representation_strategies.mean_rgb.load_or_create_slide_patch_mean_rgb(*, slide_artifact: FileHandleH5, retrieval_artifact_path: Path, slide_path: Path | None, bag_id: str, slide_processor: SlideProcessorBase, slide_id: str) → ndarray[source]¶

Resolve one slide-level mean RGB descriptor matrix using an open slide H5 handle.

Inputs: - slide_artifact: open slide artifact handle containing coords. - retrieval_artifact_path: retrieval artifact path storing descriptors. - slide_path: source slide path used when descriptors must be created. - bag_id: canonical tiling identifier. - slide_processor: backend implementation used to read patch regions. - slide_id: slide identifier for error messages.

Returns: - np.ndarray[float32] with shape (N, 3).

Parameters:

slide_artifact (FileHandleH5)
retrieval_artifact_path (Path)
slide_path (Path | None)
bag_id (str)
slide_processor (SlideProcessorBase)
slide_id (str)

Return type:

ndarray

Search strategies¶

class pathforge.slide_retrieval.search_strategies.base.BaseSearchStrategy[source]¶

Bases: object

Base class for search strategies.

name: str = ''¶

supported_representation_kinds: frozenset[Literal['single_vector', 'multi_vector', 'patch_vector']] = frozenset({})¶

__init__(params: dict[str, Any] | None = None, **kwargs) → None[source]¶

Parameters:: params (dict[str, Any] | None)
Return type:: None

classmethod hyperparam_spec() → dict[str, dict[str, Any]][source]¶

Return the hyperparameter schema for this strategy.

Return type:: dict[str, dict[str, Any]]

hyperparam_values() → dict[str, Any][source]¶

Return the effective hyperparameter values for this instance.

Return type:: dict[str, Any]

supports_representation_kind(representation_kind: str) → bool[source]¶

Return whether this strategy supports the provided representation kind.

Parameters:: representation_kind (str)
Return type:: bool

validate_representation_kind(representation_kind: str) → None[source]¶

Validate that this strategy supports the provided representation kind.

Parameters:: representation_kind (str)
Return type:: None

build_database(database_representations: list[RetrievalRepresentation]) → None[source]¶

Build the searchable database from retrieval representations.

Parameters:: database_representations (list[RetrievalRepresentation])
Return type:: None

build_database_item(representation: RetrievalRepresentation) → SearchDatabaseItem[source]¶

Convert one retrieval representation into a searchable database item.

Parameters:: representation (RetrievalRepresentation)
Return type:: SearchDatabaseItem

prepare_query(query_representation: RetrievalRepresentation) → SearchDatabaseItem[source]¶

Convert one query retrieval representation into a searchable query item.

Parameters:: query_representation (RetrievalRepresentation)
Return type:: SearchDatabaseItem

build_index() → None[source]¶

Optional hook to prepare the searchable database.

Return type:: None

filter_database_by_exclusion_key(query_item: SearchDatabaseItem, database_items: list[SearchDatabaseItem] | None = None) → list[SearchDatabaseItem][source]¶

Exclude database items that share the query exclusion key.

Parameters:

query_item (SearchDatabaseItem)
database_items (list[SearchDatabaseItem] | None)

Return type:

list[SearchDatabaseItem]

search(query_representation: RetrievalRepresentation, **kwargs) → SearchResult[source]¶

Run search for one query against the current database.

Parameters:: query_representation (RetrievalRepresentation)
Return type:: SearchResult

rank(query_item: SearchDatabaseItem, database_items: list[SearchDatabaseItem], **kwargs) → list[SearchHit][source]¶

Rank database items for one prepared query.

Parameters:

query_item (SearchDatabaseItem)
database_items (list[SearchDatabaseItem])

Return type:

list[SearchHit]

class pathforge.slide_retrieval.search_strategies.types.SearchDatabaseItem[source]¶

Bases: object

Container for one searchable item.

sample_id: str¶

data: Any¶

metadata: RetrievalItemMetadata¶

exclusion_key: str | None¶

additional_data: dict[str, Any]¶

property item_id: str¶

__init__(sample_id: str, data: Any, metadata: RetrievalItemMetadata = <factory>, exclusion_key: str | None = None, additional_data: dict[str, ~typing.Any]=<factory>) → None¶

Parameters:

sample_id (str)
data (Any)
metadata (RetrievalItemMetadata)
exclusion_key (str | None)
additional_data (dict[str, Any])

Return type:

None

class pathforge.slide_retrieval.search_strategies.types.SearchHit[source]¶

Bases: object

Container for one ranked retrieval result.

sample_id: str¶

score: float¶

rank: int¶

metadata: RetrievalItemMetadata¶

property item_id: str¶

__init__(sample_id: str, score: float, rank: int, metadata: RetrievalItemMetadata = <factory>) → None¶

Parameters:

sample_id (str)
score (float)
rank (int)
metadata (RetrievalItemMetadata)

Return type:

None

class pathforge.slide_retrieval.search_strategies.types.SearchResult[source]¶

Bases: object

Container for the output of one query.

query_sample_id: str¶

hits: list[SearchHit]¶

metadata: dict[str, Any]¶

property query_id: str¶

__init__(query_sample_id: str, hits: list[~pathforge.slide_retrieval.search_strategies.types.SearchHit], metadata: dict[str, ~typing.Any] = <factory>) → None¶

Parameters:

query_sample_id (str)
hits (list[SearchHit])
metadata (dict[str, Any])

Return type:

None

pathforge.slide_retrieval.search_strategies.registry.register_search_strategy(name: str) → Callable[[type['BaseSearchStrategy']], type['BaseSearchStrategy']][source]¶

Decorator to register a search strategy class.

Parameters:: name (str)
Return type:: Callable[[type[‘BaseSearchStrategy’]], type[‘BaseSearchStrategy’]]

pathforge.slide_retrieval.search_strategies.registry.build_search_strategy(name: str, *args, **kwargs) → BaseSearchStrategy[source]¶

Resolve and instantiate a registered search strategy.

Parameters:: name (str)
Return type:: BaseSearchStrategy

pathforge.slide_retrieval.search_strategies.registry.get_search_strategy(name: str) → type['BaseSearchStrategy'][source]¶

Get a registered search strategy class by name.

Parameters:: name (str)
Return type:: type[‘BaseSearchStrategy’]

pathforge.slide_retrieval.search_strategies.registry.get_search_strategy_supported_representation_kinds(name: str) → frozenset[str][source]¶

Return representation kinds supported by a search strategy class.

Parameters:: name (str)
Return type:: frozenset[str]

pathforge.slide_retrieval.search_strategies.registry.is_search_strategy_available(name: str) → bool[source]¶

Check whether a search strategy is registered.

Parameters:: name (str)
Return type:: bool

pathforge.slide_retrieval.search_strategies.registry.list_search_strategies() → list[str][source]¶

Return all registered search strategy names in sorted order.

Return type:: list[str]

pathforge.slide_retrieval.search_strategies.registry.import_search_strategy_modules(package_name: str = 'pathforge.slide_retrieval.search_strategies') → None[source]¶

Import the canonical search strategy package.

Parameters:: package_name (str) – Package root containing the strategies subpackage.
Return type:: None

Import side effects register all search strategies.

pathforge.slide_retrieval.search_strategies.registry.get_search_strategy_supports(name: str) → set[str][source]¶

Return the supported representation types for a search strategy.

Parameters:: name (str)
Return type:: set[str]

pathforge.slide_retrieval.search_strategies.registry.get_search_strategy_hyperparams(name: str) → dict[str, dict[str, Any]][source]¶

Return the hyperparameter schema for a registered search strategy.

Parameters:: name (str)
Return type:: dict[str, dict[str, Any]]

pathforge.slide_retrieval.search_strategies.registry.get_search_strategy_defaults(name: str) → dict[str, Any][source]¶

Return the default hyperparameter values for a registered search strategy.

Parameters:: name (str)
Return type:: dict[str, Any]

pathforge.slide_retrieval.search_strategies.registry.get_search_strategy_values(name: str, params: dict[str, Any] | None = None) → dict[str, Any][source]¶

Return effective hyperparameter values without instantiating the strategy.

Parameters:

name (str)
params (dict[str, Any] | None)

Return type:

dict[str, Any]

pathforge.slide_retrieval.search_strategies.registry.describe_all_search_strategies() → dict[str, dict[str, dict[str, Any]]][source]¶

Return the hyperparameter schema for all registered search strategies.

Return type:: dict[str, dict[str, dict[str, Any]]]

pathforge.slide_retrieval.search_strategies.utils.load_patch_dicts_pickle(pickle_path: str | Path, *, reconstruct_features: bool = True) → dict[str, Any][source]¶

Load one SISH mosaic pickle into the dictionary shape expected by the paper port.

Inputs:

pickle_path:: Path to a pickle file expected to store at least {"patches": ...}.
reconstruct_features:: If True, cast patch feature arrays to float32 NumPy arrays.

Output:

dict[str, Any]:: Dictionary containing patches and properties keys.

Parameters:

pickle_path (str | Path)
reconstruct_features (bool)

Return type:

dict[str, Any]

Visualization services¶

class pathforge.slide_retrieval.visualization.service.SlideVisualizationAsset[source]¶

Bases: object

Slide artifact context used by retrieval visualization.

Example:

asset = SlideVisualizationAsset(
    slide_id="slide_001",
    dataset_name="cohort_a",
    artifact_path=Path("/tmp/artifacts/slide_001.h5"),
    slide_path=None,
    patient_id="patient_1",
    category="tumor",
    fallback_mpp=None,
    metadata={"slide": "slide_001", "category": "tumor"},
)

slide_id: str¶

dataset_name: str¶

artifact_path: Path¶

slide_path: Path | None¶

patient_id: str¶

category: str¶

fallback_mpp: float | None¶

metadata: dict[str, Any]¶

__init__(slide_id: str, dataset_name: str, artifact_path: Path, slide_path: Path | None, patient_id: str, category: str, fallback_mpp: float | None, metadata: dict[str, Any]) → None¶

Parameters:

slide_id (str)
dataset_name (str)
artifact_path (Path)
slide_path (Path | None)
patient_id (str)
category (str)
fallback_mpp (float | None)
metadata (dict[str, Any])

Return type:

None

class pathforge.slide_retrieval.visualization.service.SlideRetrievalVisualizationService[source]¶

Bases: object

Render run-level slide retrieval visualizations.

Example:

service = SlideRetrievalVisualizationService(
    experiment=experiment,
    run_dir=Path("/tmp/run_abc"),
    manifest={"tiling_id": "256px_0.5mpp", "representation_id": "repr_id"},
)
files = service.render_requested_visualizations(
    requested_visualizations=["retrieval_results"],
    subset_ids={"slide_1"},
)

__init__(*, experiment: Experiment, run_dir: Path, manifest: dict[str, Any], visualization_root: Path | None = None) → None[source]¶

Parameters:

experiment (Experiment)
run_dir (Path)
manifest (dict[str, Any])
visualization_root (Path | None)

Return type:

None

render_requested_visualizations(*, requested_visualizations: list[str], subset_ids: set[str] | None) → list[Path][source]¶

Render the configured retrieval visualizations for one run.

Inputs: - requested_visualizations: visualization names from config. - subset_ids: optional set of selected slide IDs from the subset CSV.

Returns: - list[Path]: absolute PNG paths written for this run.

Parameters:

requested_visualizations (list[str])
subset_ids (set[str] | None)

Return type:

list[Path]

pathforge.slide_retrieval.visualization.renderers.render_retrieval_results_image(*, query_thumbnail: Image, query_lines: list[str], hit_panels: list[tuple[Image, list[str]]]) → Image[source]¶

Render one query + top-hit retrieval result summary image.

Parameters:

query_thumbnail (Image)
query_lines (list[str])
hit_panels (list[tuple[Image, list[str]]])

Return type:

Image

pathforge.slide_retrieval.visualization.renderers.render_retrieval_representation_image(*, thumbnail_image: Image, downscale_x: float, downscale_y: float, coords_array: ndarray, tiling_spec: dict[str, object] | None, base_mpp: float | None, group_ids: ndarray | None, selected_coords: ndarray | None, tissue_polygons: Sequence[Sequence[Sequence[Sequence[float]]]] | None, patch_strip_images: Iterable[Image], patch_group_ids: Sequence[int | None] | None) → Image[source]¶

Render one side-by-side retrieval representation summary image.

Parameters:

thumbnail_image (Image)
downscale_x (float)
downscale_y (float)
coords_array (ndarray)
tiling_spec (dict[str, object] | None)
base_mpp (float | None)
group_ids (ndarray | None)
selected_coords (ndarray | None)
tissue_polygons (Sequence[Sequence[Sequence[Sequence[float]]]] | None)
patch_strip_images (Iterable[Image])
patch_group_ids (Sequence[int | None] | None)

Return type:

Image