docs: Update docstrings in src/cli/ (#154)

# Summary

Add and update docstrings in `src/cli/` based on STYLE_GUIDE.md.

---------

Made with [Cursor](https://cursor.com/)

Signed-off-by: Kendrick Boyd <kendrickb@nvidia.com>

Author: kendrickb-nvidia

src/nemo_safe_synthesizer/cli/artifact_structure.py

@@ -1,6 +1,12 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
+"""CLI entry points for artifact management.
+
+Provides CLI commands for inspecting and cleaning up artifact directories
+produced by Safe Synthesizer runs.
+"""
+
 from __future__ import annotations
 
 import shutil
@@ -14,7 +20,7 @@
 @click.group(invoke_without_command=True)
 @click.pass_context
 def artifacts(ctx: click.Context):
-    """Artifacts management commands."""
+    """Artifact management commands."""
     pass
 
 

src/nemo_safe_synthesizer/cli/artifacts.py

@@ -1,6 +1,12 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
+"""Top-level CLI group for Safe Synthesizer.
+
+Assembles the ``config``, ``run``, and ``artifacts`` subcommand groups
+into a single Python Click entry point.
+"""
+
 from __future__ import annotations
 
 import click

src/nemo_safe_synthesizer/cli/cli.py

@@ -1,6 +1,12 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
+"""CLI entry points for configuration management.
+
+Each command loads or creates a ``SafeSynthesizerParameters`` model, optionally applies
+CLI overrides, and either validates, prints, or writes the result.
+"""
+
 from __future__ import annotations
 
 import click

src/nemo_safe_synthesizer/cli/config.py

@@ -24,29 +24,29 @@
 class DatasetInfo(BaseModel):
     """Entry in the dataset registry."""
 
-    name: str
-    """Short name of the dataset.
-
-    Used to fetch the dataset from the registry.
-    """
-
-    url: str
-    """URL or path to the dataset.
-
-    If a relative path, it is joined with the base_url from the registry if
-    present.
-    """
-
-    overrides: dict[str, Any] | None = None
-    """Config overrides for this dataset.
-
-    These overrides take precendence over the values from the config file in
-    the CLI, but are themselves overridden by any CLI args specifying config
-    parameters.
-    """
-
-    load_args: dict[str, Any] | None = None
-    """Extra arguments needed by the data reader for a this dataset."""
+    name: str = Field(description=("Short name of the dataset. Used to fetch the dataset from the registry by name."))
+
+    url: str = Field(
+        description=(
+            "URL or path to the dataset. "
+            "If a relative path, it is joined with the base_url from the registry if present."
+        )
+    )
+
+    overrides: dict[str, Any] | None = Field(
+        default=None,
+        description=(
+            "Config overrides for this dataset. "
+            "These overrides take precedence over the values from the config file in "
+            "the CLI, but are themselves overridden by any CLI args specifying config "
+            "parameters."
+        ),
+    )
+
+    load_args: dict[str, Any] | None = Field(
+        default=None,
+        description="Extra arguments needed by the data reader for this dataset.",
+    )
 
     _registry: DatasetRegistry | None = None
     """Private attribute to keep a reference to an associated registry.
@@ -81,7 +81,16 @@ def get_url(self) -> str:
         return self.url
 
     def fetch(self) -> pd.DataFrame:
-        """Fetch the dataset and return a pandas DataFrame."""
+        """Fetch the dataset and return a pandas DataFrame.
+
+        Infers the file format from the URL extension and merges any ``load_args`` on top of per-format defaults.
+
+        Returns:
+            The dataset as a DataFrame.
+
+        Raises:
+            ValueError: If the file extension is not supported.
+        """
         url = self.get_url()
 
         logger.info(f"Reading dataset from {url}")
@@ -116,27 +125,45 @@ def fetch(self) -> pd.DataFrame:
 
 
 class DatasetRegistry(BaseModel):
-    """Registry of datasets for easy reference by name."""
-
-    datasets: list[DatasetInfo] = Field(default_factory=list)
-    """List of datasets in the registry."""
+    """Registry of datasets for easy reference by name.
 
-    base_url: str | None = None
-    """Base URL for the registry.
+    Datasets can be looked up by name via ``get_dataset``. If the name is
+    not in the registry, a new ``DatasetInfo`` is created on-the-fly treating
+    the name as a literal URL or path.
 
-    Any relative paths will be prepended with the base_url before attempting to load the dataset.
-    This only applies to the datasets in the registry which have a relative url.
+    When constructed, the DatasetRegistry automatically adds back-references to each entry in ``self.datasets`` so the
+    ``DatasetInfo`` instances can resolve ``base_url``.
     """
 
+    datasets: list[DatasetInfo] = Field(default_factory=list, description="List of datasets in the registry.")
+
+    base_url: str | None = Field(
+        default=None,
+        description=(
+            "Base URL for the registry. Any relative paths will be prepended with the base_url before "
+            "attempting to load the dataset. This only applies to the datasets in the registry which have "
+            "a relative url."
+        ),
+    )
+
     def __init__(self, **data):
         super().__init__(**data)
         for dataset in self.datasets:
             dataset._registry = self
 
     def get_dataset(self, url: str) -> DatasetInfo:
-        """Get a dataset from the registry.
+        """Look up a dataset by name, creating an ad-hoc entry if not found.
+
+        When ``url`` matches a registered name the corresponding entry is
+        returned. Otherwise a new ``DatasetInfo`` is created with the raw
+        ``url`` as both name and path (without a registry back-reference, so
+        relative paths resolve against the working directory).
+
+        Args:
+            url: Dataset name, URL, or file path.
 
-        Automatically adds a new Dataset with name url if it doesn't exist in the registry.
+        Returns:
+            Matching or newly created ``DatasetInfo``.
         """
         for dataset in self.datasets:
             if dataset.name == url:
@@ -153,7 +180,17 @@ def get_dataset(self, url: str) -> DatasetInfo:
 
     @classmethod
     def from_yaml(cls, path: str | Path) -> Self:
-        """Load a DatasetRegistry from a YAML file."""
+        """Load a ``DatasetRegistry`` from a YAML file.
+
+        Args:
+            path: Path to the YAML file.
+
+        Returns:
+            Parsed registry with back-references set on each dataset.
+
+        Raises:
+            FileNotFoundError: If ``path`` does not exist.
+        """
         if not Path(path).exists():
             raise FileNotFoundError(f"File {path} does not exist")
         with open(path, "r") as f:

src/nemo_safe_synthesizer/cli/datasets.py

@@ -4,9 +4,10 @@
 """CLI run commands for Safe Synthesizer.
 
 This module provides the run command group for the Safe Synthesizer pipeline:
-- `run` (default): Full end-to-end pipeline
-- `run train`: Training stage only
-- `run generate`: Generation stage only (requires trained model)
+
+- ``run`` (default): Full end-to-end pipeline
+- ``run train``: Training stage only
+- ``run generate``: Generation stage only (requires trained model)
 """
 
 from __future__ import annotations

src/nemo_safe_synthesizer/cli/run.py

@@ -7,6 +7,7 @@
 (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
@@ -58,80 +59,115 @@ class CLISettings(BaseSettings):
         env_file_encoding="utf-8",
     )
 
-    # Compose existing settings (automatically populated from env vars)
-    # These are NOT loaded from env vars by CLISettings - they load their own
-    # We use default_factory to create fresh instances that read env vars
-    observability: NSSObservabilitySettings = Field(default_factory=NSSObservabilitySettings)
-    wandb: WandbSettings = Field(default_factory=WandbSettings)
+    observability: NSSObservabilitySettings = Field(
+        default_factory=NSSObservabilitySettings, description="Observability sub-settings (log level, format, color)."
+    )
+    """Observability sub-settings (log level, format, color).
+
+    Loaded from its own environment variables; not populated by ``CLISettings``.
+    """
+
+    wandb: WandbSettings = Field(default_factory=WandbSettings, description="WandB settings (mode, project, phase).")
+    """WandB settings (mode, project, phase).
+
+    Loaded from its own environment variables; not populated by ``CLISettings``.
+    """
 
-    # CLI-specific settings (paths)
-    # Note: AliasChoices allows both the field name (for CLI kwargs) and env var name to work
     url: str | None = Field(default=None, description="Dataset URL, name, or path to CSV")
+    """Dataset URL, name, or path to CSV."""
+
     config_path: str | None = Field(
         default=None,
         validation_alias=AliasChoices("config_path", "NSS_CONFIG"),
         description="Path to YAML config file",
     )
+    """Path to YAML config file (env variable: ``NSS_CONFIG``)."""
+
     artifact_path: str | None = Field(
         default=None,
         validation_alias=AliasChoices("artifact_path", "NSS_ARTIFACTS_PATH"),
         description="Base directory for all runs",
     )
+    """Base directory for all runs (env variable: ``NSS_ARTIFACTS_PATH``)."""
+
     run_path: str | None = Field(
         default=None,
         description="Explicit path for this run's output directory",
     )
+    """Explicit path for this run's output directory.
+
+    When specified, overrides ``artifact_path`` and skips the
+    ``<project>/<timestamp>`` directory layout.
+    """
+
     output_file: str | None = Field(
         default=None,
         description="Path to output CSV file",
     )
+    """Path to output CSV file, overriding the default workdir location."""
 
-    # Logging settings (can override observability defaults from CLI)
     log_format: Literal["json", "plain"] | None = Field(
         default=None,
         validation_alias=AliasChoices("log_format", "NSS_LOG_FORMAT"),
         description="Log format for console output",
     )
+    """Log format for console output (env variable: ``NSS_LOG_FORMAT``).
+
+    File logging is always JSON regardless of this setting.
+    """
+
     log_color: bool | None = Field(
         default=None,
         description="Whether to colorize console output",
     )
+    """Whether to colorize console output."""
+
     log_file: str | None = Field(
         default=None,
         validation_alias=AliasChoices("log_file", "NSS_LOG_FILE"),
         description="Path to log file",
     )
+    """Path to log file (env variable: ``NSS_LOG_FILE``)."""
+
     verbose: int = Field(
         default=0,
         description="Verbosity level (0=INFO, 1=DEBUG, 2=DEBUG_DEPENDENCIES)",
     )
+    """Verbosity level (0=INFO, 1=DEBUG, 2=DEBUG_DEPENDENCIES)."""
 
-    # WandB settings (can override wandb defaults from CLI)
     wandb_mode: WandbMode | None = Field(
         default=None,
         description="WandB mode override",
     )
+    """WandB mode override (online, offline, or disabled)."""
+
     wandb_project: str | None = Field(
         default=None,
         description="WandB project override",
     )
+    """WandB project name override."""
 
-    # Synthesis parameter overrides (populated from --data__*, --training__*, etc.)
     synthesis_overrides: dict[str, Any] = Field(
         default_factory=dict,
         description="Nested dict of SafeSynthesizerParameters overrides from CLI",
     )
+    """Nested dict of ``SafeSynthesizerParameters`` overrides from CLI.
+
+    Populated from ``--data__*``, ``--training__*``, etc. options via
+    ``parse_overrides``.
+    """
 
     dataset_registry: str | None = Field(
         default=None,
         validation_alias=AliasChoices("dataset_registry", "NSS_DATASET_REGISTRY"),
         description="URL or path to a dataset registry YAML file",
     )
+    """URL or path to a dataset registry YAML file (env: ``NSS_DATASET_REGISTRY``)."""
 
     @field_validator("wandb_mode", mode="before")
     @classmethod
     def validate_wandb_mode(cls, v: str | WandbMode | None) -> WandbMode | None:
-        """Convert string to WandbMode enum if needed."""
+        """Coerce string or None to ``WandbMode`` enum, passing through enum values unchanged."""
         if v is None:
             return None
         if isinstance(v, WandbMode):
@@ -141,7 +177,7 @@ def validate_wandb_mode(cls, v: str | WandbMode | None) -> WandbMode | None:
     @field_validator("verbose", mode="before")
     @classmethod
     def validate_verbose(cls, v: int | str | None) -> int:
-        """Ensure verbose is an integer."""
+        """Coerce string or None to int, defaulting to 0."""
         if v is None:
             return 0
         if isinstance(v, str):
@@ -167,35 +203,35 @@ def from_cli_kwargs(cls, **kwargs: Any) -> CLISettings:
 
     @property
     def effective_artifact_path(self) -> Path:
-        """The effective artifact path, using default if not set."""
+        """Effective artifact path, falling back to ``DEFAULT_ARTIFACTS_PATH``."""
         if self.artifact_path:
             return Path(self.artifact_path)
         return DEFAULT_ARTIFACTS_PATH
 
     @property
     def effective_log_format(self) -> Literal["json", "plain"]:
-        """The effective log format, falling back to observability settings."""
+        """Effective log format, falling back to observability settings."""
         if self.log_format is not None:
             return self.log_format
         return self.observability.nss_log_format or "plain"
 
     @property
     def effective_log_color(self) -> bool:
-        """The effective log color setting, falling back to observability settings."""
+        """Effective log color setting, falling back to observability settings."""
         if self.log_color is not None:
             return self.log_color
         return self.observability.nss_log_color
 
     @property
     def effective_wandb_mode(self) -> WandbMode:
-        """The effective wandb mode, falling back to wandb settings."""
+        """Effective wandb mode, falling back to wandb settings."""
         if self.wandb_mode is not None:
             return self.wandb_mode
         return self.wandb.wandb_mode
 
     @property
     def effective_wandb_project(self) -> str | None:
-        """The effective wandb project, falling back to wandb settings."""
+        """Effective wandb project, falling back to wandb settings."""
         if self.wandb_project is not None:
             return self.wandb_project
         return self.wandb.wandb_project