resolver
resolver
¶
Resolve one validated PII replacement plan from configuration and data.
Classes:
| Name | Description |
|---|---|
ColumnProfile |
Bounded descriptive evidence about one column for plan discovery. |
PlanDiscoveryInput |
Data and deterministic preparation supplied to discovery adapters. |
PlanDiscoverer |
Internal seam for producing the heuristic baseline plan. |
PlanEnhancer |
Internal seam for revising a heuristic baseline plan. |
HeuristicPlanDiscoverer |
Initial no-op heuristic adapter, ready for later rule discovery. |
Functions:
| Name | Description |
|---|---|
resolve_plan |
Resolve and validate one replacement plan. |
resolve_replacement_config |
Resolve the replacement plan and its data-to-sampler value mapping for |
ColumnProfile(column_name, dtype, non_null_count, unique_count, unique_ratio, samples)
dataclass
¶
Bounded descriptive evidence about one column for plan discovery.
PlanDiscoveryInput(dataframe, group_column, protected_columns, column_profiles)
dataclass
¶
Data and deterministic preparation supplied to discovery adapters.
group_column is the runtime consistency signal: a configured column
means replacements remain consistent within each group; None means
each record is replaced independently. This derived choice is intentionally
not part of the reusable replacement plan.
PlanDiscoverer
¶
PlanEnhancer
¶
DependencyMappingDiscoverer
¶
Bases: Protocol
Discover sampler-specific mappings for dependency-column values.
Methods:
| Name | Description |
|---|---|
discover_data_to_sampler_value_mapping |
Return sparse mappings for non-identity dependency values. |
discover_data_to_sampler_value_mapping(dataframe, plan, catalog)
¶
Return sparse mappings for non-identity dependency values.
Source code in src/nemo_safe_synthesizer/pii_replacer/planning/resolver.py
HeuristicPlanDiscoverer
¶
Bases: PlanDiscoverer
Initial no-op heuristic adapter, ready for later rule discovery.
Methods:
| Name | Description |
|---|---|
discover |
Return an empty plan for later heuristic discovery. |
discover(discovery_input)
¶
Return an empty plan for later heuristic discovery.
resolve_plan(df, config, data_config, time_series=None, *, discoverer=None, enhancer=None, check_pattern_coverage=True)
¶
Resolve and validate one replacement plan.
An inline plan is authoritative and bypasses discovery; a pattern of its that covers less than 99% of
its column logs a warning instead of failing.
Auto-discovery runs the heuristic adapter first, then the LLM enhancer
configured by config.llm. When no enhancer is
supplied, the default enhancer runs against a managed local vLLM server
unless NSS_INFERENCE_ENDPOINT selects another service; that server
stops as soon as enhancement ends. Dataframe-aware validation occurs once, after the final plan has
been selected.
Source code in src/nemo_safe_synthesizer/pii_replacer/planning/resolver.py
resolve_replacement_config(df, config, data_config, time_series=None, *, discoverer=None, enhancer=None, mapping_discoverer=None, sampler_value_catalog=None, check_pattern_coverage=True)
¶
Resolve the replacement plan and its data-to-sampler value mapping for df.
The plan comes from config or, for auto_discovery, from the
discoverer and the LLM enhancer. When config.sampler is not set and
the Nemotron-Personas data for config.locale is missing, the sampler
switches to Faker with a warning, unless the plan maps ethnicity
values, which only Nemotron-Personas has. The value
mapping then combines built-in entries for common gender spellings, the
plan's own entries, and, for auto_discovery, discovered entries for any
remaining conditioner values without a sampler match, and is checked
against the sampler.
A plan the user supplied is not discovered, so two mismatches that leave every column replaceable are warnings instead of errors: a pattern covering less than 99% of its column, and a non-categorical dependency column, which is ignored. Value mapping problems fail for every plan: mapping entries the sampler cannot use, and dataset values without a sampler match or entry.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
df
|
DataFrame
|
Data the plan is validated against and whose conditioner values are mapped. |
required |
config
|
ReplacePiiConfig
|
PII replacement configuration to resolve. |
required |
data_config
|
DataParameters
|
Data parameters, used for grouping and protected columns. |
required |
time_series
|
TimeSeriesParameters | None
|
Time-series parameters, used for protected columns. |
None
|
discoverer
|
PlanDiscoverer | None
|
Plan discoverer for |
None
|
enhancer
|
PlanEnhancer | None
|
Plan enhancer; defaults to the LLM enhancer configured by |
None
|
mapping_discoverer
|
DependencyMappingDiscoverer | None
|
Value-mapping discoverer; defaults to the LLM enhancer configured by |
None
|
sampler_value_catalog
|
Mapping[EntityType, tuple[str, ...]] | None
|
Sampler values per entity type; loaded from the configured sampler when omitted. |
None
|
check_pattern_coverage
|
bool
|
Require each pattern to cover at least 99% of |
True
|
Returns:
| Type | Description |
|---|---|
ReplacePiiConfig
|
A copy of |
ReplacePiiConfig
|
including its complete |
ReplacePiiConfig
|
|
ReplacePiiConfig
|
when |
When both plan enhancement and mapping discovery use the default LLM, they share one inference session, so a managed local vLLM server starts once and stops before this returns. Plan validation runs inside that session, between the two LLM steps.
Raises:
| Type | Description |
|---|---|
ParameterError
|
If the plan is invalid; for a discovered plan, if the mapping does not match the sampler, a conditioner value has no sampler match or mapping entry and cannot be discovered, or the plan maps ethnicity values while Nemotron-Personas data is missing; or if the sampler is set to Nemotron-Personas and its dataset is missing. |
Example
With a plan where first_name depends on sex, values "F" and
"Woman" resolve to {"sex": {"F": ["female"], "Woman": ["female"]}}
without an LLM, while a value such as "X" needs a mapping entry.
Source code in src/nemo_safe_synthesizer/pii_replacer/planning/resolver.py
237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 | |
row_counter_columns(df, *, group_column=None)
¶
Return columns whose values number the rows, so automatic discovery does not treat them as PII.
A row counter holds unique, non-missing integers that are exactly 0 to
n - 1 or 1 to n for n rows, in any order. Examples include
the Unnamed: 0 column pandas writes for a saved index, and plain
row_id or event_id sequences. Detection uses the values only, not
the column name. The grouping column is never a row counter: it identifies
the entity each row belongs to.
Example
A column holding 3, 0, 2, 1 in a four-row dataframe is a row
counter; 0, 1, 3, 4 and 17, 18, 19, 20 are not.