🕵️ Your First Anonymization¶

Detect sensitive entities and replace them with LLM-generated substitutes -- the simplest end-to-end example of Anonymizer.

📚 What you'll learn¶

• Load a CSV dataset and configure Anonymizer in a few lines
• Preview anonymized results on a small sample before committing to a full run
• Inspect entity detection and replacement with display_record()
• Process the full dataset with run()

Tip: First time running notebooks? Start with setup instructions.

⚙️ Setup¶

• Check if your NVIDIA_API_KEY from build.nvidia.com is registered for model access.
  • The default build.nvidia.com (NVIDIA Build) setup is a convenient way to try Anonymizer and iterate on previews. Use of NVIDIA Build is subject to NVIDIA Build's own terms of service and privacy practices, which are separate from and independent of the NeMo Framework library. NVIDIA Build is intended for evaluation and testing purposes only and may not be used in production environments. Do not upload any confidential information or personal data when using NVIDIA Build. Your use of NVIDIA Build is logged for security purposes and to improve NVIDIA products and services.
  • Request and token rate limits on build.nvidia.com vary by account and model access, and lower-volume development access can be slow for full-dataset runs. Start with preview() on a small sample, then move to your own endpoint for production data and usage.
• Import the core Anonymizer classes: Anonymizer, AnonymizerConfig, AnonymizerInput, and Substitute.
• Anonymizer() initializes with the default model provider -- no extra config needed.
• configure_logging(LoggingConfig.default()) keeps logs at INFO. Switch to LoggingConfig.debug() when troubleshooting.

In [2]:

import getpass
import os

if not os.getenv("NVIDIA_API_KEY"):
    key = getpass.getpass("Enter NVIDIA_API_KEY from build.nvidia.com: ").strip()
    if not key:
        raise RuntimeError("NVIDIA_API_KEY is required to run these notebooks.")
    os.environ["NVIDIA_API_KEY"] = key

import getpass import os if not os.getenv("NVIDIA_API_KEY"): key = getpass.getpass("Enter NVIDIA_API_KEY from build.nvidia.com: ").strip() if not key: raise RuntimeError("NVIDIA_API_KEY is required to run these notebooks.") os.environ["NVIDIA_API_KEY"] = key

In [3]:

from anonymizer import Anonymizer, AnonymizerConfig, AnonymizerInput, LoggingConfig, Substitute, configure_logging

configure_logging(LoggingConfig.default())

from anonymizer import Anonymizer, AnonymizerConfig, AnonymizerInput, LoggingConfig, Substitute, configure_logging configure_logging(LoggingConfig.default())

In [4]:

anonymizer = Anonymizer()

anonymizer = Anonymizer()

[10:59:16] [INFO] 🔧 Anonymizer initialized with 3 model configs

[10:59:16] [INFO]   |-- 🔎 detector:  gliner-pii-detector

[10:59:16] [INFO]   |-- ✅ validator: gpt-oss-120b

[10:59:16] [INFO]   |-- 🧩 augmenter: gpt-oss-120b

📦 Load data and configure¶

• AnonymizerInput points to your CSV and names the text column. data_summary gives the LLM context about the kind of text it will process.
• Records up to 2,000 tokens each work with the default model configs.
• AnonymizerConfig with Substitute() tells Anonymizer to replace detected entities with LLM-generated synthetic values for names, cities, dates, etc.

In [5]:

input_data = AnonymizerInput(
    source="https://raw.githubusercontent.com/NVIDIA-NeMo/Anonymizer/refs/heads/main/docs/data/NVIDIA_synthetic_biographies.csv",
    text_column="biography",
    data_summary="Biographical profiles of individuals",
)

config = AnonymizerConfig(replace=Substitute())

input_data = AnonymizerInput( source="https://raw.githubusercontent.com/NVIDIA-NeMo/Anonymizer/refs/heads/main/docs/data/NVIDIA_synthetic_biographies.csv", text_column="biography", data_summary="Biographical profiles of individuals", ) config = AnonymizerConfig(replace=Substitute())

👁️ Preview¶

• preview() runs on a small sample so you can iterate quickly.
• Always preview before processing the full dataset -- it's the fastest way to catch prompt or config issues early.

In [6]:

preview = anonymizer.preview(config=config, data=input_data, num_records=3)

preview = anonymizer.preview(config=config, data=input_data, num_records=3)

[10:59:17] [INFO] 👀 Preview mode: 📂 Loaded 3 records from https://raw.githubusercontent.com/NVIDIA-NeMo/Anonymizer/refs/heads/main/docs/data/NVIDIA_synthetic_biographies.csv (column: 'biography')

[10:59:17] [INFO] 🔍 Running entity detection on 3 records

[10:59:17] [INFO] detection labels in scope: (default: 65 labels; see anonymizer.DEFAULT_ENTITY_LABELS for list)

[11:00:13] [INFO]   |-- 📋 Detection complete — 77 entities found across 3 records (0 failed) [56.4s]

[11:00:13] [INFO]   |-- labels: first_name=22, organization_name=7, age=5, occupation=5, city=4, state=4, degree=4, university=4, field_of_study=4, political_view=4, last_name=3, race_ethnicity=3, language=2, street_address=2, place_name=1, date_of_birth=1, employment_status=1, religious_belief=1

[11:00:13] [INFO] 🔄 Running Substitute replacement

[11:00:54] [INFO]   |-- 📋 Replacement complete (0 failed) [40.9s]

[11:00:54] [INFO] 🎉 Pipeline complete — 3 records processed, 0 total failures

🔍 Inspect¶

• display_record() shows the original text with highlighted entities, the replacement map, and the anonymized output -- all in one view.
• The result dataframe has original and substituted text side-by-side.

In [7]:

preview.display_record(0)

preview.display_record(0)

Anonymizer Preview (record 0)

Original

Bobby| first_name Watford| last_name, a 40| age‑year‑old Mexican| race_ethnicity veterinarian| occupation living in Denver| city, Colorado| state, grew up on the outskirts of the city and developed a love for animals early on. After graduating from Jefferson High| organization_name, he earned his DVM| degree at the University of Colorado Boulder| university, where he also completed a research stint in wildlife health| field_of_study. Fluent in English| language, Bobby| first_name has always described his upbringing as a blend of small‑town curiosity and the vibrant culture of his community, values that continue to shape his compassionate approach to animal care. Since finishing his training, Bobby| first_name has worked at VCA Animal Hospital| organization_name and later at the Colorado Veterinary Clinic| organization_name, where he now leads a busy mixed‑practice team. He identifies as a Christian Democrat| political_view and often volunteers at local shelters, a habit encouraged by his wife, Maya| first_name, and their two teenage children, Aria and Leo| first_name. Outside the clinic, Bobby| first_name enjoys hiking the Rockies| place_name with his family and mentoring veterinary students from his alma mater.

Replaced

Ethan| first_name Kline| last_name, a 45| age‑year‑old Filipino| race_ethnicity zoological researcher| occupation living in Portland| city, Oregon| state, grew up on the outskirts of the city and developed a love for animals early on. After graduating from Lincoln High| organization_name, he earned his Master of Veterinary Science| degree at the Oregon State University| university, where he also completed a research stint in conservation genetics| field_of_study. Fluent in Spanish| language, Ethan| first_name has always described his upbringing as a blend of small‑town curiosity and the vibrant culture of his community, values that continue to shape his compassionate approach to animal care. Since finishing his training, Ethan| first_name has worked at Pacific Veterinary Group| organization_name and later at the Oregon Animal Care Center| organization_name, where he now leads a busy mixed‑practice team. He identifies as a Green Party| political_view and often volunteers at local shelters, a habit encouraged by his wife, Leah| first_name, and their two teenage children, Sofia and Mateo| first_name. Outside the clinic, Ethan| first_name enjoys hiking the Cascade Range| place_name with his family and mentoring veterinary students from his alma mater.

Replacement Map

Original	Label	Replacement
40	age	45
Aria and Leo	first_name	Sofia and Mateo
Bobby	first_name	Ethan
Christian Democrat	political_view	Green Party
Colorado	state	Oregon
Colorado Veterinary Clinic	organization_name	Oregon Animal Care Center
DVM	degree	Master of Veterinary Science
Denver	city	Portland
English	language	Spanish
Jefferson High	organization_name	Lincoln High
Maya	first_name	Leah
Mexican	race_ethnicity	Filipino
Rockies	place_name	Cascade Range
University of Colorado Boulder	university	Oregon State University
VCA Animal Hospital	organization_name	Pacific Veterinary Group
Watford	last_name	Kline
veterinarian	occupation	zoological researcher
wildlife health	field_of_study	conservation genetics

In [8]:

preview.display_record(1)

preview.display_record(1)

Anonymizer Preview (record 1)

Original

Idilio| first_name Bell| last_name is a 37| age‑year‑old astronomer| occupation living in Edison| city, New Jersey| state. Born on November 21, 1988| date_of_birth, he grew up in a bilingual Italian| race_ethnicity household and speaks English| language at home and work. He earned his bachelor’s degree| degree in physics| field_of_study from the University of New Jersey| university and later completed a PhD| degree in astrophysics| field_of_study at Princeton| university, where his dissertation focused on exoplanet atmospheres. After graduation he spent three years at NASA’s Goddard Space Flight Center| organization_name before joining SpaceX| organization_name’s research division, where he now leads a team analyzing data from the Starlink telescope array. Idilio| first_name describes himself as secular| political_view and leans progressive| political_view on most political issues, often volunteering for science outreach programs in his community. Outside the lab, Idilio| first_name shares a modest house on West Roberts Drive| street_address with his wife, Maya| first_name, and their two young daughters, Lina| first_name and Zara| first_name. His mother, Elena| first_name, lives nearby and still cooks the family’s favorite pasta on Sundays, while his father, Marco| first_name, retired| employment_status from an engineering firm in New York| state. Family gatherings are a mix of lively conversation and stargazing sessions on the backyard deck, where Idilio| first_name points out constellations and tells stories of the cosmos that inspire his children’s curiosity.

Replaced

Dario| first_name Hawthorne| last_name is a 36| age‑year‑old geologist| occupation living in Boulder| city, Colorado| state. Born on April 3, 1990| date_of_birth, he grew up in a bilingual Greek| race_ethnicity household and speaks Spanish| language at home and work. He earned his Associate’s degree| degree in chemistry| field_of_study from the University of Colorado| university and later completed a Doctor of Medicine| degree in planetary science| field_of_study at University of Chicago| university, where his dissertation focused on exoplanet atmospheres. After graduation he spent three years at European Space Agency’s ESTEC| organization_name before joining Blue Origin| organization_name’s research division, where he now leads a team analyzing data from the Starlink telescope array. Dario| first_name describes himself as agnostic| political_view and leans centrist| political_view on most political issues, often volunteering for science outreach programs in his community. Outside the lab, Dario| first_name shares a modest house on East Maple Avenue| street_address with his wife, Isabel| first_name, and their two young daughters, Mia| first_name and Nina| first_name. His mother, Sofia| first_name, lives nearby and still cooks the family’s favorite pasta on Sundays, while his father, Antonio| first_name, on sabbatical| employment_status from an engineering firm in Oregon| state. Family gatherings are a mix of lively conversation and stargazing sessions on the backyard deck, where Dario| first_name points out constellations and tells stories of the cosmos that inspire his children’s curiosity.

Replacement Map

Original	Label	Replacement
37	age	36
Bell	last_name	Hawthorne
Edison	city	Boulder
Elena	first_name	Sofia
English	language	Spanish
Idilio	first_name	Dario
Italian	race_ethnicity	Greek
Lina	first_name	Mia
Marco	first_name	Antonio
Maya	first_name	Isabel
NASA’s Goddard Space Flight Center	organization_name	European Space Agency’s ESTEC
New Jersey	state	Colorado
New York	state	Oregon
November 21, 1988	date_of_birth	April 3, 1990
PhD	degree	Doctor of Medicine
Princeton	university	University of Chicago
SpaceX	organization_name	Blue Origin
University of New Jersey	university	University of Colorado
West Roberts Drive	street_address	East Maple Avenue
Zara	first_name	Nina
astronomer	occupation	geologist
bachelor’s degree	degree	Associate’s degree
in astrophysics	field_of_study	in planetary science
in physics	field_of_study	in chemistry
progressive	political_view	centrist
retired	employment_status	on sabbatical
secular	political_view	agnostic

In [9]:

preview.dataframe

preview.dataframe

Out[9]:

	biography	biography_with_spans	final_entities	biography_replaced
0	Bobby Watford, a 40‑year‑old Mexican veterinar...	<first_name>Bobby</first_name> <last_name>Watf...	{'entities': [{'end_position': 5, 'id': 'first...	Ethan Kline, a 45‑year‑old Filipino zoological...
1	Idilio Bell is a 37‑year‑old astronomer living...	<first_name>Idilio</first_name> <last_name>Bel...	{'entities': [{'end_position': 6, 'id': 'first...	Dario Hawthorne is a 36‑year‑old geologist liv...
2	Jodi Allison, 36, lives at 204 Bluegrass in Cl...	<first_name>Jodi</first_name> <last_name>Allis...	{'entities': [{'end_position': 4, 'id': 'first...	Tara Harper, 42, lives at 317 Riverbend in Cha...

🚀 Full run¶

• run() processes the entire dataset with the same config you previewed.
• Access the output via result.dataframe.

In [10]:

result = anonymizer.run(config=config, data=input_data)
print(result)

result = anonymizer.run(config=config, data=input_data) print(result)

[11:00:55] [INFO] 📂 Loaded 25 records from https://raw.githubusercontent.com/NVIDIA-NeMo/Anonymizer/refs/heads/main/docs/data/NVIDIA_synthetic_biographies.csv (column: 'biography')

[11:00:55] [INFO] 🔍 Running entity detection on 25 records

[11:00:55] [INFO] detection labels in scope: (default: 65 labels; see anonymizer.DEFAULT_ENTITY_LABELS for list)

[11:03:15] [INFO]   |-- 📋 Detection complete — 661 entities found across 25 records (0 failed) [139.8s]

[11:03:15] [INFO]   |-- labels: first_name=152, organization_name=68, occupation=45, city=40, field_of_study=36, university=35, race_ethnicity=30, last_name=27, age=26, state=26, degree=26, political_view=25, religious_belief=25, street_address=23, language=18, place_name=12, employment_status=10, county=10, date_of_birth=9, education_level=6, date=5, company_name=3, landmark=1, country=1, gender=1, postcode=1

[11:03:15] [INFO] 🔄 Running Substitute replacement

[11:04:40] [INFO]   |-- 📋 Replacement complete (0 failed) [85.0s]

[11:04:40] [INFO] 🎉 Pipeline complete — 25 records processed, 0 total failures

AnonymizerResult(rows=25, columns=4, trace_columns=22, failed_records=0)

In [11]:

result.dataframe.head()

result.dataframe.head()

Out[11]:

	biography	biography_with_spans	final_entities	biography_replaced
0	Bobby Watford, a 40‑year‑old Mexican veterinar...	<first_name>Bobby</first_name> <last_name>Watf...	{'entities': array([{'end_position': 5, 'id': ...	Ethan Hawkins, a 52‑year‑old Filipino zoologis...
1	Idilio Bell is a 37‑year‑old astronomer living...	<first_name>Idilio</first_name> <last_name>Bel...	{'entities': array([{'end_position': 6, 'id': ...	Ravi Khan is a 42‑year‑old geophysicist living...
2	Jodi Allison, 36, lives at 204 Bluegrass in Cl...	<first_name>Jodi</first_name> <last_name>Allis...	{'entities': array([{'end_position': 4, 'id': ...	Lena Keller, 42, lives at 317 Willowbrook in E...
3	James Mills is a 69‑year‑old paramedic who liv...	<first_name>James</first_name> <last_name>Mill...	{'entities': array([{'end_position': 5, 'id': ...	Robert Harper is a 74‑year‑old firefighter who...
4	Nancy Burton is a 21‑year‑old cashier who live...	<first_name>Nancy</first_name> <last_name>Burt...	{'entities': array([{'end_position': 5, 'id': ...	Maya Keller is a 23‑year‑old stock clerk who l...

📊 (Optional) Evaluate replacement quality¶

• evaluate() is a separate, opt-in step that scores the output with LLM-as-judge metrics.
• For Substitute, all four metrics run: Detection Validity, Type Fidelity, Relational Consistency, Attribute Fidelity.
• Skip it for routine runs; call it when you want LLM-side confidence on the output. Costs LLM calls per record, so try it on preview first.

In [12]:

evaluated = anonymizer.evaluate(preview)
evaluated.display_record(0)

evaluated = anonymizer.evaluate(preview) evaluated.display_record(0)

Anonymizer Preview (record 0)

Original

Bobby| first_name Watford| last_name, a 40| age‑year‑old Mexican| race_ethnicity veterinarian| occupation living in Denver| city, Colorado| state, grew up on the outskirts of the city and developed a love for animals early on. After graduating from Jefferson High| organization_name, he earned his DVM| degree at the University of Colorado Boulder| university, where he also completed a research stint in wildlife health| field_of_study. Fluent in English| language, Bobby| first_name has always described his upbringing as a blend of small‑town curiosity and the vibrant culture of his community, values that continue to shape his compassionate approach to animal care. Since finishing his training, Bobby| first_name has worked at VCA Animal Hospital| organization_name and later at the Colorado Veterinary Clinic| organization_name, where he now leads a busy mixed‑practice team. He identifies as a Christian Democrat| political_view and often volunteers at local shelters, a habit encouraged by his wife, Maya| first_name, and their two teenage children, Aria and Leo| first_name. Outside the clinic, Bobby| first_name enjoys hiking the Rockies| place_name with his family and mentoring veterinary students from his alma mater.

Replaced

Ethan| first_name Kline| last_name, a 45| age‑year‑old Filipino| race_ethnicity zoological researcher| occupation living in Portland| city, Oregon| state, grew up on the outskirts of the city and developed a love for animals early on. After graduating from Lincoln High| organization_name, he earned his Master of Veterinary Science| degree at the Oregon State University| university, where he also completed a research stint in conservation genetics| field_of_study. Fluent in Spanish| language, Ethan| first_name has always described his upbringing as a blend of small‑town curiosity and the vibrant culture of his community, values that continue to shape his compassionate approach to animal care. Since finishing his training, Ethan| first_name has worked at Pacific Veterinary Group| organization_name and later at the Oregon Animal Care Center| organization_name, where he now leads a busy mixed‑practice team. He identifies as a Green Party| political_view and often volunteers at local shelters, a habit encouraged by his wife, Leah| first_name, and their two teenage children, Sofia and Mateo| first_name. Outside the clinic, Ethan| first_name enjoys hiking the Cascade Range| place_name with his family and mentoring veterinary students from his alma mater.

Detection Judge

Detection Validity: Partially Satisfied (Judge Agreement: 17/18)

Judge Agreement: The number of entity-label pairs accepted by the evaluation judge out of all pairs produced by the Anonymizer.

Show 1 flagged entity(ies)

Value	Label	Reason
Aria and Leo	first_name	wrong_boundary: the span combines two separate first names and a conjunction, should be two distinct first_name entities.

Type Fidelity

Type Fidelity: Satisfied (Judge Agreement: 18/18)

Attribute Fidelity

Attribute Fidelity: Satisfied (Judge Agreement: 4/4)

Show 4 evaluated entity(ies)

Original	Label	Synthetic	Attributes	Status	Reason
40	age	45	age_bucket	Pass	Age bucket preserved (adult → middle‑aged, adjacent buckets).
Aria and Leo	first_name	Sofia and Mateo	gender	Pass	Both names keep the same genders (female → female, male → male).
Bobby	first_name	Ethan	gender	Pass	Male gender preserved.
Maya	first_name	Leah	gender	Pass	Female gender preserved.

Relational Consistency

Relational Consistency: Satisfied (Judge Agreement: 8/8)

Show 8 checked relation(s)

Relation	Entities	Status	Reason
city <-> state	Denver (city) -> Portland, Colorado (state) -> Oregon	Pass	Portland is a city in Oregon, preserving the geographic relation.
first_name <-> pronouns	Bobby (first_name) -> Ethan	Pass	The pronouns 'he/his' in the text match the male name Ethan.
occupation <-> organization_name (Pacific Veterinary Group)	veterinarian (occupation) -> zoological researcher, VCA Animal Hospital (organization_name) -> Pacific Veterinary Group	Pass	A zoological researcher can plausibly work at a veterinary group.
occupation <-> organization_name (Oregon Animal Care Center)	veterinarian (occupation) -> zoological researcher, Colorado Veterinary Clinic (organization_name) -> Oregon Animal Care Center	Pass	A zoological researcher can plausibly work at an animal care center.
occupation <-> degree	veterinarian (occupation) -> zoological researcher, DVM (degree) -> Master of Veterinary Science	Pass	A Master of Veterinary Science supports a role as a zoological researcher.
occupation <-> field_of_study	veterinarian (occupation) -> zoological researcher, wildlife health (field_of_study) -> conservation genetics	Pass	Conservation genetics aligns with a zoological researcher’s work.
age <-> occupation	40 (age) -> 45, veterinarian (occupation) -> zoological researcher	Pass	A 45‑year‑old can reasonably be a zoological researcher.
age <-> degree	40 (age) -> 45, DVM (degree) -> Master of Veterinary Science	Pass	A 45‑year‑old can hold a Master of Veterinary Science.

Replacement Map

Original	Label	Replacement
40	age	45
Aria and Leo	first_name	Sofia and Mateo
Bobby	first_name	Ethan
Christian Democrat	political_view	Green Party
Colorado	state	Oregon
Colorado Veterinary Clinic	organization_name	Oregon Animal Care Center
DVM	degree	Master of Veterinary Science
Denver	city	Portland
English	language	Spanish
Jefferson High	organization_name	Lincoln High
Maya	first_name	Leah
Mexican	race_ethnicity	Filipino
Rockies	place_name	Cascade Range
University of Colorado Boulder	university	Oregon State University
VCA Animal Hospital	organization_name	Pacific Veterinary Group
Watford	last_name	Kline
veterinarian	occupation	zoological researcher
wildlife health	field_of_study	conservation genetics

⏭️ Next steps¶

• 🔍 Inspecting Detected Entities -- dig into what the detection pipeline found and debug quality.
• 🎯 Choosing a Replacement Strategy -- compare Redact, Annotate, Hash, and Substitute side-by-side.
• ✏️ Rewriting Biographies -- generate privacy-safe paraphrases instead of token-level replacements.