Review the PII Replacement Plan Before Training¶
What you'll learn¶
Before training, NeMo Safe Synthesizer replaces personally identifiable information (PII) in your data. An LLM drafts the replacement plan: which columns hold PII, what kind of PII each one holds, and how the new values should be generated. In this notebook, you'll draft that plan without training anything, review it, edit it if needed, and then train with exactly the plan you reviewed.
The example also shows how to keep a column the LLM marks as PII. The simulated hospital wants to compare readmission rates by attending physician, so it keeps the physicians' names instead of replacing them.
The steps are:
- Draft the plan from the data with
plan_pii_replacement(). - Review the saved plan file,
pii_replacement_plan.yaml. - Edit the file to correct the plan or keep a column you need.
- Run the pipeline with the reviewed file and check the PII results in the evaluation report.
Runtime: Running the complete notebook takes about an hour on an NVIDIA A100, most of it fine-tuning. A first run may take longer while model files are downloaded.
The dataset used here is the simulated hospital admissions dataset from the Healthcare Hospital Readmissions tutorial. It was generated with NVIDIA NeMo Data Designer and contains no real patient data.
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
import sys
# The override resolves a flashinfer-python pin conflict between vLLM and NeMo Safe Synthesizer.
!echo "flashinfer-python==0.7.0.post1" | uv pip install --python "{sys.executable}" \
"nemo-safe-synthesizer[engine,cu129]==0.2.0" \
-c https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/v0.2.0/constraints.txt \
--overrides - \
--find-links https://flashinfer.ai/whl/cu129/flashinfer-jit-cache/ \
--find-links https://flashinfer.ai/whl/flashinfer-cubin/ \
--find-links https://wheels.vllm.ai/0.32.0/cu129/vllm/ \
--find-links https://download.pytorch.org/whl/cu129/torch/ \
--find-links https://download.pytorch.org/whl/cu129/torchaudio/ \
--find-links https://download.pytorch.org/whl/cu129/torchvision/ \
--find-links https://download.pytorch.org/whl/cu129/torchcodec/ \
--find-links https://download.pytorch.org/whl/cu129/torchao/ \
--find-links https://download.pytorch.org/whl/cu129/triton/
import html
import numpy as np
import pandas as pd
from faker import Faker
from IPython.display import Markdown, display
2. Load the admissions data¶
Pandas infers quoted numeric CSV fields as integers, so the explicit string dtype below preserves leading zeros in postal codes.
The dataset has no clinician column, so the cell also adds one for this example: each admission gets one of 100 made-up attending physicians, some with more admissions than others.
source_df = pd.read_csv(
"datasets/hospital_readmissions_synthetic_2026_08_18.csv",
dtype={"postal_code": "string"},
)
# Add a made-up attending physician to each admission. The fixed seeds keep the names and assignments the
# same across runs.
fake = Faker("en_US")
fake.seed_instance(318)
physicians = []
while len(physicians) < 100:
name = f"{fake.first_name()} {fake.last_name()}"
if name not in physicians:
physicians.append(name)
rng = np.random.default_rng(318)
source_df.insert(
source_df.columns.get_loc("full_name") + 1,
"attending_physician",
rng.choice(physicians, size=len(source_df), p=rng.dirichlet(np.full(len(physicians), 2.0))),
)
print(f"Loaded {len(source_df):,} admissions with {source_df.shape[1]} fields, including attending_physician.")
display(source_df.head(3))
3. Choose where PII planning runs¶
By default, the planning LLM runs in a temporary vLLM server on this machine's GPU, so no API key is needed and the data stays on this machine. The local model needs an 80 GB GPU and downloads about 66 GB the first time it runs.
To use a hosted service instead, such as the NVIDIA API at https://integrate.api.nvidia.com/v1, set NSS_INFERENCE_ENDPOINT, NSS_INFERENCE_MODEL, and NSS_INFERENCE_KEY in the next cell. You can obtain an API key from build.nvidia.com. Column samples are then sent to that service. See Where planning requests go for details.
import os
# Keep the data split and generated replacements reproducible across tutorial runs.
SPLIT_SEED = 318
# Optional: plan with a hosted service instead of a local vLLM server.
# import getpass
# os.environ["NSS_INFERENCE_ENDPOINT"] = "https://integrate.api.nvidia.com/v1"
# os.environ["NSS_INFERENCE_MODEL"] = "nvidia/nemotron-3-ultra-550b-a55b"
# os.environ["NSS_INFERENCE_KEY"] = getpass.getpass("Paste inference API key: ")
if os.environ.get("NSS_INFERENCE_ENDPOINT"):
print(f"PII planning sends requests to {os.environ['NSS_INFERENCE_ENDPOINT']}")
else:
print("PII planning runs a local vLLM server on this machine's GPU")
4. Draft the plan (10 minutes)¶
plan_pii_replacement() asks the planning LLM which columns contain PII and how to replace them. Nothing is replaced or trained yet. With output_path, it saves the complete configuration and, beside it, the part to review: pii_replacement_plan.yaml. Run this cell once; the next cell shows the file.
from nemo_safe_synthesizer.sdk.library_builder import SafeSynthesizer
ARTIFACT_ROOT = "safe-synthesizer-artifacts/pii-replacement-review"
builder = (
SafeSynthesizer(save_path=ARTIFACT_ROOT)
.with_data_source(source_df)
.with_replace_pii(seed=SPLIT_SEED)
.with_data(random_state=SPLIT_SEED)
.with_generate(num_records=5_000)
)
RUN_DIR = builder._workdir.run_dir
builder.plan_pii_replacement(output_path=RUN_DIR / "safe-synthesizer-config.yaml")
PLAN_PATH = RUN_DIR / "pii_replacement_plan.yaml"
print(f"Draft plan saved to {PLAN_PATH}")
# Show the plan file. Rerun this cell after editing the file; it does not draft the plan again.
# A Markdown code block takes the notebook's own colors, so it stays readable in dark themes.
display(Markdown(f"```yaml\n{PLAN_PATH.read_text().rstrip()}\n```"))
5. Review the plan¶
The plan is a draft from an LLM, so check it against what you know about the data. The file has two sections, each with a short comment above it:
columns_to_replacelists the columns whose values are replaced. Every column not listed is kept unchanged.data_to_sampler_value_mappingtranslates values of the columns that guide a replacement, such assex, to values the sampler understands. Safe Synthesizer fills it in.
The header names the sampler and locale the plan was written for. Those are set in the configuration as replace_pii.sampler and replace_pii.locale, not in this file.
Check the plan:
- Nothing sensitive is kept. Every identifier, name, contact detail, street address, and date of birth should be in
columns_to_replace. A sensitive column left out reaches the model as is. - Nothing is replaced that you need to keep. Clinical fields such as diagnosis, labs, and charges should not be in the plan. Neither should a column you decide to keep, such as
attending_physicianin this example. - Each
entity_typeis right. It decides what kind of value is generated, for examplefull_nameorunique_identifier. - Each
patternkeeps the format you need. An optionalpatternsets the format of the new values. Without one, an identifier gets random letters and digits in the original's layout, so a fixed prefix such asMRN-is not kept. - The
depends_onlinks make sense. They list the columns a replacement follows, for example an email built from the replaced name, or a name chosen to matchsex. A missing link means those values are replaced independently, so they may no longer match. - Free text is scanned. Written notes such as
discharge_summaryshould be listed withentity_type: free_text, so names and other PII inside them are found and replaced.
Some kinds of values are never replaced as whole columns: cities, states, ZIP codes, countries, organizations, genders, ethnicities, and ordinary dates such as admission dates. They stay out of the plan by design, and the plan may use them to guide other replacements.
6. Edit the plan¶
To change the plan, edit pii_replacement_plan.yaml at the path the draft cell printed, then rerun the display cell above to see the result.
Remove attending_physician from the plan. This step is required in this example. The LLM most likely lists attending_physician as a name to replace, because it holds people's names. To keep the original names for analytics by physician, delete the whole entry. Your draft may differ: the entry may say entity_type: free_text instead, or have no depends_on lines. It often looks like this, with depends_on lines that link the physician's name to the patient's sex and ethnicity:
- column_name: attending_physician
entity_type: full_name
depends_on:
- column_name: sex
entity_type: gender
- column_name: race_ethnicity
entity_type: ethnic_background
A kept column reaches the model unchanged, so its values can appear in the synthetic data. Keep a column of names only when your data-sharing rules allow those names to be shared. If the plan does not list attending_physician, there is nothing to delete.
Other edits you may need:
Columns: add, remove, or correct entries in
columns_to_replace. For example, to keep theMRN-prefix of medical record numbers such asMRN-4C806C7840, give themrnentry a pattern.&stands for a digit or an uppercase letter, and#for a digit:- column_name: mrn entity_type: unique_identifier pattern: MRN-&&&&&&&&&&
Value mapping: in
data_to_sampler_value_mapping, map each value as it appears in your data to one or more values the sampler accepts. Gender usesfemaleandmalefor every sampler. Matching ignores case, and a value mapped to several sampler values can draw from any of them. For example:data_to_sampler_value_mapping: sex: W: [female] Unknown: [female, male]
When the plan is right, run the next cell. It loads and checks the file, and stops if attending_physician is still listed. A sampler value with a typo stops with a message naming it. A value in a guiding column that matches no sampler value and has no entry also stops, with a message giving the column and how many values are missing.
# Use the reviewed file. Its plan is no longer a draft, so the planning LLM does not run again.
builder = builder.with_replace_pii(replacement_plan=str(PLAN_PATH), seed=SPLIT_SEED)
reviewed = builder.plan_pii_replacement().inline_plan
if any(column.column_name == "attending_physician" for column in reviewed.columns_to_replace):
raise ValueError(
f"attending_physician is still in the plan. Delete its entry from {PLAN_PATH}, save the file, "
"and rerun this cell."
)
print(f"Using the reviewed plan: {len(reviewed.columns_to_replace)} columns will be replaced.")
print("attending_physician is kept unchanged.")
7. Train, generate, and evaluate (1 hour)¶
The next cell runs the complete pipeline with the reviewed plan. It sets aside 499 records for evaluation, replaces PII in the remaining 9,498 records before fine-tuning the default SmolLM3 model, generates 5,000 synthetic records, and evaluates the result. The outputs are saved under ARTIFACT_ROOT.
builder.run()
results = builder.results
print(f"Generated {len(results.synthetic_data):,} synthetic admissions.")
8. See what replacement changed¶
The run saved the training records as they were before and after PII replacement. The next cell shows three of them, picked at random with the tutorial's seed, with each replaced column's original and new value. attending_physician is included to show a column the plan keeps. In discharge_summary, only the PII found in the text is replaced; the rest of the text is unchanged.
# Both files hold the same training records in the same order. Reading every cell as text shows values
# as written, such as a postal code's leading zero.
before = pd.read_csv(builder._workdir.dataset.training, dtype=str, keep_default_na=False)
after = pd.read_csv(builder._workdir.dataset.transformed_training, dtype=str, keep_default_na=False)
shown_columns = [column.column_name for column in reviewed.columns_to_replace] + ["attending_physician"]
for number, row in enumerate(before.sample(n=3, random_state=SPLIT_SEED).index, start=1):
display(Markdown(f"**Record {number} of 3**"))
record = pd.DataFrame({"Before": before.loc[row, shown_columns], "After": after.loc[row, shown_columns]})
styled = record.style.set_properties(**{"text-align": "left", "white-space": "pre-wrap"})
styled = styled.set_table_styles(
[
{"selector": "th.col_heading", "props": [("text-align", "center")]},
# Space below each table, so the next record's label sits closer to its own table.
{"selector": "", "props": [("margin-bottom", "2em")]},
]
)
display(styled)
9. Check the PII results in the evaluation report¶
Open the Data Privacy page of the report below. Its PII Replacement and Replay table lists each replaced column, how its values were replaced, how much PII was found in the training data, and how many original values reappear in the synthetic data (PII Replay). Free-text columns list each kind of PII found in them. These results support review; they do not certify compliance or approve the data for sharing.
report_html = results.evaluation_report_html
if report_html:
# srcdoc, not a data: URL: Chrome blanks data: URLs over 2 MB, and the base keeps the report's #section links in the frame.
report_doc = report_html.replace("<head>", '<head><base href="about:srcdoc">', 1)
frame = (
f'<iframe srcdoc="{html.escape(report_doc)}" sandbox="allow-scripts allow-popups" '
'width="100%" height="850"></iframe>'
)
# Raw display: HTML() warns about a bare <iframe>, and IFrame() cannot take srcdoc.
display({"text/html": frame}, raw=True)
else:
display(Markdown("The run did not return an HTML evaluation report."))