Skip to content

config_builder

config_builder

Builder-pattern configuration layer for Safe Synthesizer.

Classes:

Name Description
ConfigBuilder

Fluent builder for assembling Safe Synthesizer configuration.

ConfigBuilder(config=None, *, unknown_fields=None)

Fluent builder for assembling Safe Synthesizer configuration.

Accumulates per-section configuration objects (data, training, generation, evaluation, privacy, PII replacement, and time-series) via with_* methods. Call resolve() (or let SafeSynthesizer do it) to collapse them into a single SafeSynthesizerParameters.

Each with_* method accepts an optional sparse typed config or raw mapping, plus **kwargs overrides. Keyword arguments take precedence over fields in the source. All with_* methods return Self so subclasses preserve their concrete type through fluent chains.

Parameters:

Name Type Description Default
config SafeSynthesizerParameters | None

Optional pre-built parameters. When supplied, the individual _*_config attributes are seeded from its sections.

None
unknown_fields UnknownFieldBehavior | None

Optional SDK-wide override for raw mapping validation. Set it at construction time so every section uses the same policy.

None

Methods:

Name Description
with_data_source

Set the data source for synthetic data generation.

with_data

Configure data processing settings.

with_train

Configure training hyperparameters.

with_generate

Configure generation settings.

with_time_series

Configure time-series synthesis settings.

with_differential_privacy

Configure differential privacy settings.

with_replace_pii

Request or disable PII replacement.

with_evaluate

Configure evaluation settings.

resolve

Finalize configuration and data source.

Source code in src/nemo_safe_synthesizer/sdk/config_builder.py
def __init__(
    self,
    config: SafeSynthesizerParameters | None = None,
    *,
    unknown_fields: UnknownFieldBehavior | None = None,
) -> None:
    self._nss_config = config.model_copy(deep=True) if config is not None else None
    self._unknown_fields_override = validate_unknown_fields(unknown_fields) if unknown_fields is not None else None
    if self._nss_config is not None:
        self._emit_telemetry_config = self._nss_config.emit_telemetry
        self._evaluation_config = self._nss_config.evaluation
        self._replace_pii_config = self._nss_config.replace_pii
        self._preflight_config = self._nss_config.preflight
        self._privacy_config: DifferentialPrivacyHyperparams | None = self._nss_config.privacy
        self._training_config = self._nss_config.training
        self._generation_config = self._nss_config.generation
        self._data_config = self._nss_config.data
        self._time_series_config = self._nss_config.time_series
    else:
        self._data_config: DataParameters = DataParameters()
        self._evaluation_config: EvaluationParameters = EvaluationParameters()
        self._generation_config: GenerateParameters = GenerateParameters()
        self._replace_pii_config: ReplacePiiConfig | None = ReplacePiiConfig()
        self._preflight_config = PreflightParameters()
        self._privacy_config: DifferentialPrivacyHyperparams = DifferentialPrivacyHyperparams()
        self._training_config: TrainingHyperparams = TrainingHyperparams()
        self._time_series_config: TimeSeriesParameters = TimeSeriesParameters()
        self._emit_telemetry_config = _telemetry_enabled()

    self._data_source: DataSource | None = None
    self._data_source_csv: CsvSource | None = None
    self._hf_token_secret: str | None = None

with_data_source(df_source)

Set the data source for synthetic data generation.

Parameters:

Name Type Description Default
df_source DataSource

Training dataset as a pandas DataFrame, a path or URL to a CSV, Parquet, JSON, or JSONL file, or a CsvSource already read from a CSV file.

required

Returns:

Type Description
Self

This builder instance with the data source configured.

Source code in src/nemo_safe_synthesizer/sdk/config_builder.py
def with_data_source(self, df_source: DataSource) -> Self:
    """Set the data source for synthetic data generation.

    Args:
        df_source: Training dataset as a pandas DataFrame, a path or URL
            to a CSV, Parquet, JSON, or JSONL file, or a ``CsvSource``
            already read from a CSV file.

    Returns:
        This builder instance with the data source configured.
    """
    self._data_source = df_source
    self._data_source_csv = None
    return self

with_data(config=None, **kwargs)

Configure data processing settings.

Parameters:

Name Type Description Default
config DataParameters | RawConfig | None

Data configuration object or raw mapping. Fields that neither it nor kwargs set keep their current values.

None
**kwargs object

Field-level overrides (e.g. holdout_size).

{}

Returns:

Type Description
Self

This builder instance with data processing settings applied.

Source code in src/nemo_safe_synthesizer/sdk/config_builder.py
def with_data(self, config: DataParameters | RawConfig | None = None, **kwargs: object) -> Self:
    """Configure data processing settings.

    Args:
        config: Data configuration object or raw mapping. Fields that neither it
            nor ``kwargs`` set keep their current values.
        **kwargs: Field-level overrides (e.g. ``holdout_size``).

    Returns:
        This builder instance with data processing settings applied.
    """
    self._data_config = self._overlay_section(DataParameters, self._data_config, config, kwargs)
    return self

with_train(config=None, **kwargs)

Configure training hyperparameters.

Parameters:

Name Type Description Default
config TrainingHyperparams | RawConfig | None

Training configuration object or raw mapping. Fields that neither it nor kwargs set keep their current values.

None
**kwargs object

Field-level overrides (e.g. learning_rate).

{}

Returns:

Type Description
Self

This builder instance with training hyperparameters applied.

Source code in src/nemo_safe_synthesizer/sdk/config_builder.py
def with_train(self, config: TrainingHyperparams | RawConfig | None = None, **kwargs: object) -> Self:
    """Configure training hyperparameters.

    Args:
        config: Training configuration object or raw mapping. Fields that neither it
            nor ``kwargs`` set keep their current values.
        **kwargs: Field-level overrides (e.g. ``learning_rate``).

    Returns:
        This builder instance with training hyperparameters applied.
    """
    self._training_config = self._overlay_section(TrainingHyperparams, self._training_config, config, kwargs)
    return self

with_generate(config=None, **kwargs)

Configure generation settings.

Parameters:

Name Type Description Default
config GenerateParameters | RawConfig | None

Generation configuration object or raw mapping. Fields that neither it nor kwargs set keep their current values.

None
**kwargs object

Field-level overrides (e.g. num_records).

{}

Returns:

Type Description
Self

This builder instance with generation settings applied.

Source code in src/nemo_safe_synthesizer/sdk/config_builder.py
def with_generate(self, config: GenerateParameters | RawConfig | None = None, **kwargs: object) -> Self:
    """Configure generation settings.

    Args:
        config: Generation configuration object or raw mapping. Fields that neither it
            nor ``kwargs`` set keep their current values.
        **kwargs: Field-level overrides (e.g. ``num_records``).

    Returns:
        This builder instance with generation settings applied.
    """
    self._generation_config = self._overlay_section(GenerateParameters, self._generation_config, config, kwargs)
    return self

with_time_series(config=None, **kwargs)

Configure time-series synthesis settings.

Parameters:

Name Type Description Default
config TimeSeriesParameters | RawConfig | None

Time-series configuration object or raw mapping. Fields that neither it nor kwargs set keep their current values.

None
**kwargs object

Field-level overrides (e.g. time_column).

{}

Returns:

Type Description
Self

This builder instance with time-series synthesis settings applied.

Source code in src/nemo_safe_synthesizer/sdk/config_builder.py
def with_time_series(self, config: TimeSeriesParameters | RawConfig | None = None, **kwargs: object) -> Self:
    """Configure time-series synthesis settings.

    Args:
        config: Time-series configuration object or raw mapping. Fields that neither it
            nor ``kwargs`` set keep their current values.
        **kwargs: Field-level overrides (e.g. ``time_column``).

    Returns:
        This builder instance with time-series synthesis settings applied.
    """
    self._time_series_config = self._overlay_section(TimeSeriesParameters, self._time_series_config, config, kwargs)
    return self

with_differential_privacy(config=None, **kwargs)

Configure differential privacy settings.

Parameters:

Name Type Description Default
config DifferentialPrivacyHyperparams | RawConfig | None

DP configuration object or raw mapping. Fields that neither it nor kwargs set keep their current values.

None
**kwargs object

Field-level overrides (e.g. epsilon).

{}

Returns:

Type Description
Self

This builder instance with differential privacy settings applied.

Source code in src/nemo_safe_synthesizer/sdk/config_builder.py
def with_differential_privacy(
    self, config: DifferentialPrivacyHyperparams | RawConfig | None = None, **kwargs: object
) -> Self:
    """Configure differential privacy settings.

    Args:
        config: DP configuration object or raw mapping. Fields that neither it
            nor ``kwargs`` set keep their current values.
        **kwargs: Field-level overrides (e.g. ``epsilon``).

    Returns:
        This builder instance with differential privacy settings applied.
    """
    self._privacy_config = self._overlay_section(
        DifferentialPrivacyHyperparams, self._privacy_config, config, kwargs
    )
    return self

with_replace_pii(config=None, *, enable=True, **kwargs)

Request or disable PII replacement.

The configuration drives :meth:SafeSynthesizer.plan_pii_replacement. Pass enable=False to set replace_pii=None and run the synthesis pipeline without replacement.

Parameters:

Name Type Description Default
config ReplacePiiConfig | RawConfig | None

PII replacement configuration object or raw mapping. Fields that neither it nor kwargs set keep their current values, or their defaults when replacement was disabled.

None
enable bool

When False, disables PII replacement entirely and clears any previously set config.

True
**kwargs object

Field-level replacement configuration overrides.

{}

Returns:

Type Description
Self

This builder instance with PII replacement configured.

Raises:

Type Description
ValueError

If config is not a ReplacePiiConfig, raw mapping, or None.

Example::

builder = SafeSynthesizer().with_data_source(your_dataframe).with_replace_pii(config=custom_pii_config)
Source code in src/nemo_safe_synthesizer/sdk/config_builder.py
def with_replace_pii(
    self, config: ReplacePiiConfig | RawConfig | None = None, *, enable: bool = True, **kwargs: object
) -> Self:
    """Request or disable PII replacement.

    The configuration drives :meth:`SafeSynthesizer.plan_pii_replacement`.
    Pass ``enable=False`` to set ``replace_pii=None`` and run the synthesis
    pipeline without replacement.

    Args:
        config: PII replacement configuration object or raw mapping. Fields that neither it
            nor ``kwargs`` set keep their current values, or their defaults when replacement was
            disabled.
        enable: When ``False``, disables PII replacement entirely
            and clears any previously set config.
        **kwargs: Field-level replacement configuration overrides.

    Returns:
        This builder instance with PII replacement configured.

    Raises:
        ValueError: If ``config`` is not a ``ReplacePiiConfig``,
            raw mapping, or ``None``.

    Example::

        builder = SafeSynthesizer().with_data_source(your_dataframe).with_replace_pii(config=custom_pii_config)
    """
    if not enable:
        self._replace_pii_config = None
        return self

    if config is not None and not isinstance(config, ReplacePiiConfig | Mapping):
        raise ValueError(f"Config must be a ReplacePiiConfig, raw mapping, or None, got {config!r}")
    self._replace_pii_config = self._overlay_section(ReplacePiiConfig, self._replace_pii_config, config, kwargs)
    return self

with_evaluate(config=None, **kwargs)

Configure evaluation settings.

Parameters:

Name Type Description Default
config EvaluationParameters | RawConfig | None

Evaluation configuration object or raw mapping. Fields that neither it nor kwargs set keep their current values.

None
**kwargs object

Field-level overrides (e.g. enabled).

{}

Returns:

Type Description
Self

This builder instance with evaluation settings applied.

Source code in src/nemo_safe_synthesizer/sdk/config_builder.py
def with_evaluate(self, config: EvaluationParameters | RawConfig | None = None, **kwargs: object) -> Self:
    """Configure evaluation settings.

    Args:
        config: Evaluation configuration object or raw mapping. Fields that neither it
            nor ``kwargs`` set keep their current values.
        **kwargs: Field-level overrides (e.g. ``enabled``).

    Returns:
        This builder instance with evaluation settings applied.
    """
    self._evaluation_config = self._overlay_section(EvaluationParameters, self._evaluation_config, config, kwargs)
    return self

resolve()

Finalize configuration and data source.

Assembles the individual _*_config sections into a single SafeSynthesizerParameters and converts the data source (URL string or DataFrame) into a DataFrame.

Returns:

Type Description
Self

This builder instance with all configuration sections finalized.

Source code in src/nemo_safe_synthesizer/sdk/config_builder.py
def resolve(self) -> Self:
    """Finalize configuration and data source.

    Assembles the individual ``_*_config`` sections into a single
    ``SafeSynthesizerParameters`` and converts the data source
    (URL string or DataFrame) into a ``DataFrame``.

    Returns:
        This builder instance with all configuration sections finalized.
    """
    self._resolve_nss_config()
    self._resolve_datasource()
    return self