Skip to content

generation

generation

Contract for replacement value generation.

Concrete generators live in replacement.generators; this module does not import them.

Classes:

Name Description
ReplacementGenerationRequest

Inputs required to deterministically generate one replacement value.

ReplacementGenerator

Generate synthetic values behind the replacement executor's private seam.

ReplacementGenerationRequest(entity_type, original_value, effective_dependency_tuple, pattern, seed, resolved_dependency_values=(), full_name_pattern=None, keep_original_locality=False) dataclass

Inputs required to deterministically generate one replacement value.

Attributes:

Name Type Description
entity_type EntityType

Normalized entity type of the value to generate.

original_value str

Exact accepted substring for free text, or the normalized_value of a

effective_dependency_tuple EffectiveDependencyTuple

Current value of each depends_on column for this row, in plan order.

pattern str | None

Plan pattern the generated value must follow, or None for the entity default.

seed int

Seed that makes generation deterministic for equal requests.

resolved_dependency_values ResolvedDependencyValues

Person-sampler values each conditioner may match, from data_to_sampler_value_mapping.

full_name_pattern str | None

Pattern of the replaced full-name column this value depends on, or None.

keep_original_locality bool

Whether the original value's locality text is kept after the generated street.

entity_type instance-attribute

Normalized entity type of the value to generate.

original_value = field(repr=False) class-attribute instance-attribute

Exact accepted substring for free text, or the normalized_value of a CanonicalValue for structured data. Excluded from repr because it is PII.

effective_dependency_tuple = field(repr=False) class-attribute instance-attribute

Current value of each depends_on column for this row, in plan order.

A dependency on another replaced column carries its already-replaced value, so an email can be built from the synthetic first and last names. A read-only conditioner such as gender carries the dataset value. Excluded from repr because the values may contain PII.

pattern instance-attribute

Plan pattern the generated value must follow, or None for the entity default.

The default for an email that depends on names is {first}.{last}##@{domain}, built from the dependency values.

seed instance-attribute

Seed that makes generation deterministic for equal requests.

resolved_dependency_values = field(default=(), repr=False) class-attribute instance-attribute

Person-sampler values each conditioner may match, from data_to_sampler_value_mapping.

Used only to filter the sampler, for example gender Woman resolved to ("female",). Generators still read effective_dependency_tuple for values they render, such as names in an email. Excluded from repr because the values derive from PII.

full_name_pattern = None class-attribute instance-attribute

Pattern of the replaced full-name column this value depends on, or None.

Used to read the first, middle, and last names out of that column's value, for example from Hopper, Grace written by {Last}, {First}.

keep_original_locality = False class-attribute instance-attribute

Whether the original value's locality text is kept after the generated street.

When True, street-address generators return only a street and do not append linked city, state, ZIP, or country values; the executor adds back the original text that followed the street. For example, only the street of "489 Park Blvd, Mesa, IA 76237" is generated, and ", Mesa, IA 76237" is kept.

ReplacementGenerator

Bases: Protocol

Generate synthetic values behind the replacement executor's private seam.

Implementations must be deterministic for equal requests. Mapping scope, cache reuse, call timing, and dataframe mutation remain responsibilities of the replacement executor.

Methods:

Name Description
generate

Return one synthetic value satisfying request.

generate(request)

Return one synthetic value satisfying request.

Source code in src/nemo_safe_synthesizer/pii_replacer/replacement/generation.py
def generate(self, request: ReplacementGenerationRequest) -> str:
    """Return one synthetic value satisfying ``request``."""