venus-pii

Give AI a blindfold before it sees your data.

Every developer calling an LLM API is sending user data to someone else's server. This library lets you blindfold the AI with one line of code — before the data ever leaves your machine.

from venus_pii import sanitize

safe_df = sanitize(df)
# "张三" → "PERSON_a3f8c21e"    (HMAC, irreversible without your key)
# "110101200001011234" → [REMOVED]  (ID card, blocked entirely)
# "85" → "85"                      (score, passed through)

Your data. Your key. Your rules.

Why

Install

pip install venus-pii

Three Protection Levels

Usage

Basic — One line

import polars as pl
from venus_pii import sanitize

df = pl.DataFrame({
    "name": ["Alice", "Bob"],
    "ssn": ["123-45-6789", "987-65-4321"],
    "score": [95, 88],
})

result = sanitize(df)
print(result.sanitized_df)
# name: PERSON_7a3f..., PERSON_b2e9...
# ssn: [column removed]
# score: 95, 88

print(result.blocked_columns)   # ["ssn"]
print(result.token_maps.keys()) # ["name"]

Restore after processing

from venus_pii import sanitize, restore

result = sanitize(df)
safe_df = result.sanitized_df

# ... send safe_df to LLM, get results back ...

original_df = restore(safe_df, result.token_maps)
# "PERSON_7a3f..." → "Alice"

Custom HMAC key

export VENUS_PII_KEY="my-secret-enterprise-key"

Same name + same key = same token (deterministic across sessions). Different key = different token (multi-tenant isolation).

Detect without masking

from venus_pii import detect

reports = detect(df)
for r in reports:
    print(f"{r.column_name}: {r.category} ({r.level})")
# name: name (mask)
# ssn: id_card (block)
# score: none (pass)

Supported PII Categories

Every new PII detector is one function + one PR. See CONTRIBUTING.md.

How HMAC tokenization works

"张三" + secret_key
    → HMAC-SHA256 → a3f8c21e78b4...
    → "PERSON_a3f8c21e"

• Deterministic: same input + same key = same token (join tables still work)
• Irreversible: can't recover "张三" from "PERSON_a3f8c21e" without the reverse map
• Isolated: different key = completely different tokens (multi-tenant safe)

The reverse map (token_maps) stays on your machine. The LLM never sees it.

Part of the Venus Protocol

venus-pii is the privacy layer of Venus — a white-box AI data processing engine.

The Venus philosophy: AI is a beautiful goddess, but she must have severed arms. Humans control what AI can touch, what it can see, and what it can do — through auditable, reversible, white-box constraints.

License

MIT