Skip to content

settings

settings

Unified CLI settings for Safe Synthesizer.

This module provides a unified settings model that composes all sub-settings (observability, wandb, etc.) into a single pydantic-settings class.

The CLISettings class:

  • Automatically loads from environment variables
  • Composes existing settings classes as nested fields
  • Provides a single source of truth for all CLI configuration
  • Can be instantiated from Click kwargs with CLI precedence
Usage

From environment variables only

settings = CLISettings()

From Click kwargs (CLI takes precedence over env vars)

settings = CLISettings.from_cli_kwargs(data_source="data.csv", artifact_path="/tmp")

Access composed settings

log_format = settings.observability.nss_log_format wandb_mode = settings.wandb.wandb_mode

Classes:

Name Description
CLISettings

Unified CLI settings composing all sub-settings.

CLISettings

Bases: BaseSettings

Unified CLI settings composing all sub-settings.

Consolidates environment variables (automatic via pydantic-settings), CLI arguments (passed via from_cli_kwargs), and composed sub-settings (observability, wandb).

Methods:

Name Description
validate_wandb_mode

Coerce string or None to WandbMode enum, passing through enum values unchanged.

validate_inference_settings

Check the PII inference values with the same reader planning uses, so errors appear before a run.

inference_environ

Return the NSS_INFERENCE_* variables for the PII inference values that are set.

validate_inference_timeout_seconds

Treat a blank value as unset, as the PII inference client does.

validate_verbose

Coerce string or None to int, defaulting to 0.

from_cli_kwargs

Create settings from Click kwargs, filtering None values.

Attributes:

Name Type Description
observability NSSObservabilitySettings

Observability sub-settings (log level, format, color).

wandb WandbSettings

WandB settings (mode, project, phase).

data_source str | None

Dataset name, URL, or path to CSV.

config_path str | None

Path to YAML config file (env variable: NSS_CONFIG).

artifact_path str | None

Base directory for all runs (env variable: NSS_ARTIFACTS_PATH).

run_path str | None

Explicit path for this run's output directory.

output_file str | None

Path to output CSV file, overriding the default workdir location.

log_format Literal['json', 'plain'] | None

Log format for console output (env variable: NSS_LOG_FORMAT).

log_color bool | None

Whether to colorize console output (env variable: NSS_LOG_COLOR).

log_file str | None

Path to log file (env variable: NSS_LOG_FILE).

verbose int

Verbosity level (0=INFO, 1=DEBUG, 2=DEBUG_DEPENDENCIES).

wandb_mode WandbMode | None

WandB mode override (online, offline, or disabled).

wandb_project str | None

WandB project name override.

wandb_upload_evaluation_report bool

Whether the CLI uploads the final evaluation HTML report and artifact to WandB.

synthesis_overrides dict[str, Any]

Nested dict of SafeSynthesizerParameters overrides from CLI.

dataset_registry str | None

URL or path to a dataset registry YAML file (env: NSS_DATASET_REGISTRY).

inference_endpoint_url str | None

OpenAI-compatible PII inference endpoint (env: NSS_INFERENCE_ENDPOINT).

inference_api_key str | None

PII inference API key (env: NSS_INFERENCE_KEY).

inference_model_id str | None

PII inference model ID (env: NSS_INFERENCE_MODEL).

inference_timeout_seconds float | None

PII inference per-request timeout (env: NSS_INFERENCE_TIMEOUT).

inference_request_options str | None

Extra PII inference request fields as JSON (env: NSS_INFERENCE_REQUEST_OPTIONS).

inference_local_profile str | None

Managed local PII inference server profile (env: NSS_INFERENCE_LOCAL_PROFILE).

huggingface_remote bool | None

Whether to allow Hugging Face remote downloads for Hub assets (base model, etc.).

explicit_cli_fields frozenset[str]

Fields explicitly supplied by Click rather than loaded from the environment.

effective_artifact_path Path

Effective artifact path, falling back to DEFAULT_ARTIFACTS_PATH.

effective_log_format Literal['json', 'plain']

Effective log format, falling back to observability settings.

effective_log_color bool

Effective log color setting, falling back to observability settings.

effective_wandb_mode WandbMode

Effective wandb mode, falling back to wandb settings.

effective_wandb_project str | None

Effective wandb project, falling back to wandb settings.

observability = Field(default_factory=NSSObservabilitySettings, description='Observability sub-settings (log level, format, color).') class-attribute instance-attribute

Observability sub-settings (log level, format, color).

Loaded from its own environment variables; not populated by CLISettings.

wandb = Field(default_factory=WandbSettings, description='WandB settings (mode, project, phase).') class-attribute instance-attribute

WandB settings (mode, project, phase).

Loaded from its own environment variables; not populated by CLISettings.

data_source = Field(default=None, description='Dataset name, URL, or path to CSV') class-attribute instance-attribute

Dataset name, URL, or path to CSV.

config_path = Field(default=None, validation_alias=(AliasChoices('config_path', 'NSS_CONFIG')), description='Path to YAML config file') class-attribute instance-attribute

Path to YAML config file (env variable: NSS_CONFIG).

artifact_path = Field(default=None, validation_alias=(AliasChoices('artifact_path', 'NSS_ARTIFACTS_PATH')), description='Base directory for all runs') class-attribute instance-attribute

Base directory for all runs (env variable: NSS_ARTIFACTS_PATH).

run_path = Field(default=None, description="Explicit path for this run's output directory") class-attribute instance-attribute

Explicit path for this run's output directory.

When specified, overrides artifact_path and skips the <project>/<timestamp> directory layout.

output_file = Field(default=None, description='Path to output CSV file') class-attribute instance-attribute

Path to output CSV file, overriding the default workdir location.

log_format = Field(default=None, validation_alias=(AliasChoices('log_format', 'NSS_LOG_FORMAT')), description='Log format for console output') class-attribute instance-attribute

Log format for console output (env variable: NSS_LOG_FORMAT).

File logging is always JSON regardless of this setting.

log_color = Field(default=None, validation_alias=(AliasChoices('log_color', 'NSS_LOG_COLOR')), description='Whether to colorize console output') class-attribute instance-attribute

Whether to colorize console output (env variable: NSS_LOG_COLOR).

log_file = Field(default=None, validation_alias=(AliasChoices('log_file', 'NSS_LOG_FILE')), description='Path to log file') class-attribute instance-attribute

Path to log file (env variable: NSS_LOG_FILE).

verbose = Field(default=0, description='Verbosity level (0=INFO, 1=DEBUG, 2=DEBUG_DEPENDENCIES)') class-attribute instance-attribute

Verbosity level (0=INFO, 1=DEBUG, 2=DEBUG_DEPENDENCIES).

wandb_mode = Field(default=None, description='WandB mode override') class-attribute instance-attribute

WandB mode override (online, offline, or disabled).

wandb_project = Field(default=None, description='WandB project override') class-attribute instance-attribute

WandB project name override.

wandb_upload_evaluation_report = Field(default=True, validation_alias=(AliasChoices('wandb_upload_evaluation_report', 'NSS_WANDB_UPLOAD_EVALUATION_REPORT')), description='Whether the CLI uploads the final evaluation HTML report and artifact to WandB.') class-attribute instance-attribute

Whether the CLI uploads the final evaluation HTML report and artifact to WandB.

synthesis_overrides = Field(default_factory=dict, description='Nested dict of SafeSynthesizerParameters overrides from CLI') class-attribute instance-attribute

Nested dict of SafeSynthesizerParameters overrides from CLI.

Populated from --data__*, --training__*, etc. options via parse_overrides.

dataset_registry = Field(default=None, validation_alias=(AliasChoices('dataset_registry', 'NSS_DATASET_REGISTRY')), description='URL or path to a dataset registry YAML file') class-attribute instance-attribute

URL or path to a dataset registry YAML file (env: NSS_DATASET_REGISTRY).

inference_endpoint_url = Field(default=None, validation_alias=(AliasChoices('inference_endpoint_url', 'NSS_INFERENCE_ENDPOINT')), description='OpenAI-compatible inference endpoint URL for LLM-assisted PII plan discovery') class-attribute instance-attribute

OpenAI-compatible PII inference endpoint (env: NSS_INFERENCE_ENDPOINT).

inference_api_key = Field(default=None, validation_alias=(AliasChoices('inference_api_key', 'NSS_INFERENCE_KEY')), description='API key for the PII inference endpoint') class-attribute instance-attribute

PII inference API key (env: NSS_INFERENCE_KEY).

inference_model_id = Field(default=None, validation_alias=(AliasChoices('inference_model_id', 'NSS_INFERENCE_MODEL')), description='Model ID served by the PII inference endpoint') class-attribute instance-attribute

PII inference model ID (env: NSS_INFERENCE_MODEL).

inference_timeout_seconds = Field(default=None, validation_alias=(AliasChoices('inference_timeout_seconds', 'NSS_INFERENCE_TIMEOUT')), description='Per-request timeout in seconds for PII inference') class-attribute instance-attribute

PII inference per-request timeout (env: NSS_INFERENCE_TIMEOUT).

Overrides a local profile's request timeout; defaults to 60 seconds otherwise.

inference_request_options = Field(default=None, validation_alias=(AliasChoices('inference_request_options', 'NSS_INFERENCE_REQUEST_OPTIONS')), description='JSON object of chat-completions fields sent with every PII inference request') class-attribute instance-attribute

Extra PII inference request fields as JSON (env: NSS_INFERENCE_REQUEST_OPTIONS).

Overrides a local profile's request options field by field; a null value drops a field. Fields left out use the server's defaults.

inference_local_profile = Field(default=None, validation_alias=(AliasChoices('inference_local_profile', 'NSS_INFERENCE_LOCAL_PROFILE')), description='Bundled profile name or YAML path for a managed local vLLM PII inference server') class-attribute instance-attribute

Managed local PII inference server profile (env: NSS_INFERENCE_LOCAL_PROFILE).

NSS starts the server only for LLM-assisted plan discovery and stops it before planning returns. When this and the endpoint are both unset, the configured model ID selects a bundled profile.

huggingface_remote = Field(default=None, validation_alias=(AliasChoices('huggingface_remote')), description='Whether to allow Hugging Face remote downloads for Hub assets') class-attribute instance-attribute

Whether to allow Hugging Face remote downloads for Hub assets (base model, etc.).

None leaves the environment untouched. True / False is propagated to the standard HF_HUB_OFFLINE and TRANSFORMERS_OFFLINE variables (the canonical env switch) by _propagate_runtime_settings_to_env; there is no separate NSS env var.

explicit_cli_fields property

Fields explicitly supplied by Click rather than loaded from the environment.

effective_artifact_path property

Effective artifact path, falling back to DEFAULT_ARTIFACTS_PATH.

effective_log_format property

Effective log format, falling back to observability settings.

effective_log_color property

Effective log color setting, falling back to observability settings.

effective_wandb_mode property

Effective wandb mode, falling back to wandb settings.

effective_wandb_project property

Effective wandb project, falling back to wandb settings.

validate_wandb_mode(v) classmethod

Coerce string or None to WandbMode enum, passing through enum values unchanged.

Source code in src/nemo_safe_synthesizer/cli/settings.py
@field_validator("wandb_mode", mode="before")
@classmethod
def validate_wandb_mode(cls, v: str | WandbMode | None) -> WandbMode | None:
    """Coerce string or None to ``WandbMode`` enum, passing through enum values unchanged."""
    if v is None:
        return None
    if isinstance(v, WandbMode):
        return v
    return WandbMode(v)

validate_inference_settings()

Check the PII inference values with the same reader planning uses, so errors appear before a run.

Source code in src/nemo_safe_synthesizer/cli/settings.py
@model_validator(mode="after")
def validate_inference_settings(self) -> CLISettings:
    """Check the PII inference values with the same reader planning uses, so errors appear before a run."""
    InferenceEnvironment.from_environ(self.inference_environ())
    return self

inference_environ()

Return the NSS_INFERENCE_* variables for the PII inference values that are set.

Source code in src/nemo_safe_synthesizer/cli/settings.py
def inference_environ(self) -> dict[str, str]:
    """Return the ``NSS_INFERENCE_*`` variables for the PII inference values that are set."""
    values = {
        ENDPOINT_ENV: self.inference_endpoint_url,
        KEY_ENV: self.inference_api_key,
        MODEL_ENV: self.inference_model_id,
        TIMEOUT_ENV: None if self.inference_timeout_seconds is None else f"{self.inference_timeout_seconds:g}",
        REQUEST_OPTIONS_ENV: self.inference_request_options,
        LOCAL_PROFILE_ENV: self.inference_local_profile,
    }
    return {name: value for name, value in values.items() if value is not None}

validate_inference_timeout_seconds(v) classmethod

Treat a blank value as unset, as the PII inference client does.

Source code in src/nemo_safe_synthesizer/cli/settings.py
@field_validator("inference_timeout_seconds", mode="before")
@classmethod
def validate_inference_timeout_seconds(cls, v: float | str | None) -> float | str | None:
    """Treat a blank value as unset, as the PII inference client does."""
    if isinstance(v, str) and not v.strip():
        return None
    return v

validate_verbose(v) classmethod

Coerce string or None to int, defaulting to 0.

Source code in src/nemo_safe_synthesizer/cli/settings.py
@field_validator("verbose", mode="before")
@classmethod
def validate_verbose(cls, v: int | str | None) -> int:
    """Coerce string or None to int, defaulting to 0."""
    if v is None:
        return 0
    if isinstance(v, str):
        return int(v)
    return v

from_cli_kwargs(**kwargs) classmethod

Create settings from Click kwargs, filtering None values.

CLI arguments take precedence over environment variables. None values are filtered out so env vars can fill in.

Parameters:

Name Type Description Default
**kwargs Any

Keyword arguments from Click command

{}

Returns:

Type Description
CLISettings

CLISettings instance with CLI values merged over env vars

Source code in src/nemo_safe_synthesizer/cli/settings.py
@classmethod
def from_cli_kwargs(cls, **kwargs: Any) -> CLISettings:
    """Create settings from Click kwargs, filtering None values.

    CLI arguments take precedence over environment variables.
    None values are filtered out so env vars can fill in.

    Args:
        **kwargs: Keyword arguments from Click command

    Returns:
        CLISettings instance with CLI values merged over env vars
    """
    # Filter out None values so env vars can provide defaults
    filtered = {k: v for k, v in kwargs.items() if v is not None}
    settings = cls(**filtered)
    settings._explicit_cli_fields = frozenset(filtered)
    return settings