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', salt=42)
('员工P-83811，身份证ID-03292，电话138****5678',
 {'P-83811': '张三', 'ID-03292': '110101199003074610', '138****5678': '13812345678'})

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

text = "员工张三，身份证110101199003074610，电话13812345678"
redact(
    text,
    lang="zh",
    salt=42,
    unified_prefix="R",
    config={
        "phone": {"strategy": "remove"},   # mask types must opt in to participate
        "email": {"strategy": "remove"},
    },
)
# → "员工R-83811，身份证R-03292，电话R-68060"

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

78 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), and six of the other seven (en, ja, ko, de, uk, in) add regex + spaCy NER coverage — br is regex-only, with no NER adapter. 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 — all but br also ship a NER adapter — 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 (measured at v0.7.16 — Layer-1 detection has changed since; see benchmark-report for currency)

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.13", "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 pseudonym codes and masks (P-83811, 138****5678) — clear and reversible for audit, but the realistic surface is gone, which can break downstream LLM reasoning. 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:

The realistic strategy needs an explicit salt (salt=42 below keeps the output reproducible; use a real secret in production).

from argus_redact import redact_pseudonym_llm, restore

# Chinese
zh = redact_pseudonym_llm("请拨打 13912345678 联系王建国", lang="zh", salt=42)
zh.downstream_text  # "请拨打 19999946823 联系毕马温"    → LLM
zh.display_text     # "请拨打 19999946823ⓕ 联系毕马温ⓕ" → UI

# English
en = redact_pseudonym_llm("Call (415) 555-1234, SSN 123-45-6789", lang="en", salt=42)
en.downstream_text  # "Call (555) 555-0123, SSN 999-47-9373" → LLM
en.audit_text       # "Call PHON-68060, SSN SSN-54474"       → audit

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

# Round-trip works on any of the three forms, in any language.
# guard=False here: this restores the library's own output, not an LLM
# reply — see "Restoring LLM output safely" for the guarded path a real
# LLM round-trip needs.
print(restore(zh.downstream_text, zh.key, guard=False))
# expected: 请拨打 13912345678 联系王建国
print(restore(en.downstream_text, en.key, guard=False))
# expected: Call (415) 555-1234, SSN 123-45-6789
print(restore(mx.downstream_text, mx.key, guard=False))
# expected: 客户Wang at user@company.com

# 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