Skip to content

run

run

CLI run commands for Safe Synthesizer.

Functions:

Name Description
common_run_options

Decorator to add common options for run commands.

run

Run the Safe Synthesizer end-to-end pipeline.

run_replace_pii

Plan or apply PII replacement to the full input dataset.

run_train

Run the training stage only.

run_generate

Run the generation stage only.

common_run_options(f)

Decorator to add common options for run commands.

Apply this above @pydantic_options in source order. Python applies decorators bottom-up, so the shared command options are added after the generated parameter options. Environment-variable handling stays in CLISettings rather than Click envvar= declarations, so precedence is centralized in one settings model.

Source code in src/nemo_safe_synthesizer/cli/run.py
def common_run_options(f: Callable[..., object]) -> Callable[..., object]:
    """Decorator to add common options for run commands.

    Apply this above ``@pydantic_options`` in source order. Python applies
    decorators bottom-up, so the shared command options are added after the
    generated parameter options. Environment-variable handling stays in
    ``CLISettings`` rather than Click ``envvar=`` declarations, so precedence is
    centralized in one settings model.
    """
    options = []
    options.append(
        click.option("--config", "config_path", default=None, required=False, help="path to a yaml config file")
    )
    options.append(
        click.option(
            "--data-source",
            type=str,
            default=None,
            required=False,
            help="Dataset name, URL, or path to CSV dataset. "
            "For 'run generate', this is optional if a cached dataset exists in the workdir.",
        )
    )
    options.append(
        click.option(
            "--wandb-upload-evaluation-report/--no-wandb-upload-evaluation-report",
            default=None,
            help="Upload the final evaluation HTML report and artifact to WandB. "
            "Use --no-wandb-upload-evaluation-report to skip report HTML and artifact publishing while retaining "
            "summary metrics and the evaluation scorecard. "
            "Can also be set via NSS_WANDB_UPLOAD_EVALUATION_REPORT. [default: --wandb-upload-evaluation-report]",
        )
    )
    options.append(
        click.option(
            "--artifact-path",
            type=click.Path(exists=False, dir_okay=True, file_okay=False, resolve_path=True),
            default=None,
            required=False,
            help="Base directory for all runs. Runs are created as "
            "<artifact-path>/<config>---<dataset>/<timestamp>/. "
            "Can also be set via NSS_ARTIFACTS_PATH env var. "
            "[default: ./safe-synthesizer-artifacts]",
        )
    )
    options.append(
        click.option(
            "--run-path",
            type=click.Path(exists=False, dir_okay=True, file_okay=False, resolve_path=True),
            default=None,
            required=False,
            help="Explicit path for this run's output directory. "
            "When specified, outputs go directly to this path. "
            "Overrides --artifact-path.",
        )
    )
    options.append(
        click.option(
            "--output-file",
            type=click.Path(exists=False),
            default=None,
            required=False,
            help="Path to output CSV file. Overrides the default workdir output location.",
        )
    )
    options.append(
        click.option(
            "--log-format",
            type=click.Choice(["json", "plain"]),
            default=None,
            required=False,
            help="Log format for console output. File logging will always be JSON. "
            "Can also be set via NSS_LOG_FORMAT env var. [default: plain]",
        )
    )
    options.append(
        click.option(
            "--log-color/--no-log-color",
            type=click.BOOL,
            default=None,
            required=False,
            help="Whether to colorize the log output on the console. [default: --log-color]",
        )
    )
    options.append(
        click.option(
            "--log-file",
            type=click.Path(exists=False),
            default=None,
            required=False,
            help="Path to log file. Defaults to a file nested under the run directory. "
            "Can also be set via NSS_LOG_FILE env var.",
        )
    )
    options.append(
        click.option(
            "--wandb-mode",
            type=click.Choice(["online", "offline", "disabled"]),
            default=None,
            required=False,
            help="Wandb mode. 'online' will upload logs to wandb, 'offline' will save logs to a local file, 'disabled' will not upload logs to wandb. Can also be set via WANDB_MODE env var. [default: disabled]",
        )
    )
    options.append(
        click.option(
            "--wandb-project",
            type=str,
            default=None,
            required=False,
            help="Wandb project. Can also be set via WANDB_PROJECT env var.",
        )
    )
    options.append(
        click.option(
            "-v",
            "verbose",
            required=False,
            help="Verbose logging. 'v' shows debug info from main program, 'vv' shows debug from dependencies too",
            count=True,
        )
    )
    options.append(
        click.option(
            "--dataset-registry",
            type=str,
            required=False,
            default=None,
            help="URL or path of a dataset registry YAML file. If provided, "
            "datasets in the registry may be referenced by name in --data-source. "
            "Can also be set via NSS_DATASET_REGISTRY env var. "
            "If both env var and CLI option are provided, the CLI option takes precedence.",
        )
    )
    options.append(
        click.option(
            "--inference-endpoint-url",
            type=str,
            required=False,
            default=None,
            help="OpenAI-compatible inference endpoint URL for LLM-assisted PII plan discovery. When unset, NSS "
            "runs a local vLLM server instead (see --inference-local-profile). "
            "Can also be set via NSS_INFERENCE_ENDPOINT env var.",
        )
    )
    options.append(
        click.option(
            "--inference-api-key",
            type=str,
            required=False,
            default=None,
            help="API key for the PII inference endpoint. Can also be set via NSS_INFERENCE_KEY env var.",
        )
    )
    options.append(
        click.option(
            "--inference-model-id",
            type=str,
            required=False,
            default=None,
            help="Model ID served by the PII inference endpoint. "
            "Can also be set via NSS_INFERENCE_MODEL env var. "
            "Without an endpoint, selects the bundled local vLLM profile to run "
            f"(default: {DEFAULT_NSS_INFERENCE_LOCAL_MODEL}); required with an explicit endpoint.",
        )
    )
    options.append(
        click.option(
            "--inference-timeout-seconds",
            type=float,
            required=False,
            default=None,
            help="Per-request timeout in seconds for PII inference, including model reasoning. "
            "Overrides the local profile's timeout. Can also be set via NSS_INFERENCE_TIMEOUT env var. "
            "[default: the local profile's timeout, or 60]",
        )
    )
    options.append(
        click.option(
            "--inference-request-options",
            type=str,
            required=False,
            default=None,
            help="JSON object of chat-completions fields sent with every PII inference request, such as "
            '\'{"temperature": 1.0, "thinking_token_budget": 1000}\'. Overrides the local profile\'s options '
            "field by field; a null value drops a field. Fields left out use the server's defaults. "
            "Can also be set via NSS_INFERENCE_REQUEST_OPTIONS env var.",
        )
    )
    options.append(
        click.option(
            "--inference-local-profile",
            type=str,
            required=False,
            default=None,
            help="Path to a custom profile YAML, or a bundled profile name, for the local vLLM server that NSS "
            "starts for LLM-assisted "
            "PII plan discovery and stops before planning returns. Without it and without an endpoint, "
            "--inference-model-id selects a bundled profile. With a profile, NSS_INFERENCE_ENDPOINT, if set, "
            "must be a loopback http URL and selects the listening address. "
            "Can also be set via NSS_INFERENCE_LOCAL_PROFILE env var.",
        )
    )
    options.append(
        click.option(
            "--enable-huggingface-remote/--disable-huggingface-remote",
            "huggingface_remote",
            required=False,
            default=None,
            help="Allow or block Hugging Face remote downloads for Hub assets "
            "(base model, evaluation embeddings, and similar). "
            "--disable-huggingface-remote blocks Hugging Face asset downloads by "
            "setting HF_HUB_OFFLINE and TRANSFORMERS_OFFLINE; required assets must already be "
            "cached. Equivalent to setting HF_HUB_OFFLINE in the environment. When "
            "neither flag is given, the run inherits HF_HUB_OFFLINE/TRANSFORMERS_OFFLINE "
            "from the environment (remote downloads enabled when unset). "
            "[default: --enable-huggingface-remote]",
        )
    )
    # Apply each option decorator in reverse order (decorators apply bottom-up)
    for option in reversed(options):
        f = option(f)
    return f

run(ctx, validate=False, **kwargs)

Run the Safe Synthesizer end-to-end pipeline.

Without a subcommand, runs the full end-to-end pipeline. Use 'run train', 'run generate', or 'run replace-pii' for individual stages. Pass '--plan-only' to resolve a PII replacement configuration without replacing data.

Source code in src/nemo_safe_synthesizer/cli/run.py
@click.group(invoke_without_command=True)
@click.pass_context
@common_run_options
@pydantic_options(SafeSynthesizerParameters, field_separator=CLI_NESTED_FIELD_SEPARATOR)
@click.option(
    "--validate",
    is_flag=True,
    default=False,
    help="Run pre-flight validation only, then exit without training or generating.",
)
def run(
    ctx: click.Context,
    validate: bool = False,
    **kwargs: Any,
) -> None:
    """Run the Safe Synthesizer end-to-end pipeline.

    Without a subcommand, runs the full end-to-end pipeline.
    Use 'run train', 'run generate', or 'run replace-pii' for individual
    stages. Pass '--plan-only' to resolve a PII replacement configuration
    without replacing data.
    """
    # If a subcommand is invoked, skip the default behavior
    if ctx.invoked_subcommand is not None:
        return

    _set_cli_deployment_type_default()

    settings = _settings_from_run_kwargs(kwargs)

    if validate:
        os.environ["NSS_PHASE"] = "process_data"
    else:
        os.environ["NSS_PHASE"] = "end_to_end"

    run_logger, config, df, workdir = common_setup(
        settings=settings,
        phase="process_data" if validate else "end_to_end",
        skip_wandb=validate,
        quiet=validate,
        run_name="validate" if validate else None,
    )

    try:
        run_logger.info("Nemo Safe Synthesizer starting")
        run_logger.debug("running with: ", extra={"config": config.model_dump()})

        with traced_user("SafeSynthesizer"):
            from ..sdk.library_builder import SafeSynthesizer

            assert df is not None
            nss: SafeSynthesizer = SafeSynthesizer(
                config=config,
                workdir=workdir,
                emit_telemetry=config.emit_telemetry,
            ).with_data_source(df)

            if validate:
                _run_validate_and_render(nss, settings=settings, workdir=workdir, config=config, data=df)
                return

            try:
                nss.run(output_file=settings.output_file)
                nss.results.summary.log_summary(run_logger)
                nss.results.summary.timing.log_timing(run_logger)
                nss.results.summary.log_wandb()
                publish_evaluation_report(workdir, nss.results.summary, settings.wandb_upload_evaluation_report)
            finally:
                if hasattr(nss, "generator") and nss.generator is not None:
                    nss.generator.teardown()
    except UserError as exc:
        click.secho(str(exc), fg="red", err=True)
        raise SystemExit(1)

run_replace_pii(plan_only=False, **kwargs)

Plan or apply PII replacement to the full input dataset.

Source code in src/nemo_safe_synthesizer/cli/run.py
@run.command("replace-pii")
@common_run_options
@pydantic_options(SafeSynthesizerParameters, field_separator=CLI_NESTED_FIELD_SEPARATOR)
@click.option(
    "--plan-only",
    is_flag=True,
    default=False,
    help="Resolve and write the PII replacement plan without running replacement, training, generation, or evaluation.",
)
def run_replace_pii(
    plan_only: bool = False,
    **kwargs: Any,
) -> None:
    """Plan or apply PII replacement to the full input dataset."""
    _set_cli_deployment_type_default()
    settings = _settings_from_run_kwargs(kwargs)
    run_logger, config, _, workdir = common_setup(
        settings=settings,
        phase="replace_pii",
        skip_wandb=True,
        load_data=False,
    )

    try:
        with traced_user("SafeSynthesizer"):
            from ..sdk.library_builder import SafeSynthesizer

            # A CSV source keeps its bytes, so the output's unchanged cells are parsed from the same read.
            data_source = fetch_data_source_for_replacement(settings)
            if data_source is None:
                raise UserError("Input data is required to plan or apply PII replacement.")
            config_output_path = workdir.run_dir / RESOLVED_CONFIG_FILENAME
            nss = SafeSynthesizer(
                config=config,
                workdir=workdir,
                emit_telemetry=config.emit_telemetry,
            ).with_data_source(data_source)
            if plan_only:
                nss.plan_pii_replacement(output_path=config_output_path)
                run_logger.info(f"Resolved PII replacement configuration saved to: {config_output_path}")
            else:
                # Parquet input is written back as Parquet so its column types survive; otherwise CSV.
                output_suffix = ".parquet" if data_source_extension(settings) == "parquet" else ".csv"
                data_output_path = (
                    Path(settings.output_file)
                    if settings.output_file
                    else workdir.run_dir / f"{workdir.dataset_name}_pii_replaced{output_suffix}"
                )
                result = nss.replace_pii(
                    output_path=data_output_path,
                    config_output_path=config_output_path,
                )
                run_logger.info(
                    f"PII replacement complete: {result.generation_statistics.generated_replacement_count} "
                    f"distinct replacements generated; output saved to: {data_output_path}"
                )
    except UserError as exc:
        click.secho(str(exc), fg="red", err=True)
        raise SystemExit(1)

run_train(validate=False, **kwargs)

Run the training stage only.

This command processes data and trains the model, saving the adapter to the run directory. Use 'run generate' afterwards to generate synthetic data from the trained adapter.

Source code in src/nemo_safe_synthesizer/cli/run.py
@run.command("train")
@common_run_options
@pydantic_options(SafeSynthesizerParameters, field_separator=CLI_NESTED_FIELD_SEPARATOR)
@click.option(
    "--validate",
    is_flag=True,
    default=False,
    help="Run pre-flight validation only, then exit without training or generating.",
)
def run_train(
    validate: bool = False,
    **kwargs: Any,
) -> None:
    """Run the training stage only.

    This command processes data and trains the model, saving the adapter to the run directory.
    Use 'run generate' afterwards to generate synthetic data from the trained adapter.
    """
    _set_cli_deployment_type_default()

    settings = _settings_from_run_kwargs(kwargs)

    if validate:
        os.environ["NSS_PHASE"] = "process_data"
    else:
        os.environ["NSS_PHASE"] = "train"

    run_logger, config, df, workdir = common_setup(
        settings=settings,
        phase="process_data" if validate else "train",
        skip_wandb=validate,
        quiet=validate,
        run_name="validate" if validate else None,
    )
    from ..sdk.library_builder import SafeSynthesizer

    try:
        with traced_user("SafeSynthesizer"):
            assert df is not None
            nss = SafeSynthesizer(
                config,
                workdir=workdir,
                emit_telemetry=config.emit_telemetry,
            ).with_data_source(df)

            if validate:
                _run_validate_and_render(nss, settings=settings, workdir=workdir, config=config, data=df)
                return

            nss.process_data().train()
            run_logger.info(f"Training complete. Adapter saved to: {workdir.adapter_path}")
    except UserError as exc:
        click.secho(str(exc), fg="red", err=True)
        raise SystemExit(1)

run_generate(auto_discover_adapter=False, wandb_resume_job_id=None, **kwargs)

Run the generation stage only.

This command loads a trained adapter and generates synthetic data. Requires 'run train' to have been executed first.

Use --run-path to specify the exact run directory containing the trained model, or use --auto-discover-adapter with --artifact-path to automatically find the latest trained run.

Source code in src/nemo_safe_synthesizer/cli/run.py
@run.command("generate")
@common_run_options
@click.option(
    "--auto-discover-adapter",
    is_flag=True,
    default=False,
    help="Automatically find the latest trained adapter in --artifacts-path. "
    "Without this flag, --run-path must point to a specific trained run.",
)
@click.option(
    "--wandb-resume-job-id",
    type=str,
    default=None,
    required=False,
    help="Wandb run ID to resume, or path to a file containing the run ID. "
    "Overrides file-based run ID detection from workdir.",
)
@pydantic_options(SafeSynthesizerParameters, field_separator=CLI_NESTED_FIELD_SEPARATOR)
def run_generate(
    auto_discover_adapter: bool = False,
    wandb_resume_job_id: str | None = None,
    **kwargs: Any,
) -> None:
    """Run the generation stage only.

    This command loads a trained adapter and generates synthetic data.
    Requires 'run train' to have been executed first.

    Use --run-path to specify the exact run directory containing the trained model,
    or use --auto-discover-adapter with --artifact-path to automatically find
    the latest trained run.
    """
    _set_cli_deployment_type_default()

    # Create unified settings from CLI kwargs
    settings = _settings_from_run_kwargs(kwargs)

    os.environ["NSS_PHASE"] = "generate"
    # Generation always resumes from an existing workdir with a trained model
    run_logger, config, df, workdir = common_setup(
        settings=settings,
        resume=True,
        phase="generate",
        auto_discover_adapter=auto_discover_adapter,
        wandb_resume_job_id=wandb_resume_job_id,
    )
    from ..sdk.library_builder import SafeSynthesizer, _emit_nss_telemetry

    final_output_file = settings.output_file or workdir.output_file
    with traced_user("SafeSynthesizer"):
        nss = SafeSynthesizer(
            config,
            workdir=workdir,
            emit_telemetry=config.emit_telemetry,
        )

        # Only set data source if provided via --data-source
        # Otherwise, load_from_save_path() will load from cached files
        if df is not None:
            nss = nss.with_data_source(df)

        try:
            nss = (
                nss.load_from_save_path(runtime_config=config)
                .process_data()
                .generate()
                .evaluate()
                .save_results(output_file=final_output_file)
            )
            _emit_nss_telemetry(nss, TaskStatusEnum.COMPLETED)
            nss.results.summary.log_summary(run_logger)
            nss.results.summary.timing.log_timing(run_logger)
            run_logger.info(f"Generation complete. Results saved to: {final_output_file}")
            nss.results.summary.log_wandb()
            publish_evaluation_report(workdir, nss.results.summary, settings.wandb_upload_evaluation_report)
        except KeyboardInterrupt:
            _emit_nss_telemetry(nss, TaskStatusEnum.CANCELED)
            raise
        except Exception:
            _emit_nss_telemetry(nss, TaskStatusEnum.ERROR)
            raise
        finally:
            if hasattr(nss, "generator") and nss.generator is not None:
                nss.generator.teardown()