transform_result
transform_result
¶
Classes:
| Name | Description |
|---|---|
StructuredReplacementRecord |
One structured replacement occurrence captured for explicit evaluation use. |
FreeTextReplacementRecord |
One accepted free-text span and its applied replacement. |
ReplacementMap |
Sensitive, opt-in replacement provenance for evaluation and auditing. |
ColumnStatistics |
Metadata and statistics for transformations and detected entities in a column. |
ReplacementGenerationStatistics |
Aggregate statistics for the synthetic replacement generation phase. |
TransformResult |
Result of PII replacement: transformed data and per-column statistics. |
StructuredReplacementRecord
pydantic-model
¶
Bases: BaseModel
One structured replacement occurrence captured for explicit evaluation use.
The original and replacement values can contain sensitive data. They are
excluded from repr but remain available to callers and serialization.
Config:
frozen:True
Fields:
-
row_position(int) -
column_name(str) -
entity_type(EntityType) -
scope(MappingScope) -
original_value(str) -
replacement_value(str)
row_position
pydantic-field
¶
Zero-based position of the replaced dataframe row.
column_name
pydantic-field
¶
Name of the structured column that was replaced.
entity_type
pydantic-field
¶
Normalized entity type used to generate the replacement.
scope
pydantic-field
¶
Mapping scope used for replacement reuse.
original_value
pydantic-field
¶
Canonical original value. May contain sensitive data.
replacement_value
pydantic-field
¶
Generated replacement value.
FreeTextReplacementRecord
pydantic-model
¶
Bases: BaseModel
One accepted free-text span and its applied replacement.
Offsets are half-open and refer to the complete original cell. The original
and replacement values can contain sensitive data. They are excluded from
repr but remain available to callers and serialization.
Config:
frozen:True
Fields:
-
row_position(int) -
column_name(str) -
start(int) -
end(int) -
entity_type(EntityType) -
detection_source(DetectionSource) -
score(float | None) -
scope(MappingScope) -
original_value(str) -
replacement_value(str)
Validators:
-
_require_nonempty_span
row_position
pydantic-field
¶
Zero-based position of the replaced dataframe row.
column_name
pydantic-field
¶
Name of the free-text column containing the accepted span.
start
pydantic-field
¶
Inclusive start offset in the original cell.
end
pydantic-field
¶
Exclusive end offset in the original cell. Must be greater than start.
entity_type
pydantic-field
¶
Normalized entity type assigned to the accepted span.
detection_source
pydantic-field
¶
Detector that produced the accepted span, or, for structured_value and detected_value, the known value whose occurrence was found by searching the text.
score = None
pydantic-field
¶
Detector confidence in [0, 1] when the detector supplies one.
scope
pydantic-field
¶
Mapping scope used for replacement reuse.
original_value
pydantic-field
¶
Exact text covered by the span. May contain sensitive data.
replacement_value
pydantic-field
¶
Replacement inserted for the accepted span.
ReplacementMap
pydantic-model
¶
Bases: BaseModel
Sensitive, opt-in replacement provenance for evaluation and auditing.
Structured records identify each replaced cell. Free-text records are the exact accepted-span trace, including original offsets and detector provenance. Serializing this model persists original PII, so normal replacement calls do not create it unless explicitly requested.
Config:
frozen:True
Fields:
-
structured(tuple[StructuredReplacementRecord, ...]) -
free_text(tuple[FreeTextReplacementRecord, ...])
ColumnStatistics
pydantic-model
¶
Bases: BaseModel
Metadata and statistics for transformations and detected entities in a column.
Tracks assigned type and entity, detected entity counts and values, and which transform functions were applied.
Fields:
-
assigned_type(str | None) -
assigned_entity(str | None) -
detected_entity_counts(dict[str, int]) -
detected_entity_values(dict[str, set]) -
is_transformed(bool) -
transform_functions(set[str]) -
dependency_drift_count(int) -
repeated_replacement_count(int) -
kept_name_part_count(int)
assigned_type
pydantic-field
¶
Type assigned to the column.
assigned_entity
pydantic-field
¶
Entity assigned to the column.
detected_entity_counts
pydantic-field
¶
Entity name to count of times it was detected in the column.
detected_entity_values
pydantic-field
¶
Entity name to set of detected values. These are original PII values, kept in memory for the PII replay metric and excluded from serialization and repr so they cannot be written out.
is_transformed = False
pydantic-field
¶
Whether the column was transformed.
transform_functions
pydantic-field
¶
Names of transform functions applied to the column.
dependency_drift_count = 0
pydantic-field
¶
Number of later rows in a group that reused the group's first replacement although a column it depends on had a different value in that row.
repeated_replacement_count = 0
pydantic-field
¶
Number of replacements that repeat an earlier one in a column whose original values are all distinct, because no unused value was found.
kept_name_part_count = 0
pydantic-field
¶
Number of full-name replacements that keep the original's first or last name.
ReplacementGenerationStatistics
pydantic-model
¶
Bases: BaseModel
Aggregate statistics for the synthetic replacement generation phase.
Fields:
-
generated_replacement_count(int) -
generator_time_seconds(float) -
dependency_drift_count(int)
generated_replacement_count
pydantic-field
¶
Number of distinct replacement values generated after cache reuse.
generator_time_seconds
pydantic-field
¶
Wall-clock time spent inside replacement generator calls, in seconds. Excludes plan resolution, free-text detection, and writing replacements back.
dependency_drift_count = 0
pydantic-field
¶
Number of later group occurrences that reused a replacement although their dependency values differed from the group's first occurrence.
TransformResult
pydantic-model
¶
Bases: BaseModel
Result of PII replacement: transformed data and per-column statistics.
Shared result shape consumed by evaluation after a replacement run. The
result keeps its own deep copy of resolved_config, and
replacement_plan is read from that copy, so later changes to the
caller's configuration cannot make the result inconsistent.
Config:
arbitrary_types_allowed:Trueextra:forbid
Fields:
-
transformed_df(DataFrame) -
column_statistics(dict[str, ColumnStatistics]) -
resolved_config(ReplacePiiConfig) -
generation_statistics(ReplacementGenerationStatistics) -
replacement_time_seconds(float) -
replacement_map(ReplacementMap | None)
Validators:
-
_own_a_resolved_config_snapshot→resolved_config
transformed_df
pydantic-field
¶
DataFrame with PII replaced according to config.
column_statistics
pydantic-field
¶
Column name to ColumnStatistics for that column.
resolved_config
pydantic-field
¶
Resolved PII configuration containing the executed plan and its dependency mappings. Stored as a deep copy of the value passed in.
generation_statistics
pydantic-field
¶
Aggregate timing and count statistics for replacement generation.
replacement_time_seconds
pydantic-field
¶
Wall-clock time for this PII replacement call, in seconds, including plan resolution, free-text detection, generation, and statistics.
replacement_map = None
pydantic-field
¶
Sensitive replacement provenance, present only when explicitly requested.
replacement_plan
property
¶
Resolved replacement plan executed for this result, read from resolved_config.
DetectionResult
pydantic-model
¶
Bases: BaseModel
Result of PII detection without replacement: per-column statistics for the unchanged data.
The statistics are those TransformResult would report for the same data and plan, so PII replay
can use them when replacement is off. Like TransformResult, the result keeps its own deep copy of
resolved_config.
Config:
extra:forbid
Fields:
-
column_statistics(dict[str, ColumnStatistics]) -
resolved_config(ReplacePiiConfig) -
detection_time_seconds(float)
Validators:
-
_own_a_resolved_config_snapshot→resolved_config
column_statistics
pydantic-field
¶
Column name to ColumnStatistics for that column; no column is marked transformed.
resolved_config
pydantic-field
¶
Resolved PII configuration containing the plan used for detection. Stored as a deep copy.
detection_time_seconds
pydantic-field
¶
Wall-clock time for this detection call, in seconds, including plan resolution.