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_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.
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.
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).
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, description='Whether to colorize console output') class-attribute instance-attribute

Whether to colorize console output.

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.

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).

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_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}
    return cls(**filtered)