mmirage.cli — Command-Line Interface

Command-line interface for MMIRAGE pipeline.

mmirage.cli.run_local(config_path, shard_id=None, collect_stats=False, export_prompts_path=None)[source]

Run one shard in the current Python environment.

Parameters:

  • config_path (str) – Absolute path to the MMIRAGE YAML config file.

  • shard_id (int | None) – Optional shard id to inject via SLURM_ARRAY_TASK_ID.

  • collect_stats (bool) – If True, enable GPU utilization polling in the shard process.

  • export_prompts_path (str | None) – Optional file path for exporting batch prompts instead of submitting them.

Returns:

Process return code from shard execution.

Return type:

int

mmirage.cli.launch_pipeline(cfg, config_path, force_retry=False, require_completion=False, collect_stats=False, export_prompts_path=None)[source]

Launch the pipeline according to execution mode and retry settings.

Parameters:

  • cfg (MMirageConfig) – Parsed MMIRAGE configuration object.

  • config_path (str) – Absolute path to the MMIRAGE YAML config file.

  • force_retry (bool) – If True, enable retry orchestration regardless of config flag.

  • require_completion (bool) – If True, wait for completion and verify shard status before returning success in SLURM mode when auto-retry is off.

  • collect_stats (bool) – If True, enable GPU utilization polling on compute nodes.

  • export_prompts_path (str | None) – Optional file path for exporting batch prompts instead of submitting them.

Returns:

0 on success, 1 on failure.

Return type:

Exit code

mmirage.cli.configure_logging(level)[source]

Configure root logging.

Parameters:

level (str) – Root log level name.

Return type:

None

mmirage.cli.add_shared_arguments(parser)[source]

Attach common CLI arguments to a subcommand parser.

Parameters:

parser (ArgumentParser) – Subcommand parser receiving shared arguments.

Return type:

None

mmirage.cli.add_metadata_path_argument(parser)[source]

Attach the batch receipt path argument to a subcommand parser.

Parameters:

parser (ArgumentParser) – Subcommand parser receiving the argument.

Return type:

None

mmirage.cli.uses_batch_api(cfg)[source]

Return True when the config declares at least one batch_api processor.

Parameters:

cfg (MMirageConfig) – Parsed MMIRAGE configuration object.

Return type:

bool

mmirage.cli.build_argparser()[source]

Build the CLI parser.

Returns:

Configured top-level argparse parser.

Return type:

ArgumentParser

mmirage.cli.log_merge_reports(reports)[source]

Log merge summary for one or more datasets.

Parameters:

reports (List[MergeReport])

Return type:

None

mmirage.cli.parse_shard_ids(raw_value, num_shards=None)[source]

Parse a comma-separated shard id list.

Parameters:

  • raw_value (str | None) – Comma-separated shard ids, or None/empty for full array.

  • num_shards (int | None) – Optional upper bound used for range validation.

Returns:

Parsed shard ids.

Return type:

List[int]

mmirage.cli.handle_run(args, cfg, config_path)[source]

Handle the canonical run command.

Parameters:

  • args (Namespace) – Parsed CLI namespace.

  • cfg (MMirageConfig) – Parsed MMIRAGE configuration object.

  • config_path (str) – Absolute path to the MMIRAGE YAML config file.

Returns:

Exit code for the run operation.

Return type:

int

mmirage.cli.handle_submit(args, cfg, config_path)[source]

Submit a SLURM array job and optionally wait.

Parameters:

  • args (Namespace) – Parsed CLI namespace.

  • cfg (MMirageConfig) – Parsed MMIRAGE configuration object.

  • config_path (str) – Absolute path to the MMIRAGE YAML config file.

Returns:

Exit code for submission/wait outcome.

Return type:

int

mmirage.cli.handle_check(args, cfg, config_path)[source]

Inspect shard status and optionally submit retries.

For batch_api configs, shard state only records submission, so the provider batch status is reported from the metadata receipts instead.

Parameters:

  • args (Namespace) – Parsed CLI namespace.

  • cfg (MMirageConfig) – Parsed MMIRAGE configuration object.

  • config_path (str) – Absolute path to the MMIRAGE YAML config file.

Returns:

Exit code based on shard status and optional retry submission.

Return type:

int

mmirage.cli.handle_retry(args, cfg, config_path)[source]

Submit retries for failed shards only.

Parameters:

  • args (Namespace) – Parsed CLI namespace.

  • cfg (MMirageConfig) – Parsed MMIRAGE configuration object.

  • config_path (str) – Absolute path to the MMIRAGE YAML config file.

Returns:

Exit code for retry submission outcome.

Return type:

int

mmirage.cli.handle_stats(args, cfg, _config_path)[source]

Print per-shard benchmark statistics and aggregate totals.

Parameters:

  • args (Namespace) – Parsed CLI namespace.

  • cfg (MMirageConfig) – Parsed MMIRAGE configuration object.

  • _config_path (str) – Absolute path to the MMIRAGE YAML config file (not needed here).

Returns:

0 always (stats are informational).

Return type:

Exit code

mmirage.cli.handle_merge(args, cfg, _config_path)[source]

Merge shard outputs defined in config.loading_params.datasets.

For batch_api configs, the shards only hold submission placeholders, so the completed provider results are retrieved and merged into –output-path.

Parameters:

  • args (Namespace) – Parsed CLI namespace.

  • cfg (MMirageConfig) – Parsed MMIRAGE configuration object.

  • _config_path (str) – Absolute path to the MMIRAGE YAML config file (not needed here).

Returns:

Exit code for merge outcome.

Return type:

int

mmirage.cli.handle_merge_dir(args)[source]

Merge shard outputs directly from input/output directory arguments.

Parameters:

args (Namespace) – Parsed CLI namespace.

Returns:

Exit code for merge outcome.

Return type:

int

mmirage.cli.main()[source]

CLI entry point.

Return type:

None