argus-redact

English · 中文说明

Encrypt PII, not meaning. Locally.

The privacy layer between you and AI. Your identity stays on your device — AI gets the meaning, not you.

Rated PRvL-Gold (default profile) on the project's own PRvL reference suite — see the spec for what it measures and the full per-profile matrix.

from argus_redact import redact

redacted, key = redact("张三的电话是13812345678，身份证号110101199003074610", names=["张三"], lang="zh", salt=42)
print(redacted)
# expected: P-83811的电话是138****5678，身份证号ID-03292

print(sorted(key.items()))
# expected: [('138****5678', '13812345678'), ('ID-03292', '110101199003074610'), ('P-83811', '张三')]

pip install argus-redact

Three Promises

Other tools shred your PII — it's gone forever. argus-redact encrypts it with a different key every time. ETH Zurich research shows LLMs can deanonymize users for $1-4/person when pseudonyms are fixed. We generate fresh random keys per call — the cloud sees unrelated pseudonyms every time.

Default redaction output

redact() emits per-type pseudonym codes, not Chinese label literals:

>>> redact("员工张三，身份证110101199003074610，电话13812345678", mode='fast', lang='zh')
('员工P-83811，身份证ID-89732，电话138****5678',
 {'P-83811': '张三', 'ID-89732': '110101199003074610', '138****5678': '13812345678'})

To unify all reversible types under one prefix (hides PII type from the LLM):

redact(
    text,
    unified_prefix="R",
    config={
        "phone": {"strategy": "remove"},   # mask types must opt in to participate
        "email": {"strategy": "remove"},
    },
)
# → "员工R-83811，身份证R-89732，电话R-12345"

<TYPE_N> 1-based sequential token style is on the future-release candidate list (no committed timeline). See docs/configuration.md for the current strategy reference.

Privacy Levels

argus-redact evaluates your text from your perspective, not a regulator's:

🟢 Safe      — nothing about you is exposed
🟡 Caution   — contains personal info, not dangerous alone
🟠 Danger    — can narrow down to you specifically
🔴 Exposed   — directly identifies you

from argus_redact import redact

report = redact("身份证110101199003074610，手机13812345678，确诊糖尿病", report=True)
report.risk.level    # "critical"
report.risk.score    # 1.0
report.risk.reasons  # ("id_number (critical)", "phone (high)", "medical (critical)", ...)

This is what compliance frameworks don't tell you: how dangerous is it to share this specific text with AI?

Three Layers, Collaborative

Layer 1  Rust+Regex   phone, ID, bank card, email, self-reference, ...    <0.2ms
             │
         produce_hints() → text_intent, pii_density, self_reference_tier
             │
Layer 2  NER ← hints   locations, organizations, standalone names         10-100ms
Layer 3  Local LLM      implicit PII — symptoms→disease, behavior→belief  ~20s

Layers are not independent — L1 passes hints to L2, enabling collaborative detection. Instruction text ("帮我看看这段代码") skips NER entirely. High PII density lowers NER thresholds. Cross-layer agreement boosts confidence.

Unicode-hardened: NFKC normalization, zero-width stripping, Cyrillic/Greek confusable defense, Chinese digit detection (一三八零零一三八零零零 → detected as phone).

Core engine (regex matching, entity merging, restore, pseudonym generation) is written in Rust via PyO3 for maximum performance. Python handles orchestration, NER models, and LLM integration.

60+ PII types across 3 layers — from phone numbers to medical diagnoses, religious beliefs, political opinions. Default is mode="fast" (Layer 1 only, zero deps, sub-ms). Opt in: mode="ner" (+ NER models) → mode="auto" (all three layers).

Telemetry: ARGUS_PERF_LOG=perf.jsonl for per-call timing breakdown. Details →

Deployment fit — modes have very different latency budgets; pick by where you sit in the request path:

Don't put auto in front of an interactive LLM call. Use fast inline + auto in a parallel audit lane.

Limitations & When NOT to Rely on This

argus-redact is a PII data minimization aid, not an anonymization or compliance certification:

• L1 fast (regex) matches well-defined formats. Novel or obfuscated variants, cross-field inference attacks pass through.

• L2 NER is statistical inference; out-of-distribution text (informal, typo-heavy, minority names) has higher miss rate. See benchmark results for measured numbers.

• No guarantee against adversarial inputs — attackers can craft text that evades detection.

• Removing explicit PII ≠ anonymity. LLM agents can re-identify individuals by combining residual, individually-non-identifying cues with public data — even on redacted text, even during benign tasks (Ko et al. 2026). Reversible substitution protects explicit identifiers and preserves LLM utility; it does not defend against inference-based re-identification, which a per-document redactor cannot fully prevent — the residual comes from combinations of quasi-identifiers, not single fields (why coarsening one field doesn't fix it; and why detecting more English quasi-identifiers didn't reduce re-id either).

• Not a GDPR / PIPL anonymization framework — anonymization is a compliance process decision, not a single-library output.

• Restore is a substitution pass, not an authorization check. An unguarded restore (guard=False) substitutes originals into any text carrying the right pseudonyms — including a reply an attacker steered the model into producing. As of v0.8.0 the default is guard=True, which fails closed without a valid anchor; use the guarded round-trip to bind a restore to the exchange that produced the key.

When to use argus-redact: reversible pseudonymization for LLM pipelines where you need redact() → LLM → guarded_restore() with zero PII crossing the network boundary.

When to consider alternatives: if you need one-way English PII masking with a single model call, OpenAI Privacy Filter and similar model-based maskers may fit better. argus-redact's strongest suit is reversible pseudonymization with per-message keys; Chinese has the deepest support (HanLP + native validators), the other 7 languages have regex + spaCy NER coverage. Pick by the workload, not by exclusivity.

Combine argus-redact with audit logging, rate limiting, and upstream policy — no single layer is sufficient.

8 Languages

Mix freely: lang=["zh", "en", "de"]. Pass known names: names=["王一", "张三"].

Benchmark scope: only zh and en have committed recall benchmarks. The other six packs (de, uk, br, in, ja, ko) ship L1 patterns + NER adapters but have no measured recall — treat them as best-effort and reach them with an explicit lang="…". They are not auto-selected under lang="auto", whose script-only detection resolves all Latin-script text to en. See language-packs.md.

Performance

Rust core (PyO3), mode="fast" — redact() p50 over 500 iterations, Apple M1 Max, Python 3.11. Reproduce with python tests/benchmark/perf_profile.py:

Throughput depends heavily on document size and language, so the workload sizes are stated rather than a single headline number. Committed run: perf_profile_0.7.16.json.

Pre-built wheels for all major platforms — no Rust toolchain needed to install:

✓ Linux x86_64 (glibc + musl/Alpine)
✓ Linux aarch64 (Raspberry Pi + Alpine ARM)
✓ macOS (Apple Silicon + Intel)
✓ Windows x64
× Python 3.10 / 3.11 / 3.12 / 3.13

Detection accuracy

ai4privacy en, 500 samples, v0.7.16 run (tests/benchmark/results/ai4privacy_0.7.16.json). auto mode skipped on the maintainer's hardware — see benchmark-report.md for full matrix + reproduction commands.

For context: fast mode is high-precision / low-recall by design — it only emits formats it can validate (Luhn, MOD11-2, etc.). Recall comes from ner and auto at the cost of latency. Pick the mode for your deployment shape (see Deployment fit above). Full benchmarks → | Performance →

North Star

Risk Assessment

# Assess risk before sending to AI
report = redact(text, report=True)
report.risk.level         # "critical"
report.risk.pipl_articles # ("PIPL Art.28", "PIPL Art.51", ...)
report.entities           # detected PII details
report.stats              # per-layer timing

# CLI
argus-redact assess <<< "身份证110101199003074610"

Compliance profiles: redact(text, profile="pipl") / "gdpr" / "hipaa". These are strategy-override presets, not coverage guarantees — they change how detected types are redacted, not which types are detected, and don't by themselves make a pipeline compliant. Details → Type filtering: redact(text, types=["phone", "id_number"]) / types_exclude=["address"].

Realistic Redaction (pseudonym-llm profile)

Default redaction emits placeholder labels ([TEL-79329], P-164) — clear for audit, but breaks downstream LLM reasoning because the message structure is gone. The pseudonym-llm profile replaces PII with realistic-looking but reserved-range fake values (e.g., 19999... mobile, 999... ID, 999999... bank card). LLMs reason correctly; humans can still tell it's synthetic if they know the convention.

Each call returns three text forms sharing one key dict:

from argus_redact import redact_pseudonym_llm, restore

# Chinese
zh = redact_pseudonym_llm("请拨打 13912345678 联系王建国", lang="zh")
zh.downstream_text  # "请拨打 19999123456 联系张明"           → LLM
zh.display_text     # "请拨打 19999123456ⓕ 联系张明ⓕ"        → UI

# English
en = redact_pseudonym_llm("Call (415) 555-1234, SSN 123-45-6789", lang="en")
en.downstream_text  # "Call (555) 555-0142, SSN 999-37-2811" → LLM
en.audit_text       # "Call [PHONE-23801], SSN [SSN-15772]"  → audit

# Mixed (auto-detect)
mx = redact_pseudonym_llm("客户Wang at user@company.com", lang="auto")

# Round-trip works on any of the three forms, in any language
restore(zh.downstream_text, zh.key)   # → original
restore(en.downstream_text, en.key)   # → original
restore(mx.downstream_text, mx.key)   # → original

# CLI emits all three forms as JSON
echo "Call (415) 555-1234" | \
  argus-redact redact -k key.json --profile pseudonym-llm -l en | \
  jq .downstream_text
# "Call (555) 555-0142"

Reserved ranges:

• zh: 199-99-XXXXXX mobile (sub-segment unassigned by 工信部), 099- landline (no such area code), 999XXX ID address code (GB/T 2260 unassigned), 999999 bank BIN (银联 unassigned), 滨海市 fictional city.
• en: (555) 555-01XX phone (FCC permanent fictional reservation), 999-XX-XXXX SSN (SSA never assigns 9XX), 999999 credit card BIN, John Doe / Jane Roe person, 1313 Mockingbird Lane address.
• shared (RFC): example.com / .org / .net email (RFC 2606), 192.0.2.0/24 / 198.51.100.0/24 / 203.0.113.0/24 IPv4 (RFC 5737), 2001:db8::/32 IPv6 (RFC 3849), 00:00:5E:00:53:xx MAC (RFC 7042).

Argus Gateway integration: response headers should include X-Argus-Redact-Profile: pseudonym-llm; UI clients render display_text, LLM clients consume downstream_text. Storage of downstream_text as business truth is unsafe — it's synthetic by design.

Real users named like canonical fakes (e.g., a real customer named 张三 or John Doe): pass reserved_names={"person_zh": ()} (or person_en) to disable that locale's canonical-name pollution detection so the real user's name flows through normal redaction.

Streaming

For chat sessions or long-form input where text arrives in chunks, use StreamingRedactor (input side) and StreamingRestorer (output side). Both require complete logical units per chunk (sentence / paragraph / turn) — entities split across chunk boundaries are not handled.

from argus_redact.streaming import StreamingRedactor, StreamingRestorer

# Input side: redact each chunk; same original value across chunks → same fake
r = StreamingRedactor(salt=b"my-secret-salt", lang="zh")
for chunk in input_stream:                  # one sentence/paragraph/turn each
    res = r.feed(chunk)
    send_to_llm(res.downstream_text)

# Output side: restore LLM output stream at sentence boundaries
restorer = StreamingRestorer(r.aggregate_key())
for chunk in llm_output_stream:
    restored = restorer.feed(chunk)
    if restored:
        print(restored, end="")
print(restorer.flush(), end="")

True byte-level streaming (entities crossing chunk boundaries) needs full incremental detection and is roadmapped for a later release.

⚠️ Realistic-mode output must not be re-redacted (it would corrupt the key dict). redact_pseudonym_llm will raise PseudonymPollutionError if called on already-faked input — call restore() first.

Full API → · Design constraints →

Integrations

Security

PII never leaves your device. Per-message keys prevent cross-request profiling. Full security model →

Guarded round-trip. guarded_restore() binds a restore to the exchange that produced the key. Two deterministic checks: the reply must echo a per-call nonce (provenance), and only the pseudonyms this call emitted are substituted (scope). Both fail closed — pseudonyms are returned unchanged, with a SecurityWarning, rather than PII being substituted into an attacker-shaped reply. A supplementary injection heuristic is advisory by default.

from argus_redact import redact, guarded_restore, make_anchor
from argus_redact.compose import prompt_anchor

redacted, key = redact("张三的电话是13812345678", names=["张三"], lang="zh")
anchor = make_anchor(key)          # per-call nonce + the pseudonym scope of this call

system = prompt_anchor(key, lang="zh", anchor=anchor)   # asks the model to echo the nonce
reply = call_llm(redacted, system=system)

restored = guarded_restore(reply, key, redacted=redacted, anchor=anchor)
# strict=True raises RestoreGuardError instead of returning un-restored text

As of v0.8.0, restore(text, key) defaults to guard=True and fails closed without a valid anchor; pass guard=False for the legacy unguarded substitution, or use the guarded round-trip with an anchor. Guarded restore →

Provides the local de-identification layer that PIPL cross-border transfer, GDPR Art.25 data minimization, and HIPAA de-identification workflows call for — a technical control, not a certification. Details →

Documentation

Contributing

CONTRIBUTING.md — language packs, test scenarios, framework integrations welcome.

Contributors

License

Apache 2.0