Skip to content

plan_builder

plan_builder

Build PII replacement plans from semantic column classifications.

Classes:

Name Description
ColumnClassification

Semantic classification produced by a heuristic or LLM planner.

DependencyCandidate

One proposed dependency edge identified only by dataframe columns.

Functions:

Name Description
plan_from_classifications

Build replacement membership from one classification per expected column.

derive_dependency_candidates

Return the individually permitted edges for a later selection pass.

apply_dependencies

Validate and apply selected dependency edges using classified entity types.

ColumnClassification pydantic-model

Bases: BaseModel

Semantic classification produced by a heuristic or LLM planner.

Config:

  • extra: forbid
  • frozen: True

Fields:

  • column_name (str)
  • entity_type (EntityType | None)
  • pattern (str | None)

Validators:

  • _validate_pattern_eligibility

DependencyCandidate(target_column, source_column) dataclass

One proposed dependency edge identified only by dataframe columns.

Entity types deliberately remain in ColumnClassification as the single source of truth. apply_dependencies validates this edge against those classifications and the target plan before constructing the final plan.

plan_from_classifications(classifications, *, expected_columns, protected_columns=frozenset())

Build replacement membership from one classification per expected column.

A classification with entity_type=None records that the column was examined but does not contain a supported entity. Protected columns must still be classified, but are omitted from the replacement plan.

Source code in src/nemo_safe_synthesizer/pii_replacer/planning/plan_builder.py
def plan_from_classifications(
    classifications: Sequence[ColumnClassification],
    *,
    expected_columns: Set[str],
    protected_columns: Set[str] = frozenset(),
) -> PiiReplacementPlan:
    """Build replacement membership from one classification per expected column.

    A classification with ``entity_type=None`` records that the column was
    examined but does not contain a supported entity. Protected columns must
    still be classified, but are omitted from the replacement plan.
    """
    _classifications_by_column(classifications, expected_columns=expected_columns)
    columns_to_replace: list[PiiColumnPlan] = []
    for classification in classifications:
        entity_type = classification.entity_type
        if (
            entity_type is None
            or not is_columns_to_replace_type(entity_type)
            or classification.column_name in protected_columns
        ):
            continue
        columns_to_replace.append(
            PiiColumnPlan(
                column_name=classification.column_name,
                entity_type=entity_type,
                pattern=classification.pattern,
            )
        )
    return PiiReplacementPlan(columns_to_replace=columns_to_replace)

derive_dependency_candidates(classifications, *, expected_columns, protected_columns=frozenset())

Return the individually permitted edges for a later selection pass.

The classifications determine the replacement nodes, including protected column exclusion. This function constructs that node-only plan internally so callers cannot supply a plan that disagrees with the classifications. It intentionally does not filter mutually exclusive candidate groups; exclusivity applies to the set selected in the later dependency pass.

Source code in src/nemo_safe_synthesizer/pii_replacer/planning/plan_builder.py
def derive_dependency_candidates(
    classifications: Sequence[ColumnClassification],
    *,
    expected_columns: Set[str],
    protected_columns: Set[str] = frozenset(),
) -> list[DependencyCandidate]:
    """Return the individually permitted edges for a later selection pass.

    The classifications determine the replacement nodes, including protected
    column exclusion. This function constructs that node-only plan internally
    so callers cannot supply a plan that disagrees with the classifications.
    It intentionally does not filter mutually exclusive candidate groups;
    exclusivity applies to the set selected in the later dependency pass.
    """
    plan = plan_from_classifications(
        classifications,
        expected_columns=expected_columns,
        protected_columns=protected_columns,
    )
    candidates: list[DependencyCandidate] = []
    for target in plan.columns_to_replace:
        allowed_sources = ALLOWED_DEPENDS_ON.get(target.entity_type, frozenset())
        for source in classifications:
            if (
                source.entity_type is None
                or source.entity_type not in allowed_sources
                or source.column_name == target.column_name
            ):
                continue
            candidates.append(
                DependencyCandidate(
                    target_column=target.column_name,
                    source_column=source.column_name,
                )
            )
    return candidates

apply_dependencies(plan, dependencies, *, classifications)

Validate and apply selected dependency edges using classified entity types.

Source code in src/nemo_safe_synthesizer/pii_replacer/planning/plan_builder.py
def apply_dependencies(
    plan: PiiReplacementPlan,
    dependencies: Sequence[DependencyCandidate],
    *,
    classifications: Sequence[ColumnClassification],
) -> PiiReplacementPlan:
    """Validate and apply selected dependency edges using classified entity types."""
    dependencies_by_target: dict[str, list[ConditioningColumn]] = {}
    classifications_by_column = _classifications_by_column(classifications)
    targets = _validate_plan_classifications(plan, classifications_by_column)
    for dependency in dependencies:
        target = targets.get(dependency.target_column)
        if target is None:
            raise ParameterError(f"dependency targets unknown replacement column {dependency.target_column!r}")
        source = classifications_by_column.get(dependency.source_column)
        if source is None:
            raise ParameterError(f"dependency sources unknown classified column {dependency.source_column!r}")
        if source.entity_type is None:
            raise ParameterError(
                f"dependency source {dependency.source_column!r} is not classified as one of the supported entities"
            )
        validate_dependency_relationship(
            target.entity_type,
            source.entity_type,
            target_column=target.column_name,
        )
        conditioner = ConditioningColumn(column_name=source.column_name, entity_type=source.entity_type)
        dependencies_by_target.setdefault(dependency.target_column, []).append(conditioner)

    return PiiReplacementPlan(
        columns_to_replace=[
            PiiColumnPlan(
                column_name=spec.column_name,
                entity_type=spec.entity_type,
                pattern=spec.pattern,
                depends_on=dependencies_by_target.get(spec.column_name, []),
            )
            for spec in plan.columns_to_replace
        ],
        data_to_sampler_value_mapping=plan.data_to_sampler_value_mapping,
    )