🕵️ 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¶

• Install the notebook extra, then provide credentials for the configured external LLM providers.
• create_anonymizer() starts pinned GLiNER2 locally and selects CUDA, MPS, or CPU automatically.
• The default external LLM models currently use OpenRouter; its terms and privacy practices apply.

Data boundary: GLiNER2 detection runs locally in this notebook environment. LLM-assisted validation, augmentation, replacement, rewriting, repair, and evaluation use configured external hosts and may send them original or tagged input text. Do not treat this configuration as an all-local privacy boundary.

• configure_logging(LoggingConfig.default()) keeps logs at INFO. Switch to LoggingConfig.debug() when troubleshooting.

In [1]:

import getpass
import os
import subprocess
import sys

package_spec = os.getenv("ANONYMIZER_NOTEBOOK_PACKAGE", "nemo-anonymizer[notebooks]")
subprocess.check_call([sys.executable, "-m", "pip", "install", "--quiet", package_spec])

import getpass import os import subprocess import sys package_spec = os.getenv("ANONYMIZER_NOTEBOOK_PACKAGE", "nemo-anonymizer[notebooks]") subprocess.check_call([sys.executable, "-m", "pip", "install", "--quiet", package_spec])

Out[1]:

0

In [2]:

from anonymizer.notebooks import required_api_key_environment_variables

for variable in required_api_key_environment_variables():
    key = getpass.getpass(f"Enter {variable}: ").strip()
    if not key:
        raise RuntimeError(f"{variable} is required by the configured external model providers.")
    os.environ[variable] = key

from anonymizer.notebooks import required_api_key_environment_variables for variable in required_api_key_environment_variables(): key = getpass.getpass(f"Enter {variable}: ").strip() if not key: raise RuntimeError(f"{variable} is required by the configured external model providers.") os.environ[variable] = key

In [3]:

from anonymizer import AnonymizerConfig, AnonymizerInput, LoggingConfig, Substitute, configure_logging
from anonymizer.notebooks import create_anonymizer, stop_local_runtime

configure_logging(LoggingConfig.default())

from anonymizer import AnonymizerConfig, AnonymizerInput, LoggingConfig, Substitute, configure_logging from anonymizer.notebooks import create_anonymizer, stop_local_runtime configure_logging(LoggingConfig.default())

In [4]:

anonymizer = create_anonymizer()

anonymizer = create_anonymizer()

[00:00:01] [INFO] 🔧 Anonymizer initialized with 5 model configs

[00:00:01] [INFO]   |-- 🔎 detector:  local-gliner2-pii

[00:00:01] [INFO]   |-- ✅ validator: gpt-oss-120b

[00:00:01] [INFO]   |-- 🧩 augmenter: gpt-oss-120b

GLiNER2 ready: model=fastino/gliner2-privacy-filter-PII-multi revision=59894c087cb2923b01f337d4ee72f6ff84d5bdd6 device=mps endpoint=http://127.0.0.1:52975/v1

📦 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)

[00:00:01] [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')

[00:00:01] [INFO] 🔍 Running entity detection on 3 records

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

[00:01:41] [INFO]   |-- 📋 Detection complete — 84 entities found across 3 records (0 failed) [100.1s]

[00:01:41] [INFO]   |-- labels: first_name=23, occupation=6, age=5, organization_name=5, field_of_study=5, company_name=5, city=4, degree=4, university=4, last_name=3, state=3, language=3, political_view=3, place_name=2, race_ethnicity=2, street_address=2, religious_belief=2, nationality=1, date_of_birth=1, landmark=1

[00:01:41] [INFO] 🔄 Running Substitute replacement

[00:02:53] [INFO]   |-- 📋 Replacement complete (0 failed) [71.7s]

[00:02:53] [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‑year‑old| age Mexican| nationality 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| field_of_study. 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| first_name 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 Henderson| last_name, a 52-year-old| age Canadian| nationality marine biologist| 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 Public Health| degree at the University of Washington Seattle| university, where he also completed a research stint in climate science| field_of_study. Fluent in German| 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 public health| field_of_study. Since finishing his training, Ethan| first_name has worked at Paws & Claws Animal Hospital| organization_name and later at the Willamette Veterinary Clinic| organization_name, where he now leads a busy mixed‑practice team. He identifies as a Libertarian| political_view and often volunteers at local shelters, a habit encouraged by his wife, Nina| first_name, and their two teenage children, Sofia| first_name and Jasper| first_name. Outside the clinic, Ethan| first_name enjoys hiking the Sierra Nevada| place_name with his family and mentoring veterinary students from his alma mater.

Replacement Map

Original	Label	Replacement
40‑year‑old	age	52-year-old
Aria	first_name	Sofia
Bobby	first_name	Ethan
Christian Democrat	political_view	Libertarian
Colorado	state	Oregon
Colorado Veterinary Clinic	organization_name	Willamette Veterinary Clinic
DVM	degree	Master of Public Health
Denver	city	Portland
English	language	German
Jefferson High	organization_name	Lincoln High
Leo	first_name	Jasper
Maya	first_name	Nina
Mexican	nationality	Canadian
Rockies	place_name	Sierra Nevada
University of Colorado Boulder	university	University of Washington Seattle
VCA Animal Hospital	organization_name	Paws & Claws Animal Hospital
Watford	last_name	Henderson
animal care	field_of_study	public health
veterinarian	occupation	marine biologist
wildlife health	field_of_study	climate science

In [8]:

preview.display_record(1)

preview.display_record(1)

Anonymizer Preview (record 1)

Original

Idilio| first_name Bell| last_name is a 37‑year‑old| age 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| field_of_study. After graduation he spent three years at NASA| company_name’s Goddard Space Flight Center| landmark before joining SpaceX| company_name’s research division, where he now leads a team analyzing data from the Starlink| organization_name telescope array. Idilio| first_name describes himself as secular 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 cook| occupations the family’s favorite pasta on Sundays, while his father, Marco| first_name, retired from an engineering firm in New York| city. Family gatherings are a mix of lively conversation and stargazing sessions on the backyard deck| place_name, where Idilio| first_name points out constellations and tells stories of the cosmos that inspire his children’s curiosity.

Replaced

Santiago| first_name Khan| last_name is a 42‑year‑old| age geophysicist| occupation living in Boulder| city, Colorado| state. Born on April 12, 1984| date_of_birth, he grew up in a bilingual Greek| race_ethnicity household and speaks Spanish| language at home and work. He earned his Bachelor of Arts| degree in chemistry| field_of_study from the University of Colorado| university and later completed a Doctor of Engineering| degree in marine biology| field_of_study at University of Chicago| university, where his dissertation focused on quantum computing| field_of_study. After graduation he spent three years at European Space Agency| company_name’s Kennedy Space Center| landmark before joining Blue Origin| company_name’s research division, where he now leads a team analyzing data from the OneWeb| organization_name telescope array. Santiago| first_name describes himself as secular and leans centrist| political_view on most political issues, often volunteering for science outreach programs in his community. Outside the lab, Santiago| first_name shares a modest house on North Maple Avenue| street_address with his wife, Priya| first_name, and their two young daughters, Aisha| first_name and Nadia| first_name. His mother, Sofia| first_name, lives nearby and still carpenter| occupations the family’s favorite pasta on Sundays, while his father, Diego| first_name, retired from an engineering firm in Seattle| city. Family gatherings are a mix of lively conversation and stargazing sessions on the garden patio| place_name, where Santiago| first_name points out constellations and tells stories of the cosmos that inspire his children’s curiosity.

Replacement Map

Original	Label	Replacement
37‑year‑old	age	42‑year‑old
Bell	last_name	Khan
Edison	city	Boulder
Elena	first_name	Sofia
English	language	Spanish
Goddard Space Flight Center	landmark	Kennedy Space Center
Idilio	first_name	Santiago
Italian	race_ethnicity	Greek
Lina	first_name	Aisha
Marco	first_name	Diego
Maya	first_name	Priya
NASA	company_name	European Space Agency
New Jersey	state	Colorado
New York	city	Seattle
November 21, 1988	date_of_birth	April 12, 1984
PhD	degree	Doctor of Engineering
Princeton	university	University of Chicago
SpaceX	company_name	Blue Origin
Starlink	organization_name	OneWeb
University of New Jersey	university	University of Colorado
West Roberts Drive	street_address	North Maple Avenue
Zara	first_name	Nadia
astronomer	occupation	geophysicist
astrophysics	field_of_study	marine biology
bachelor’s degree	degree	Bachelor of Arts
backyard deck	place_name	garden patio
cook	occupation	carpenter
exoplanet atmospheres	field_of_study	quantum computing
physics	field_of_study	chemistry
progressive	political_view	centrist

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': [{'id': 'first_name_0_5', 'value'...	Ethan Henderson, a 52-year-old Canadian marine...
1	Idilio Bell is a 37‑year‑old astronomer living...	<first_name>Idilio</first_name> <last_name>Bel...	{'entities': [{'id': 'first_name_0_6', 'value'...	Santiago Khan is a 42‑year‑old geophysicist li...
2	Jodi Allison, 36, lives at 204 Bluegrass in Cl...	<first_name>Jodi</first_name> <last_name>Allis...	{'entities': [{'id': 'first_name_0_4', 'value'...	Leah Keller, 42, lives at 317 Oakridge in Bent...

🚀 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)

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

[00:02:54] [INFO] 🔍 Running entity detection on 25 records

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

[00:07:59] [INFO]   |-- 📋 Detection complete — 695 entities found across 25 records (0 failed) [305.1s]

[00:07:59] [INFO]   |-- labels: first_name=153, field_of_study=52, occupation=47, company_name=44, organization_name=42, city=38, university=35, last_name=26, age=26, state=25, degree=25, political_view=25, religious_belief=25, street_address=23, language=19, place_name=18, race_ethnicity=18, county=11, nationality=10, date_of_birth=9, employment_status=9, education_level=6, date=5, landmark=1, country=1, sexuality=1, postcode=1

[00:07:59] [INFO] 🔄 Running Substitute replacement

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

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

AnonymizerResult(rows=25, columns=4, trace_columns=23, 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([{'id': 'first_name_0_5', '...	Ethan Kline, a 45‑year‑old Canadian marine bio...
1	Idilio Bell is a 37‑year‑old astronomer living...	<first_name>Idilio</first_name> <last_name>Bel...	{'entities': array([{'id': 'first_name_0_6', '...	Rafael Hawthorne is a 45‑year‑old geophysicist...
2	Jodi Allison, 36, lives at 204 Bluegrass in Cl...	<first_name>Jodi</first_name> <last_name>Allis...	{'entities': array([{'id': 'first_name_0_4', '...	Leah Harper, 42, lives at 317 Oakridge in Bent...
3	James Mills is a 69‑year‑old paramedic who liv...	<first_name>James</first_name> <last_name>Mill...	{'entities': array([{'id': 'first_name_0_5', '...	Robert Harper is a 72‑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([{'id': 'first_name_0_5', '...	Sophie Keller is a 27‑year‑old customer servic...

📊 (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)

[00:11:03] [INFO] 🧪 Running Substitute evaluation on 3 records

[00:11:03] [INFO]   |-- ⚖️ Running replace judges

[00:12:31] [INFO]   |-- 📋 Replace judges complete [88.3s]

[00:12:31] [INFO] 🎉 Evaluation complete — 3 records processed [88.3s]

Anonymizer Preview (record 0)

Original

Bobby| first_name Watford| last_name, a 40‑year‑old| age Mexican| nationality 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| field_of_study. 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| first_name 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 Henderson| last_name, a 52-year-old| age Canadian| nationality marine biologist| 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 Public Health| degree at the University of Washington Seattle| university, where he also completed a research stint in climate science| field_of_study. Fluent in German| 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 public health| field_of_study. Since finishing his training, Ethan| first_name has worked at Paws & Claws Animal Hospital| organization_name and later at the Willamette Veterinary Clinic| organization_name, where he now leads a busy mixed‑practice team. He identifies as a Libertarian| political_view and often volunteers at local shelters, a habit encouraged by his wife, Nina| first_name, and their two teenage children, Sofia| first_name and Jasper| first_name. Outside the clinic, Ethan| first_name enjoys hiking the Sierra Nevada| place_name with his family and mentoring veterinary students from his alma mater.

Entity Coverage

Entity Coverage: Satisfied — 15/15 (100%)

Type Fidelity

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

Attribute Fidelity

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

Show 5 evaluated entity(ies)

Original	Label	Synthetic	Attributes	Status	Reason
40‑year‑old	age	52-year-old	age_bucket	Pass	Age bucket preserved (adult to adjacent middle‑aged bucket).
Aria	first_name	Sofia	gender	Pass	Gender preserved (both feminine).
Bobby	first_name	Ethan	gender	Pass	Gender preserved (both masculine).
Leo	first_name	Jasper	gender	Pass	Gender preserved (both masculine).
Maya	first_name	Nina	gender	Pass	Gender preserved (both feminine).

Relational Consistency

Relational Consistency: Partially Satisfied (Judge Agreement: 7/9)

Show 9 checked relation(s)

Relation	Entities	Status	Reason
city <-> state	Denver (city) -> Portland, Colorado (state) -> Oregon	Pass	Portland is a city located in Oregon.
occupation <-> organization_name	veterinarian (occupation) -> marine biologist, VCA Animal Hospital (organization_name) -> Paws & Claws Animal Hospital	Fail	A marine biologist role is not plausible at an animal hospital.
occupation <-> organization_name	veterinarian (occupation) -> marine biologist, Colorado Veterinary Clinic (organization_name) -> Willamette Veterinary Clinic	Fail	A marine biologist role is not plausible at a veterinary clinic.
occupation <-> degree	veterinarian (occupation) -> marine biologist, DVM (degree) -> Master of Public Health	Pass	A marine biologist can hold a Master of Public Health degree.
occupation <-> field_of_study	veterinarian (occupation) -> marine biologist, animal care (field_of_study) -> public health	Pass	Public health is compatible with a marine biology career.
occupation <-> field_of_study	veterinarian (occupation) -> marine biologist, wildlife health (field_of_study) -> climate science	Pass	Climate science is compatible with marine biology work.
age <-> occupation	40‑year‑old (age) -> 52-year-old, veterinarian (occupation) -> marine biologist	Pass	A 52‑year‑old can reasonably be a marine biologist.
age <-> degree	40‑year‑old (age) -> 52-year-old, DVM (degree) -> Master of Public Health	Pass	Being 52 years old is plausible for holding an MPH.
first_name <-> pronoun	Bobby (first_name) -> Ethan	Pass	The name Ethan is male and matches the masculine pronouns used.

Replacement Map

Original	Label	Replacement
40‑year‑old	age	52-year-old
Aria	first_name	Sofia
Bobby	first_name	Ethan
Christian Democrat	political_view	Libertarian
Colorado	state	Oregon
Colorado Veterinary Clinic	organization_name	Willamette Veterinary Clinic
DVM	degree	Master of Public Health
Denver	city	Portland
English	language	German
Jefferson High	organization_name	Lincoln High
Leo	first_name	Jasper
Maya	first_name	Nina
Mexican	nationality	Canadian
Rockies	place_name	Sierra Nevada
University of Colorado Boulder	university	University of Washington Seattle
VCA Animal Hospital	organization_name	Paws & Claws Animal Hospital
Watford	last_name	Henderson
animal care	field_of_study	public health
veterinarian	occupation	marine biologist
wildlife health	field_of_study	climate science

⏭️ 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.

In [13]:

stop_local_runtime()

stop_local_runtime()