docs: add/update docstrings for holdout and root files (#170)

<!-- SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION
& AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

<!-- Thank you for contributing to Safe Synthesizer! -->

# Summary
<!-- Brief description of changes -->

Added/audited docstrings for all the files in
`src/nemo_safe_synthesizer/` root and in `holdout/`. Had agent check for
style guide and correctness

## Pre-Review Checklist

<!-- These checks should be completed before a PR is reviewed, -->
<!-- but you can submit a draft early to indicate that the issue is
being worked on. -->

Ensure that the following pass:

- [x] `make format && make check` or via prek validation.
- [x] `make test` passes locally
- [ ] `make test-e2e` passes locally
- [ ] `make test-ci-container` passes locally (recommended)

## Pre-Merge Checklist

<!-- These checks need to be completed before a PR is merged, -->
<!-- but as PRs often change significantly during review, -->
<!-- it's OK for them to be incomplete when review is first requested.
-->

- [ ] New or updated tests for any fix or new behavior
- [x] Updated documentation for new features and behaviors, including
docstrings for API docs.

## Other Notes

<!-- Please add the issue number that should be closed when this PR is
merged. -->
- Closes #<issue>

Signed-off-by: Nina Xu <19981858+nina-xu@users.noreply.github.com>

Author: nina-xu

src/nemo_safe_synthesizer/__main__.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
+"""Entry point for ``python -m nemo_safe_synthesizer``."""
+
 import os
 import sys
 

src/nemo_safe_synthesizer/defaults.py

@@ -1,7 +1,12 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-"""Collection of default settings for the Nemo Safe Synthesizer implementation."""
+"""Default constants for the Safe Synthesizer pipeline.
+
+Includes artifact paths, logging parameters, training and generation
+defaults, prompt templates, and miscellaneous constants shared across
+modules.
+"""
 
 from pathlib import Path
 

src/nemo_safe_synthesizer/errors.py

@@ -1,52 +1,62 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-"""Custom error classes"""
+"""Error hierarchy for Safe Synthesizer.
+
+All public exceptions inherit from ``SafeSynthesizerError``. Errors on
+the user side (bad data, bad config, generation failure) inherit from
+``UserError`` and a matching built-in (``ValueError``, ``RuntimeError``)
+so callers can catch either.
+
+Classes:
+    SafeSynthesizerError: Base for all known errors.
+    UserError: Invalid usage (bad inputs, uninitialized state).
+    InternalError: Library bug (equivalent to HTTP 5xx).
+    DataError: Problems with training data (NaNs, unsupported types).
+    ParameterError: Invalid config or parameter input.
+    GenerationError: Sampling/generation failures.
+"""
 
 
 class SafeSynthesizerError(Exception):
-    """Base class for all known errors that can be thrown from nemo_safe_synthesizer."""
+    """Base class for all known Safe Synthesizer errors."""
 
 
 class UserError(SafeSynthesizerError):
-    """
-    Base class for errors that are caused by invalid usage. This is usually caused
-    by invalid input parameters, by calling methods on a class that is not initialized,
-    etc.
-    If you are receiving this error, please see documentation of the corresponding
-    classes and check your inputs.
+    """Invalid usage -- bad input parameters, uninitialized state, etc.
+
+    If you receive this error, check the documentation for the corresponding
+    class and verify your inputs.
     """
 
 
 class InternalError(SafeSynthesizerError, RuntimeError):
-    """
-    Error that indicate invalid internal state.
-
-    If you're using safe_synthesizer through documented interfaces, this usually
-    indicates a bug in safe_synthesizer itself.
-    If you're using not documented interfaces, this could indicate invalid usage.
+    """Invalid internal state indicating a bug in Safe Synthesizer.
 
-    This class of errors is equivalent to 5xx status codes in HTTP protocol.
+    When using documented interfaces this usually indicates a library bug.
+    When using undocumented interfaces it may indicate invalid usage.
+    Equivalent to HTTP 5xx status codes.
     """
 
 
 class DataError(UserError, ValueError):
-    """
-    Represents problems with training data before work is actually attempted.
-    For example: data contains values that are not supported by the model that is
-    being used: infinity, too many NaNs, nested data, etc.
+    """Problems with training data before work is attempted.
+
+    Examples: data contains infinity, too many NaNs, nested structures,
+    or types unsupported by the model.
     """
 
 
 class ParameterError(UserError, ValueError):
-    """
-    Represents errors with configurations or parameter input to user-facing methods.
-    For example: config referencing column that is not present in the data.
+    """Invalid configuration or parameter input to user-facing methods.
+
+    Examples: config references a column not present in the data, invalid
+    combination of parameters.
     """
 
 
 class GenerationError(UserError, RuntimeError):
-    """
-    Represents errors happening during sampling/generation.
-    For example: rejection sampling fails, invalid record threshold met.
+    """Errors during sampling or generation.
+
+    Examples: rejection sampling fails, invalid record threshold met.
     """

src/nemo_safe_synthesizer/holdout/holdout.py

@@ -1,6 +1,13 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
+"""Train/test splitting for evaluation holdout.
+
+Provides two splitting strategies -- naive (random) and grouped (preserving
+group membership) -- and a ``Holdout`` class that selects the appropriate
+strategy based on pipeline configuration.
+"""
+
 import pandas as pd
 from sklearn.model_selection import GroupShuffleSplit, train_test_split
 
@@ -23,6 +30,20 @@
 
 
 def naive_train_test_split(df, test_size, random_state=None) -> DataFrameOptionalTuple:
+    """Split a dataframe into train and test sets with a random shuffle.
+
+    Thin wrapper around ``sklearn.model_selection.train_test_split`` that
+    resets the index on both resulting dataframes.
+
+    Args:
+        df: Input dataframe to split.
+        test_size: Number of rows (int) or fraction (float) to hold out.
+        random_state: Seed for reproducibility.
+
+    Returns:
+        Tuple of ``(train_df, test_df)``, or ``(train_df, None)`` if the
+        split produces no test set.
+    """
     train, test = train_test_split(df, test_size=test_size, random_state=random_state)
     if test is None:
         return train, None
@@ -31,6 +52,26 @@ def naive_train_test_split(df, test_size, random_state=None) -> DataFrameOptiona
 
 
 def grouped_train_test_split(df, test_size, group_by, random_state=None) -> DataFrameOptionalTuple:
+    """Split a dataframe so that all rows sharing a group stay in the same fold.
+
+    Uses ``GroupShuffleSplit`` with 20 candidate splits and picks the one
+    whose test-set size is closest to the requested ``test_size``.  If
+    ``test_size`` exceeds the number of groups, equals 0, or equals 1, it
+    falls back to ``DEFAULT_HOLDOUT``.
+
+    Args:
+        df: Input dataframe to split.
+        test_size: Desired number of test rows (int) or fraction (float).
+        group_by: Column name whose values define the groups.
+        random_state: Seed for reproducibility.
+
+    Returns:
+        Tuple of ``(train_df, test_df)``, or ``(df, None)`` if no valid
+        grouped split could be produced.
+
+    Raises:
+        ValueError: If the ``group_by`` column contains missing values.
+    """
     # Do not continue the split process if the groupby column has missing values.
     if df[group_by].isna().any():
         msg = f"Group by column '{group_by}' has missing values. Please remove/replace them."
@@ -62,13 +103,49 @@ def grouped_train_test_split(df, test_size, group_by, random_state=None) -> Data
 
 
 class Holdout:
+    """Config-driven train/test splitter for the evaluation holdout set.
+
+    Reads holdout parameters from the pipeline configuration and delegates
+    to either ``naive_train_test_split`` or ``grouped_train_test_split``
+    depending on whether a ``group_training_examples_by`` column is set.
+
+    The holdout size is resolved as follows:
+
+      - If ``holdout < 1.0``, it is treated as a fraction of the input rows.
+      - If ``holdout >= 1.0``, it is treated as an absolute row count.
+      - The result is clamped to ``max_holdout`` and must be at least
+        ``MIN_HOLDOUT`` rows.
+
+    Args:
+        config: Pipeline parameters providing ``holdout``, ``max_holdout``,
+            ``group_training_examples_by``, and ``random_state``.
+    """
+
     def __init__(self, config: SafeSynthesizerParameters):
         self.holdout = config.get("holdout")
         self.max_holdout = config.get("max_holdout")
         self.group_by = config.get("group_training_examples_by")
         self.random_state = config.get("random_state")
 
     def train_test_split(self, input_df: pd.DataFrame) -> DataFrameOptionalTuple:
+        """Split the input dataframe into training and holdout test sets.
+
+        Returns the full dataframe with no test set when holdout is disabled
+        (``holdout == 0`` or ``max_holdout == 0``).
+
+        Args:
+            input_df: The full input dataframe to split.
+
+        Returns:
+            Tuple of ``(train_df, test_df)``, or ``(train_df, None)`` when
+            holdout is disabled or the grouped split fails.
+
+        Raises:
+            ValueError: If the input dataframe has fewer than
+                ``MIN_RECORDS_FOR_TEXT_AND_PRIVACY_METRICS`` rows, if the
+                computed holdout is smaller than ``MIN_HOLDOUT``, or if
+                the ``group_by`` column contains missing values.
+        """
         if self.holdout == 0 or self.max_holdout == 0:
             return input_df, None