pathforge.config

Configuration classes built on Pydantic v2. Load a YAML file with from_yaml(); all sections are validated before any work begins.

class pathforge.config.config.BenchmarkParamEntry[source]

Bases: object

Normalized benchmark-parameter entry used for combo expansion.

Inputs: - value: base benchmark value consumed by existing code paths. - hyperparams: optional hyperparameter mapping attached to that value.

Returns: - Immutable normalized entry for one benchmark-parameter option.

value: int | float | str | None
hyperparams: dict[str, Any]
__init__(value: int | float | str | None, hyperparams: dict[str, ~typing.Any]=<factory>) → None
Parameters:

  • value (int | float | str | None)

  • hyperparams (dict[str, Any])

Return type:

None

class pathforge.config.config.ExperimentConfig[source]

Bases: BaseModel

Universal experiment settings.

project_name: str
annotation_file: str
project_root: str | None
num_workers: int
task: TaskType | None
mode: ModeType
prediction_level: Literal['mil', 'slide']
aggregation_level: AggregationLevel
label_column: str
slide_column: str
survival_time_column: str | None
survival_event_column: str | None
report: bool
thumbnail: bool
mixed_precision: bool
visualization: List[str]
evaluation: List[str]
custom_metrics: List[str]
validate_task_for_mode() → ExperimentConfig[source]
Return type:

ExperimentConfig

classmethod validate_num_workers(value: int) → int[source]
Parameters:

value (int)

Return type:

int

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pathforge.config.config.ClassificationConfig[source]

Bases: BaseModel

Classification task settings.

split_technique: Literal['k-fold', 'k-fold-stratified', 'fixed']
val_fraction: float
epochs: int
batch_size: int
best_epoch_based_on: str
patience: int
accumulate_grad_batches: int
gradient_clip_val: float
lr: float
weight_decay: float
scheduler: Literal['none', 'reduce_on_plateau', 'cosine']
scheduler_monitor: str
balancing: str | None
class_weighting: bool
bag_size: int
encoder_layers: int
z_dim: int
dropout_p: float
k: int
skip_extracted: bool
skip_feature_extraction: bool
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pathforge.config.config.MILConfig[source]

Bases: BaseModel

MIL backend selection and training settings.

backend: Literal['native', 'torchmil', 'mil-lab']
torchmil_model: str | None
torchmil_model_kwargs: Dict[str, Any]
use_torchmil_collate: bool
mil_lab_model: str | None
mil_lab_model_kwargs: Dict[str, Any]
mil_lab_from_pretrained: bool
epochs: int
batch_size: int
best_epoch_based_on: str
patience: int
accumulate_grad_batches: int
gradient_clip_val: float
optimizer: str
lr: float
weight_decay: float
scheduler: Literal['none', 'reduce_on_plateau', 'cosine']
scheduler_monitor: str
balancing: str | None
class_weighting: bool
bag_size: int
encoder_layers: int
z_dim: int
dropout_p: float
k: int
skip_extracted: bool
skip_feature_extraction: bool
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pathforge.config.config.SlideRetrievalConfig[source]

Bases: BaseModel

Slide retrieval task settings.

exclusion_level: Literal['none', 'slide', 'case', 'patient']
search_workers: int
representation_loader_workers: int | None
representation_workers: int | None
visualization_metadata_columns: List[str]
visualization_top_k: int
weights_dir: str
classmethod validate_visualization_metadata_columns(value: List[str]) → List[str][source]
Parameters:

value (List[str])

Return type:

List[str]

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pathforge.config.config.ExplainabilityConfig[source]

Bases: BaseModel

Explainability backend selection.

heatmap_backend: Literal['native', 'torchmil']
heatmap_colormap: str
heatmap_tile_alpha: float
heatmap_smoothed_alpha: float
heatmap_smoothing_sigma_scale: float
heatmap_top_k_tiles: int
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pathforge.config.config.MetricsConfig[source]

Bases: BaseModel

Metric and loss backend selection.

Examples

metrics:
  classification_backend: torchmetrics
  survival_continuous_backend: torchsurv
classification_backend: str
survival_continuous_backend: str
registry_namespace: str | None
classification_metrics: list[str]
survival_metrics: list[str]
regression_metrics: list[str]
classmethod validate_classification_metrics(value: list[str]) → list[str][source]
Parameters:

value (list[str])

Return type:

list[str]

classmethod validate_survival_metrics(value: list[str]) → list[str][source]
Parameters:

value (list[str])

Return type:

list[str]

classmethod validate_regression_metrics(value: list[str]) → list[str][source]
Parameters:

value (list[str])

Return type:

list[str]

metrics_for_task(task: str | None) → list[str][source]

Return the configured metric names compatible with one task.

Parameters:

task (str | None)

Return type:

list[str]

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pathforge.config.config.SearchSpaceParameter[source]

Bases: BaseModel

One optimization search-space parameter specification.

kind: Literal['categorical', 'float', 'int']
choices: list[Any]
low: float | int | None
high: float | int | None
step: float | int | None
log: bool
validate_shape() → SearchSpaceParameter[source]
Return type:

SearchSpaceParameter

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pathforge.config.config.FeatureExtractionRuntimeConfig[source]

Bases: BaseModel

Runtime controls forwarded to slide-backend feature extraction.

batch_size: int
num_workers: int
amp: bool
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pathforge.config.config.SlideProcessingConfig[source]

Bases: BaseModel

Settings for slide processing backends.

backend: Literal['lazyslide', 'openslide', 'cucim']
save_tiles: bool
segmentation_method: str | None
feature_extraction: FeatureExtractionRuntimeConfig
qc_filters: List[Dict[str, Any]]
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pathforge.config.config.OptimizationConfig[source]

Bases: BaseModel

Optuna Optimization settings.

study_name: str
load_study: bool
objective_metric: str
objective_mode: Literal['max', 'min']
objective_dataset: Literal['val', 'test']
sampler: str
trials: int
pruner: str | None
storage: str | None
trials_per_worker: int
heartbeat_interval: int | None
stale_trial_timeout: int | None
search_space: dict[str, SearchSpaceParameter]
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pathforge.config.config.StageResourceConfig[source]

Bases: BaseModel

Resource request used when rendering one distributed execution stage.

cpus: int
gpus: int
memory_gb: int
time: str
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pathforge.config.config.ExecutionResourcesConfig[source]

Bases: BaseModel

Per-stage resource requests for generated scheduler jobs.

feature_extraction: StageResourceConfig
benchmarking: StageResourceConfig
optimization: StageResourceConfig
aggregation: StageResourceConfig
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pathforge.config.config.SlurmExecutionConfig[source]

Bases: BaseModel

SLURM-specific rendering controls for distributed execution plans.

partition: str | None
account: str | None
qos: str | None
constraint: str | None
max_concurrent: int
extra_directives: list[str]
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pathforge.config.config.ExecutionConfig[source]

Bases: BaseModel

Global scheduler-neutral settings for distributed PathForge work.

backend: Literal['local', 'slurm', 'dask']
work_dir: str | None
resume: bool
max_workers: int
resources: ExecutionResourcesConfig
slurm: SlurmExecutionConfig
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pathforge.config.config.EvaluationConfig[source]

Bases: BaseModel

Post-run evaluation and visualization settings.

label_column: str | None
metrics: List[str]
visualization: List[str]
visualization_subset_file: str | None
classmethod validate_label_column(value: str | None) → str | None[source]
Parameters:

value (str | None)

Return type:

str | None

classmethod validate_visualization_subset_file(value: str | None) → str | None[source]
Parameters:

value (str | None)

Return type:

str | None

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pathforge.config.config.DatasetEntry[source]

Bases: BaseModel

Definition of a dataset source.

name: str
slides_dir: str
artifacts_dir: str
features_dir: str | None
tissue_annotations_dir: str | None
used_for: str
classmethod validate_used_for(value: str) → str[source]
Parameters:

value (str)

Return type:

str

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pathforge.config.config.BenchmarkParameters[source]

Bases: BaseModel

Grid search parameters. Pydantic validators enforce logic previously implemented manually.

tile_px: List[BenchmarkParamInput]
tile_mpp: List[BenchmarkParamInput]
color_norm: List[BenchmarkParamInput | None] | None
feature_extraction: List[BenchmarkParamInput]
mil: List[BenchmarkParamInput]
slide_level_models: List[str]
slide_aggregation: List[Literal['mean', 'max', 'mean_max']]
loss: List[BenchmarkParamInput]
activation_function: List[BenchmarkParamInput]
optimizer: List[BenchmarkParamInput]
search_strategy: List[BenchmarkParamInput] | None
retrieval_representation: List[BenchmarkParamInput] | None
scheduler: List[Literal['none', 'reduce_on_plateau', 'cosine']]
batch_size: List[int]
epochs: List[int]
lr: List[float]
weight_decay: List[float]
dropout_p: List[float]
bag_size: List[int]
z_dim: List[int]
encoder_layers: List[int]
k: List[int]
seeds: List[int]
get_entries(field_name: str) → list[BenchmarkParamEntry][source]

Return normalized benchmark entries for one benchmark-parameter field.

Parameters:

field_name (str)

Return type:

list[BenchmarkParamEntry]

get_values(field_name: str) → list[int | float | str | None][source]

Return only the base values for one benchmark-parameter field.

Parameters:

field_name (str)

Return type:

list[int | float | str | None]

validate_strategy_hyperparams() → BenchmarkParameters[source]

Validate slide-retrieval hyperparameter names when provided.

Return type:

BenchmarkParameters

classmethod validate_tile_px(v: List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]]) → List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]][source]
Parameters:

v (List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]])

Return type:

List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]]

classmethod validate_tile_mpp(v: List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]]) → List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]][source]
Parameters:

v (List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]])

Return type:

List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]]

classmethod validate_feature_extractors(v: list[int | float | str | None | dict[int | float | str | None, dict[str, Any]]]) → list[int | float | str | None | dict[int | float | str | None, dict[str, Any]]][source]
Parameters:

v (list[int | float | str | None | dict[int | float | str | None, dict[str, Any]]])

Return type:

list[int | float | str | None | dict[int | float | str | None, dict[str, Any]]]

classmethod validate_color_norm(v: list[int | float | str | None | dict[int | float | str | None, dict[str, Any]]] | None) → list[int | float | str | None | dict[int | float | str | None, dict[str, Any]]] | None[source]
Parameters:

v (list[int | float | str | None | dict[int | float | str | None, dict[str, Any]]] | None)

Return type:

list[int | float | str | None | dict[int | float | str | None, dict[str, Any]]] | None

classmethod validate_mil_models(v: List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]]) → List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]][source]
Parameters:

v (List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]])

Return type:

List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]]

classmethod validate_slide_level_models(v: List[str]) → List[str][source]
Parameters:

v (List[str])

Return type:

List[str]

classmethod validate_activations(v: List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]]) → List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]][source]
Parameters:

v (List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]])

Return type:

List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]]

classmethod validate_optimizers(v: List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]]) → List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]][source]
Parameters:

v (List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]])

Return type:

List[int | float | str | None | dict[int | float | str | None, dict[str, Any]]]

classmethod validate_batch_sizes(value: list[int]) → list[int][source]
Parameters:

value (list[int])

Return type:

list[int]

classmethod validate_epochs(value: list[int]) → list[int][source]
Parameters:

value (list[int])

Return type:

list[int]

classmethod validate_learning_rates(value: list[float]) → list[float][source]
Parameters:

value (list[float])

Return type:

list[float]

classmethod validate_weight_decay(value: list[float]) → list[float][source]
Parameters:

value (list[float])

Return type:

list[float]

classmethod validate_dropouts(value: list[float]) → list[float][source]
Parameters:

value (list[float])

Return type:

list[float]

classmethod validate_positive_int_lists(value: list[int], info: Any) → list[int][source]
Parameters:

  • value (list[int])

  • info (Any)

Return type:

list[int]

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pathforge.config.config.Config[source]

Bases: BaseModel

Top-level configuration object.

experiment: ExperimentConfig
classification: ClassificationConfig | None
slide_retrieval: SlideRetrievalConfig | None
mil: MILConfig
slide_processing: SlideProcessingConfig
explainability: ExplainabilityConfig
metrics: MetricsConfig
optimization: OptimizationConfig
execution: ExecutionConfig
evaluation: EvaluationConfig
datasets: List[DatasetEntry]
benchmark_parameters: BenchmarkParameters
weights_dir: str
hf_key: str | None
validate_backend_constraints() → Config[source]

Ensures selected optional backends are installed before runtime uses them.

Return type:

Config

classmethod from_yaml(path: str | Path) → Config[source]
Parameters:

path (str | Path)

Return type:

Config

save_yaml(path: str | Path) → None[source]
Parameters:

path (str | Path)

Return type:

None

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].