Redact PII from LLM prompts and logs

Agent PII Redactor cleans prompts, support transcripts, incident notes and LLM logs before they leave a private workspace. It detects common personal data and high-risk tokens locally, replaces them with stable placeholders, and writes a JSON report that an operator can audit.

This pack is for teams that already use LLMs in support, ops, product research or engineering triage and need a repeatable pre-flight sanitizer. It does not claim perfect legal compliance, identity proofing or DLP coverage. It is a practical guardrail: deterministic first, LLM review optional.

What It Catches

• Email addresses
• Phone-like numbers
• US SSN patterns
• Luhn-valid payment cards
• Bearer tokens and API-key-shaped secrets
• Private/local IPv4 addresses
• 12-word recovery-phrase-shaped text

Quick Start

cd agent-pii-redactor-v1
python3 agent.py --help
python3 agent.py init-sample --dir examples
python3 agent.py redact --deterministic \
  --input examples/sample_prompt.txt \
  --policy examples/policy.example.json \
  --out out/redacted.json
python3 agent.py status --report out/redacted.json

Install on a Debian or Ubuntu VM:

sudo bash install.sh

Run without installing a service:

bash install.sh --no-service
venv/bin/python agent.py run --once --deterministic

How It Works

input prompt/log
      |
      v
+-------------------+
| deterministic scan |
+-------------------+
      |
      v
+-------------------+      optional BYO-LLM
| redaction engine   |----> review redacted report only
+-------------------+
      |
      v
JSON report + redacted_text

The optional LLM review uses your local Claude Code, Kimi Code or Codex CLI through llm_adapter.py. The LLM is never required and the raw input text is not sent to the LLM reviewer. Only the redacted preview and structured findings are passed along.

Outputs

The report contains:

• summary: counts by detector kind and whether redaction was applied.
• redacted_text: safe text with placeholders such as [EMAIL_1].
• findings: kind, placeholder, offset and reason.
• llm_review: optional reviewer output or deterministic fallback status.

Customization

Edit examples/policy.example.json or pass --policy /path/to/policy.json.

{
  "allowlist": ["example.org", "support@your-company.test"],
  "disabled_kinds": []
}

Use the allowlist for values that are safe in your workflow. Disable a detector only when the downstream process accepts that risk.

Use a local model (Ollama)

The optional LLM step can also run on your own machine through Ollama, so no text leaves your server. No account and no API key.

ollama pull <model>               # any chat model you like
export PACK_LLM=ollama            # prefer Ollama even if a coding-agent CLI is installed
export PACK_OLLAMA_MODEL=<model>  # optional: default is the first chat model the server lists
python3 -c "import llm_adapter; print(llm_adapter.detect())"   # prints: ollama

• PACK_OLLAMA_HOST points to another server (default http://127.0.0.1:11434); OLLAMA_HOST is also read when PACK_LLM=ollama.
• PACK_OLLAMA_NUM_CTX sets the context size if your reports or prompts are long.
• Without PACK_LLM, a local Ollama server is used only when no Claude Code, Kimi Code or Codex CLI is found.
• If the server is down or the model is missing, the pack keeps working in its deterministic mode.

Learning memory (local and private)

Every LLM call this pack makes is journaled in ./.pack_memory/ next to the code, so the pack can improve for you. Nothing is ever sent anywhere.

• What is kept: the task name, the masked input, the masked answer, status and latency. Keys, tokens, e-mails, phone numbers, IP addresses, card and IBAN numbers and personal paths are masked before writing; the system prompt is never stored.
• Teach it: python3 pack_memory.py feedback last ok confirms a result, python3 pack_memory.py feedback last bad --fix "the right answer" corrects it. Confirmed and corrected runs are reused as validated examples when a similar input comes in. Unrated runs are never injected into a prompt.
• Find similar cases: python3 pack_memory.py similar "some text" and python3 pack_memory.py clusters (groups of near-identical failures) work in plain Python, no model needed. Optional meaning-based matching uses an embedding model you already run locally: python3 pack_memory.py enable-semantic (Ollama on this machine only).
• Share, only if you want: python3 pack_memory.py export writes an anonymised summary (counts, statuses, size buckets, no text) for you to review.
• Control: PACK_MEMORY=0 turns it off, PACK_MEMORY_STORE_TEXT=0 keeps fingerprints only, python3 pack_memory.py purge --yes wipes it.