pathforge.cli¶

Thin CLI shells. Each module exposes a main() function registered as a console script entry point.

Application and shared helpers¶

pathforge.cli.app.main() → None[source]¶

Entry point that launches the PathForge Typer application.

Return type:: None

pathforge.cli.common.normalize_log_level(log_level: str) → str[source]¶

Return the upper-cased log level, validating it against the allowed set.

Parameters:: log_level (str)
Return type:: str

pathforge.cli.common.configure_logging(log_level: str) → None[source]¶

Configure root logging at the given level using the shared CLI format.

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

pathforge.cli.common.enable_dask_query_planning() → None[source]¶

Enable Dask dataframe query planning for downstream processing.

Return type:: None

pathforge.cli.common.resolve_config_path(config: Path) → Path[source]¶

Return the config path as a Path, raising if it does not exist.

Parameters:: config (Path)
Return type:: Path

Feature Extraction¶

pathforge.cli.features_run.run_feature_extraction(*, config: Path, log_level: str = 'INFO') → int[source]¶

Run batch feature extraction for one YAML config and return an exit code.

Parameters:

config (Path)
log_level (str)

Return type:

int

pathforge.cli.features_run.run_command(config: Path = typer.Option(..., '--config', help='Path to YAML config'), log_level: str = typer.Option('INFO', '--log-level', help='Logging level.', show_default=True)) → None[source]¶

Typer command that runs feature extraction from the provided config option.

Parameters:

config (Path)
log_level (str)

Return type:

None

pathforge.cli.features_run.main(argv: list[str] | None = None) → int[source]¶

Argparse entry point for the feature-extraction CLI; returns a process exit code.

Parameters:: argv (list[str] | None)
Return type:: int

Single-Slide Feature Extraction¶

pathforge.cli.features_slide.run_feature_extraction_single_slide(*, config: Path, dataset: str, input_path: Path, log_level: str = 'INFO') → int[source]¶

Run feature extraction for a single slide and return an exit code.

Parameters:

config (Path)
dataset (str)
input_path (Path)
log_level (str)

Return type:

int

pathforge.cli.features_slide.run_command(config: Path = typer.Option(..., '--config', help='Path to YAML config'), dataset: str = typer.Option(..., '--dataset', help='Dataset name (must exist in config.datasets).'), input_path: Path = typer.Option(..., '--input', help='Path to a single WSI file.'), log_level: str = typer.Option('INFO', '--log-level', help='Logging level.', show_default=True)) → None[source]¶

Typer command that runs single-slide feature extraction from the provided options.

Parameters:

config (Path)
dataset (str)
input_path (Path)
log_level (str)

Return type:

None

pathforge.cli.features_slide.main(argv: list[str] | None = None) → int[source]¶

Argparse entry point for the single-slide feature-extraction CLI.

Parameters:: argv (list[str] | None)
Return type:: int

Benchmarking¶

pathforge.cli.benchmark_run.run_benchmark(*, config: Path, log_level: str = 'INFO') → int[source]¶

Run the benchmarking workflow for one YAML config and return an exit code.

Parameters:

config (Path)
log_level (str)

Return type:

int

pathforge.cli.benchmark_run.run_command(config: Path = typer.Option(..., '--config', help='Path to YAML config'), log_level: str = typer.Option('INFO', '--log-level', help='Logging level.', show_default=True)) → None[source]¶

Typer command that runs benchmarking from the provided config option.

Parameters:

config (Path)
log_level (str)

Return type:

None

pathforge.cli.benchmark_run.main(argv: list[str] | None = None) → int[source]¶

Argparse entry point for the benchmarking CLI; returns a process exit code.

Parameters:: argv (list[str] | None)
Return type:: int

Optimization¶

pathforge.cli.optimize_run.run_optimization(*, config: Path, trials: int | None = None, finalize: bool = True) → int[source]¶

Run the optimization policy for one YAML config and return an exit code.

Parameters:

config (Path)
trials (int | None)
finalize (bool)

Return type:

int

pathforge.cli.optimize_run.run_command(config: Path = typer.Option(..., '--config', help='Path to YAML config.')) → None[source]¶

Typer command that runs optimization from the provided config option.

Parameters:: config (Path)
Return type:: None

pathforge.cli.optimize_run.worker_command(config: Path = typer.Option(..., '--config', help='Path to YAML config.'), trials: int | None = typer.Option(None, '--trials', min=1, help='Trials claimed by this worker; defaults to trials_per_worker.')) → None[source]¶

Join a shared Optuna study and execute this worker’s trial allocation.

Parameters:

config (Path)
trials (int | None)

Return type:

None

pathforge.cli.optimize_run.finalize_command(config: Path = typer.Option(..., '--config', help='Path to YAML config.')) → None[source]¶

Load a shared Optuna study and write its final summaries and plots.

Parameters:: config (Path)
Return type:: None

pathforge.cli.optimize_run.main(argv: list[str] | None = None) → int[source]¶

Argparse entry point for the optimization CLI; returns a process exit code.

Parameters:: argv (list[str] | None)
Return type:: int

Distributed Execution¶

CLI commands for distributed execution planning, workers, and aggregation.

pathforge.cli.execution.plan_command(config: Path = typer.Option(..., '--config', help='Path to YAML config.'), output: Path = typer.Option(..., '--output', help='Execution-plan directory.')) → None[source]¶

Materialize work manifests and ready-to-submit SLURM scripts.

Parameters:

config (Path)
output (Path)

Return type:

None

pathforge.cli.execution.worker_command(plan: Path = typer.Option(..., '--plan', help='Path to plan.json.'), stage: Literal['features', 'benchmark'] = typer.Option(..., '--stage', help='features or benchmark'), index: int = typer.Option(..., '--index', min=0, help='Zero-based manifest index.'), no_resume: bool = typer.Option(False, '--no-resume', help='Rerun successful work.')) → None[source]¶

Execute exactly one idempotent manifest record.

Parameters:

plan (Path)
stage (Literal['features', 'benchmark'])
index (int)
no_resume (bool)

Return type:

None

pathforge.cli.execution.aggregate_command(plan: Path = typer.Option(..., '--plan', help='Path to plan.json.')) → None[source]¶

Reduce isolated worker status files into a deterministic CSV report.

Parameters:: plan (Path)
Return type:: None

pathforge.cli.execution.status_command(plan: Path = typer.Option(..., '--plan', help='Path to plan.json.')) → None[source]¶

Print counts of worker lifecycle states for one execution plan.

Parameters:: plan (Path)
Return type:: None

pathforge.cli.execution.run_command(plan: Path = typer.Option(..., '--plan', help='Path to plan.json.'), stage: Literal['features', 'benchmark'] = typer.Option(..., '--stage', help='features or benchmark'), backend: str = typer.Option('local', '--backend', help='local or dask'), scheduler_address: str | None = typer.Option(None, '--scheduler-address', help='Existing Dask scheduler address; omit to create a local client.')) → None[source]¶

Execute a complete manifest stage through local processes or Dask.

Parameters:

plan (Path)
stage (Literal['features', 'benchmark'])
backend (str)
scheduler_address (str | None)

Return type:

None

Inference¶

pathforge.cli.infer_run.run_inference(*, config: Path, input_csv: Path, log_level: str = 'INFO') → int[source]¶

Run the inference policy over the input CSV for one YAML config.

Parameters:

config (Path)
input_csv (Path)
log_level (str)

Return type:

int

pathforge.cli.infer_run.run_command(config: Path = typer.Option(..., '--config', help='Path to YAML config.'), input_csv: Path = typer.Option(..., '--input-csv', help='CSV selecting slides to run inference for.'), log_level: str = typer.Option('INFO', '--log-level', help='Logging level.', show_default=True)) → None[source]¶

Typer command that runs inference from the provided config and input CSV.

Parameters:

config (Path)
input_csv (Path)
log_level (str)

Return type:

None

pathforge.cli.infer_run.main(argv: list[str] | None = None) → int[source]¶

Argparse entry point for the inference CLI; returns a process exit code.

Parameters:: argv (list[str] | None)
Return type:: int

pathforge.cli.inference.main(argv: list[str] | None = None) → int[source]¶

Run packaged-model inference and optional heatmap generation from the CLI.

Parameters:: argv (list[str] | None)
Return type:: int

Evaluation¶

pathforge.cli.evaluate_run.run_evaluation(*, config: Path, log_level: str = 'INFO') → int[source]¶

Run the evaluation orchestrator for one YAML config and return an exit code.

Parameters:

config (Path)
log_level (str)

Return type:

int

pathforge.cli.evaluate_run.run_command(config: Path = typer.Option(..., '--config', help='Path to YAML config'), log_level: str = typer.Option('INFO', '--log-level', help='Logging level.', show_default=True)) → None[source]¶

Typer command that runs evaluation from the provided config option.

Parameters:

config (Path)
log_level (str)

Return type:

None

pathforge.cli.evaluate_run.main(argv: list[str] | None = None) → int[source]¶

Argparse entry point for the evaluation CLI; returns a process exit code.

Parameters:: argv (list[str] | None)
Return type:: int

Mean RGB¶

pathforge.cli.retrieval_mean_rgb.run_mean_rgb(*, config: Path, dataset: str, slide_id: str, input_path: Path | None = None, bag_ids: list[str] | None = None, artifact_path: Path | None = None, log_level: str = 'INFO') → int[source]¶

Precompute mean-RGB slide-retrieval descriptors for one YAML config.

Parameters:

config (Path)
dataset (str)
slide_id (str)
input_path (Path | None)
bag_ids (list[str] | None)
artifact_path (Path | None)
log_level (str)

Return type:

int

pathforge.cli.retrieval_mean_rgb.run_command(config: Path = typer.Option(..., '--config', help='Path to YAML config'), dataset: str = typer.Option(..., '--dataset', help='Dataset name (must exist in config.datasets).'), slide_id: str = typer.Option(..., '--slide-id', help='Slide ID (without extension), used for source lookup and artifact naming.'), input_path: Path | None = typer.Option(None, '--input', help='Optional explicit source slide path. When provided, mean_rgb uses this path instead of resolving the slide from datasets[].slides_dir.'), bag_ids: list[str] | None = typer.Option(None, '--bag-id', help='Bag identifier (repeatable). If omitted, bag IDs are inferred from all tile_px/tile_mpp combinations in config.benchmark_parameters.'), artifact_path: Path | None = typer.Option(None, '--artifact-path', help='Optional explicit slide artifact path. Defaults to datasets[].artifacts_dir/{slide_id}.h5.'), log_level: str = typer.Option('INFO', '--log-level', help='Logging level.', show_default=True)) → None[source]¶

Typer command that precomputes mean-RGB descriptors from the provided options.

Parameters:

config (Path)
dataset (str)
slide_id (str)
input_path (Path | None)
bag_ids (list[str] | None)
artifact_path (Path | None)
log_level (str)

Return type:

None

pathforge.cli.retrieval_mean_rgb.main(argv: list[str] | None = None) → int[source]¶

Argparse entry point for the mean-RGB CLI; returns a process exit code.

Parameters:: argv (list[str] | None)
Return type:: int

Visualization¶

pathforge.cli.visualize_run.run_visualization(*, config: Path, log_level: str = 'INFO') → int[source]¶

Run the visualization orchestrator for one YAML config and return an exit code.

Parameters:

config (Path)
log_level (str)

Return type:

int

pathforge.cli.visualize_run.run_command(config: Path = typer.Option(..., '--config', help='Path to YAML config'), log_level: str = typer.Option('INFO', '--log-level', help='Logging level.', show_default=True)) → None[source]¶

Typer command that runs visualization from the provided config option.

Parameters:

config (Path)
log_level (str)

Return type:

None

pathforge.cli.visualize_run.summary_command(input_csv: Path = typer.Option(..., '--input', help='Global benchmark_results.csv or optimization_results.csv.'), output: Path | None = typer.Option(None, '--output', help='Output directory; defaults beside the input CSV.'), title: str = typer.Option('Pipeline Results', '--title', help='Title prefix used by the generated charts.')) → None[source]¶

Create standalone ranked HTML charts from a saved global results CSV.

Parameters:

input_csv (Path)
output (Path | None)
title (str)

Return type:

None

pathforge.cli.visualize_run.main(argv: list[str] | None = None) → int[source]¶

Argparse entry point for the visualization CLI; returns a process exit code.

Parameters:: argv (list[str] | None)
Return type:: int

Slide Retrieval Representations¶

pathforge.cli.retrieval_representations.run_slide_retrieval_representations(*, config: Path, log_level: str = 'INFO', skip_missing_features: bool = False) → int[source]¶

Precompute slide-retrieval representations for one YAML config.

Parameters:

config (Path)
log_level (str)
skip_missing_features (bool)

Return type:

int

pathforge.cli.retrieval_representations.run_command(config: Path = typer.Option(..., '--config', help='Path to YAML config'), log_level: str = typer.Option('INFO', '--log-level', help='Logging level.', show_default=True), skip_missing_features: bool = typer.Option(False, '--skip-missing-features', help='Deprecated compatibility flag. Representation precompute is now always artifact-only and skips slides with missing features.')) → None[source]¶

Typer command that precomputes slide-retrieval representations from the provided options.

Parameters:

config (Path)
log_level (str)
skip_missing_features (bool)

Return type:

None

pathforge.cli.retrieval_representations.main(argv: list[str] | None = None) → int[source]¶

Run only the slide-retrieval representation materialization stage.

Parameters:: argv (list[str] | None)
Return type:: int

Tile Reports¶

pathforge.cli.report_tiles.run_tiles_report(*, config: Path, log_level: str = 'INFO') → int[source]¶

Generate the tiles report for one YAML config and return an exit code.

Parameters:

config (Path)
log_level (str)

Return type:

int

pathforge.cli.report_tiles.run_command(config: Path = typer.Option(..., '--config', help='Path to YAML config'), log_level: str = typer.Option('INFO', '--log-level', help='Logging level.', show_default=True)) → None[source]¶

Typer command that builds the tiles report from the provided config option.

Parameters:

config (Path)
log_level (str)

Return type:

None

pathforge.cli.report_tiles.main(argv: list[str] | None = None) → int[source]¶

Argparse entry point for the tiles-report CLI; returns a process exit code.

Parameters:: argv (list[str] | None)
Return type:: int

SISH VQ-VAE¶

pathforge.cli.retrieval_sish_vqvae.run_sish_vqvae(*, config: Path, dataset: str, slide_id: str, input_path: Path | None = None, bag_ids: list[str] | None = None, artifact_path: Path | None = None, descriptor_name: str = SISH_VQVAE_DESCRIPTOR_NAME, log_level: str = 'INFO') → int[source]¶

Run SISH VQ-VAE descriptor precomputation for one YAML config.

Parameters:

config (Path)
dataset (str)
slide_id (str)
input_path (Path | None)
bag_ids (list[str] | None)
artifact_path (Path | None)
descriptor_name (str)
log_level (str)

Return type:

int

pathforge.cli.retrieval_sish_vqvae.run_command(config: Path = typer.Option(..., '--config', help='Path to YAML config'), dataset: str = typer.Option(..., '--dataset', help='Dataset name (must exist in config.datasets).'), slide_id: str = typer.Option(..., '--slide-id', help='Slide ID (without extension), used for source lookup and artifact naming.'), input_path: Path | None = typer.Option(None, '--input', help='Optional explicit source slide path.'), bag_ids: list[str] | None = typer.Option(None, '--bag-id', help='Bag identifier (repeatable).'), artifact_path: Path | None = typer.Option(None, '--artifact-path', help='Optional explicit slide artifact path.'), descriptor_name: str = typer.Option(SISH_VQVAE_DESCRIPTOR_NAME, '--descriptor-name', help='Retrieval descriptor dataset name to write.', show_default=True), log_level: str = typer.Option('INFO', '--log-level', help='Logging level.', show_default=True)) → None[source]¶

Typer command that runs SISH VQ-VAE precomputation from the provided options.

Parameters:

config (Path)
dataset (str)
slide_id (str)
input_path (Path | None)
bag_ids (list[str] | None)
artifact_path (Path | None)
descriptor_name (str)
log_level (str)

Return type:

None

pathforge.cli.retrieval_sish_vqvae.main(argv: list[str] | None = None) → int[source]¶

Argparse entry point for the SISH VQ-VAE CLI; returns a process exit code.

Parameters:: argv (list[str] | None)
Return type:: int

Base¶

pathforge.cli.base.add_config_argument(parser: ArgumentParser) → None[source]¶

Parameters:: parser (ArgumentParser)
Return type:: None

pathforge.cli.base.add_log_level_argument(parser: ArgumentParser) → None[source]¶

Parameters:: parser (ArgumentParser)
Return type:: None

pathforge.cli.base.configure_logging(log_level: str) → None[source]¶

Configure the shared PathForge CLI logging format once per process.

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

pathforge.cli.base.enable_dask_query_planning() → None[source]¶

Enable the shared Dask dataframe planning setting used by PathForge CLIs.

Return type:: None

pathforge.cli.base.load_config(config_path: str | Path) → Config[source]¶

Load a validated PathForge config from disk.

Parameters:: config_path (str | Path)
Return type:: Config

pathforge.cli.base.load_experiment(config_path: str | Path) → Experiment[source]¶

Build an Experiment from one validated config path.

Parameters:: config_path (str | Path)
Return type:: Experiment