Skip to main content

pii-masker-ai 🔒🤖

PyPI version Python versions License: MIT Tests good first issues Contributions welcome

Ultra-fast, zero-dependency PII masking, redaction, and de-identification for AI prompts, LLM agents, and datasets.

Detect and mask supported patterns before sending text to an external model. Review the output: pattern matching cannot guarantee that all sensitive data has been removed.

Start here: your first contribution

Featured beginner issue #11: Write a first redaction walkthrough using synthetic data. Read CONTRIBUTING.md for setup, claiming an issue, and opening a draft PR.

Repository: pii-masker-ai; PyPI distribution: pii-masker-ai; Python import: pii_masker. The installed CLI is pii-masker.

Try this from a reviewed source checkout, in the repository root, with Python 3.8+. It uses synthetic inputs and needs no API key or network access:

from pii_masker import redact_text
print(redact_text("Contact demo@example.com"))

Expected output:

Contact [EMAIL]

Pattern detection can miss personal data. Review results before sharing them, and keep reversible mappings private because they contain original values.


⚡ The AI Privacy Problem & Solution

sequenceDiagram
    participant User
    participant PII_Masker as pii-masker-ai
    participant LLM as Claude / OpenAI / Gemini
    
    User->>PII_Masker: "Contact John at john@company.com with phone 0912345678"
    Note over PII_Masker: Reversible Masking
    PII_Masker->>LLM: "Contact John at <EMAIL_1> with phone <PHONE_1>"
    LLM->>PII_Masker: "Scheduled an appointment for <EMAIL_1> via <PHONE_1>."
    Note over PII_Masker: Automatic Unmasking
    PII_Masker->>User: "Scheduled an appointment for john@company.com via 0912345678."

🌟 Key Features

  • Zero dependencies: Written in 100% pure Python standard library. No third-party runtime dependencies; this does not eliminate security risks.
  • 4 De-identification Modes:
    1. reversible: Sequential numbered tokens (<EMAIL_1>, <PHONE_1>) for LLM chat round-trips.
    2. redact: Fixed redaction tags ([EMAIL], [API_KEY]) for audit logs and security reporting.
    3. hash: Salted SHA-256 pseudonym digests (<EMAIL_a1b2c3d4>) for persistent agent memory & cross-session consistency.
    4. synthetic: Realistic fake dummy data (user1@example.com, +84901234561) for realistic model reasoning.
  • Allowlist & Safe Exemption: Safely exempt public support emails, internal company domains, or localhost IPs.
  • LangChain & LLM Chat Wrapper: Wrap any LLM or ChatModel in 1 line of code with automatic prompt masking and response unmasking.
  • Batch Dataset Sanitizer: High-speed CLI to sanitize .jsonl, .csv, and .txt datasets with column/field targeting.
  • Comprehensive Pattern Suite (v0.3.0):
    • Financial: Credit cards (Visa, MasterCard, Amex, Discover, JCB) with Luhn algorithm verification, IBAN bank codes.
    • Network: IPv4, IPv6 addresses, MAC addresses.
    • Secrets & API Keys: JWT tokens, PEM Private Keys (RSA, EC), OpenAI, Anthropic, GitHub, AWS, Slack, Stripe, Google Cloud.
    • Global & Regional: Email, US SSN, International phone (E.164), Vietnam Citizen ID (CCCD/CMND), Tax ID, Passports.

📦 Installation

pip install pii-masker-ai

🚀 Quickstart (Python API)

1. Reversible Masking for LLMs

from pii_masker import mask_text, unmask_text

# 1. Mask prompt before calling Claude / OpenAI
prompt = "Please send invoice #123 to customer alice@example.com, phone 0912345678."
result = mask_text(prompt, reversible=True)

print(result.masked_text)
# Output: "Please send invoice #123 to customer <EMAIL_1>, phone <PHONE_1>."

# 2. Call your LLM with masked_text...
llm_response = "I have drafted the invoice for <EMAIL_1> and notified <PHONE_1>."

# 3. Restore original customer PII in the response
final_output = unmask_text(llm_response, result.mapping)
print(final_output)
# Output: "I have drafted the invoice for alice@example.com and notified 0912345678."

2. LangChain & Claude Chat Wrapper

from pii_masker.integrations import PIIChatWrapper
from langchain_anthropic import ChatAnthropic

base_model = ChatAnthropic(model="claude-3-5-sonnet-20241022")

# Shield your LLM: automatically sanitizes prompts & unmasks responses
shielded_model = PIIChatWrapper(base_model)

response = shielded_model.invoke("Send email to alice@company.com with bill $500")
print(response.content)

3. Pseudonymization (Hash Mode) & Synthetic Data

from pii_masker import PIIMasker, MaskMode

masker = PIIMasker(salt="company-secret-salt", allowlist=["support@mycompany.com"])

# Hash mode for persistent agent memory
res_hash = masker.mask("User dev@corp.io reported an issue", mode=MaskMode.HASH)
print(res_hash.masked_text)
# Output: "User <EMAIL_8f2b3e41> reported an issue"

# Synthetic replacement
res_synth = masker.synthetic_mask("Customer phone is 0912345678")
print(res_synth.masked_text)
# Output: "Customer phone is +84901234561"

💻 CLI Usage

Masking text

# Reversible masking
pii-masker mask "My email is alice@company.com"

# Redact mode
pii-masker mask "Contact support@example.com" --mode redact

# Output JSON with mapping
pii-masker mask "User 0912345678" --json --save-mapping map.json

# Restore text
pii-masker unmask "Hello <PHONE_1>" -m map.json

Batch Dataset Sanitization (JSONL & CSV)

# Sanitize fine-tuning or training datasets
pii-masker batch -i raw_dataset.jsonl -o clean_dataset.jsonl --fields prompt,response --mode redact

# Sanitize CSV customer data
pii-masker batch -i users.csv -o safe_users.csv --fields email,phone --mode synthetic

Scanning files for PII leaks (CI/CD friendly)

# Returns exit code 1 if any PII leak is found
pii-masker scan ./data/ --strict

🌍 Supported PII Categories

Category Description Examples
EMAIL Standard RFC email addresses user@example.com
PHONE International & Vietnamese numbers +84912345678, 0901234567
CREDIT_CARD Major credit cards with Luhn verification 4532-xxxx-xxxx-9012
IBAN International Bank Account Numbers DE89370400440532013000
IP_ADDRESS IPv4 & IPv6 addresses 198.51.100.1, 2001:db8::1
MAC_ADDRESS Network hardware MAC addresses 00:1A:2B:3C:4D:5E
API_KEY OpenAI, Anthropic, GitHub, AWS, Stripe keys sk-..., sk-ant-..., ghp_..., AKIA...
JWT_TOKEN JSON Web Tokens eyJhbGci...
PRIVATE_KEY RSA / EC PEM private keys -----BEGIN PRIVATE KEY-----
GOV_ID National IDs (e.g. VN CCCD 12-digit / US SSN) 001201012345, 123-45-6789
TAX_ID Business tax identification numbers 0123456789-001
PASSPORT Passport identification numbers B1234567

🤝 Community: Add Your Country's PII Rules!

We are actively expanding localized PII regex rules for more countries! Country-specific rules need format references, synthetic test cases, and validation:

  • 🇫🇷 France (NIR / Carte Vitale)
  • 🇯🇵 Japan (My Number)
  • 🇩🇪 Germany (Steuer-ID)
  • 🇬🇧 UK (National Insurance Number)

See CONTRIBUTING.md to get started.


📄 License

MIT License © 2026 lui01212

Metadata

Release files for pii-masker-ai 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pii-masker-ai 0.3.1
File Size Uploaded Provenance Actions
pii_masker_ai-0.3.1.tar.gz 26.0 kB With provenance Details for pii_masker_ai-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pii-masker-ai 0.3.1
File Interpreter ABI Platform Actions
pii_masker_ai-0.3.1-py3-none-any.whl Python 3 none any Details for pii_masker_ai-0.3.1-py3-none-any.whl

Total release size: 47.4 kB

Release files / pii_masker_ai-0.3.1.tar.gz

Download URL pii_masker_ai-0.3.1.tar.gz
Size 26.0 kB
Tags Source
SHA-256 checksum
How to use checksums
92272b93cb5674358f6680158e48de77415fbd194ed1c35d2ec0684b577626ea
BLAKE2b-256 checksum
How to use checksums
a774b1dd744628db473699795673b0a9e70fb54d1fb2a7957f71acc0c85fd539
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.

Transparency log

Release files / pii_masker_ai-0.3.1-py3-none-any.whl

Download URL pii_masker_ai-0.3.1-py3-none-any.whl
Size 21.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c1e5fd8e0869d2a840882b516d7aedb406f7174046d6edfebe7b596380308d77
BLAKE2b-256 checksum
How to use checksums
2777171c692f41ec53f00aed4bbe291c17d3f3c3f721a271b0515ef37b191228
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.

Transparency log

Security for pii-masker-ai 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pii_masker_ai-0.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page