Skip to content

llm

llm

OpenAI-compatible LLM discovery for PII plans and sampler mappings.

Classes:

Name Description
LLMPlanEnhancer

Discover plans and sampler mappings through bounded structured requests.

DependencyOptions = dict[str, dict[EntityType, list[str]]] module-attribute

Target column -> source entity type -> permitted source columns, in candidate order.

LLMPlanEnhancer(config, *, settings=None, transport=None, sleep=time.sleep)

Bases: PlanEnhancer

Discover plans and sampler mappings through bounded structured requests.

Pass one classifies every column's entity type and optional pattern. NSS then derives replacement membership and all permitted dependency candidates deterministically, and pass two only selects useful candidate IDs. Invalid optional patterns get focused repair requests. A separate request maps dependency values to sampler values on demand.

Parameters:

Name Type Description Default
config LLMConfig

Persisted LLM behavior.

required
settings InferenceSettings | None

Endpoint, model, key, and request settings; defaults to resolve_inference_settings(config), which reads an explicit endpoint from the environment.

None
transport LLMTransport | None

Structured-response transport; defaults to an OpenAICompatibleTransport for settings.

None
sleep Callable[[float], None]

Function used to wait between transient retries.

sleep

Attributes:

Name Type Description
settings

Resolved inference settings.

Raises:

Type Description
ParameterError

If the inference settings are invalid.

Methods:

Name Description
enhance

Return a semantically classified, deterministically assembled plan.

discover_data_to_sampler_value_mapping

Map conditioner-column values without a sampler match to values from one sampler catalog.

Source code in src/nemo_safe_synthesizer/pii_replacer/planning/llm.py
def __init__(
    self,
    config: LLMConfig,
    *,
    settings: InferenceSettings | None = None,
    transport: LLMTransport | None = None,
    sleep: Callable[[float], None] = time.sleep,
) -> None:
    self.settings = resolve_inference_settings(config) if settings is None else settings
    self._transport = transport or OpenAICompatibleTransport(self.settings)
    self._sleep = sleep

enhance(discovery_input, baseline)

Return a semantically classified, deterministically assembled plan.

baseline is not sent to the model. The heuristic discoverer returns an empty plan, and a hint that always says nothing reads as a negative signal, so prompts carry no heuristic classifications or dependency choices.

Source code in src/nemo_safe_synthesizer/pii_replacer/planning/llm.py
def enhance(
    self,
    discovery_input: PlanDiscoveryInput,
    baseline: PiiReplacementPlan,
) -> PiiReplacementPlan:
    """Return a semantically classified, deterministically assembled plan.

    ``baseline`` is not sent to the model. The heuristic discoverer returns an empty plan, and a hint that always
    says nothing reads as a negative signal, so prompts carry no heuristic classifications or dependency choices.
    """
    classifications = self._classify_columns(discovery_input)
    expected_columns = {profile.column_name for profile in discovery_input.column_profiles}
    plan = plan_from_classifications(
        classifications,
        expected_columns=expected_columns,
        protected_columns=discovery_input.protected_columns,
    )
    # Repair first so dependency selection sees each target's final pattern.
    plan = self._repair_invalid_patterns(discovery_input, plan)
    candidates = derive_dependency_candidates(
        classifications,
        expected_columns=expected_columns,
        protected_columns=discovery_input.protected_columns,
    )
    if candidates:
        plan = self._select_dependencies(plan, candidates, classifications, discovery_input.dataframe)
    return plan

discover_data_to_sampler_value_mapping(dataframe, plan, catalog)

Map conditioner-column values without a sampler match to values from one sampler catalog.

Parameters:

Name Type Description Default
dataframe DataFrame

Data whose conditioner-column values need sampler values.

required
plan PiiReplacementPlan

Replacement plan naming the conditioner columns.

required
catalog SamplerValueCatalog

Sampler values available for each conditioner entity type.

required

Returns:

Type Description
DataToSamplerValueMapping

Per-column mappings from each dataset value that has no

DataToSamplerValueMapping

case-insensitive sampler match to one or more sampler values. A

DataToSamplerValueMapping

value that fits no narrower set maps to every supplied value, so

DataToSamplerValueMapping

sampling is not narrowed. Returns an empty dict when every value

DataToSamplerValueMapping

already matches.

DataToSamplerValueMapping

For example, with the catalog

DataToSamplerValueMapping

{ETHNIC_BACKGROUND: ("east asian", "south asian", "white")} and

DataToSamplerValueMapping

a race column holding "Asian" and "White", the result is

DataToSamplerValueMapping

{"race": {"Asian": ["east asian", "south asian"]}}. "White"

DataToSamplerValueMapping

is omitted because it already matches.

Raises:

Type Description
ParameterError

If the mapping request exceeds its size bounds.

Source code in src/nemo_safe_synthesizer/pii_replacer/planning/llm.py
def discover_data_to_sampler_value_mapping(
    self,
    dataframe: pd.DataFrame,
    plan: PiiReplacementPlan,
    catalog: SamplerValueCatalog,
) -> DataToSamplerValueMapping:
    """Map conditioner-column values without a sampler match to values from one sampler catalog.

    Args:
        dataframe: Data whose conditioner-column values need sampler values.
        plan: Replacement plan naming the conditioner columns.
        catalog: Sampler values available for each conditioner entity type.

    Returns:
        Per-column mappings from each dataset value that has no
        case-insensitive sampler match to one or more sampler values. A
        value that fits no narrower set maps to every supplied value, so
        sampling is not narrowed. Returns an empty dict when every value
        already matches.

        For example, with the catalog
        ``{ETHNIC_BACKGROUND: ("east asian", "south asian", "white")}`` and
        a ``race`` column holding ``"Asian"`` and ``"White"``, the result is
        ``{"race": {"Asian": ["east asian", "south asian"]}}``. ``"White"``
        is omitted because it already matches.

    Raises:
        ParameterError: If the mapping request exceeds its size bounds.
    """
    inputs = mapping_inputs(dataframe, plan, catalog)
    if not inputs:
        return {}
    source_value_count = sum(len(item.source_values) for item in inputs)
    messages = _dependency_mapping_messages(inputs)
    if source_value_count > MAX_MAPPING_SOURCE_VALUES or _json_bytes(messages) > MAX_MAPPING_REQUEST_BYTES:
        raise ParameterError(
            "automatic dependency mapping exceeds its bounded request size; provide manual mappings instead"
        )

    expected: dict[tuple[str, str], tuple[str, DependencyMappingInput]] = {}
    for item in inputs:
        for source_value in item.source_values:
            expected[(item.column_name, source_value.casefold())] = (source_value, item)

    def parse(response: _LLMValueMappingResponse) -> DataToSamplerValueMapping:
        columns = _submitted_names(
            {item.column_name for item in inputs}, [item.column_name for item in response.mappings]
        )
        actual = [(column, item.source_value.casefold()) for column, item in zip(columns, response.mappings)]
        if issue := _mapping_coverage_issue(list(expected), actual):
            raise _RejectedResponseError(issue)
        result: DataToSamplerValueMapping = {}
        for (column, _), item in zip(actual, response.mappings):
            source_value, mapping_input = expected[(column, item.source_value.casefold())]
            result.setdefault(column, {})[source_value] = _resolved_sampler_values(
                item.sampler_values, mapping_input.sampler_values
            )
        return result

    return self._request_structured(
        purpose="PII data-to-sampler value mapping",
        messages=messages,
        response_model=_LLMValueMappingResponse,
        parse=parse,
    )