Imported from Protocol-Wealth/pw-redact (AGENTS.md). Install upstream with npx skills add Protocol-Wealth/pw-redact. Copyright stays with the author.

AGENTS.md — pw-redact

Instructions for AI coding assistants working in this repository.

What This Repo Is

pw-redact is an open-source PII redaction engine for financial services AI pipelines. It strips personally identifiable information from financial text (meeting transcripts, tax notes, mortgage documents) before it reaches AI models, while preserving dollar amounts, percentages, tax brackets, and financial acronyms.

Stack: Python 3.12 · FastAPI · Presidio · spaCy · Fly.io License: MIT Deployment: Configure via fly.toml (not committed)

Key Files

Commands

# Install
pip install -e ".[dev]" && python -m spacy download en_core_web_lg

# Test
pytest tests/ -v

# Lint
ruff check src/

# Run locally
uvicorn pw_redact.main:app --port 8080

# Deploy
fly deploy -a pw-redact --remote-only

Rules

1. No real PII. Test fixtures use synthetic data only. Never include real names, SSNs, addresses, or client data.
2. MIT license header on every new .py file:

   # Copyright 2026 Protocol Wealth LLC
   # Licensed under the MIT License
   # https://github.com/Protocol-Wealth/pw-redact

3. Every new regex pattern needs 3+ test cases (match, non-match, extracted text).
4. Financial data must survive. Verify allow-list doesn't conflict when adding patterns.
5. Security matters. This sits at the chokepoint of an AI pipeline processing SEC-regulated data. Use hmac.compare_digest() for secrets, validate all external input, use possessive quantifiers in regex to prevent ReDoS.
6. This is a public repo. No internal URLs, no vendor-specific references, no PW business logic.
7. Run tests before committing. All 332 tests must pass. Lint + format must pass. Coverage must stay above 85%.

Architecture

Request → Rate Limiter → Content-Length Guard → Input Validator
  → Injection Detector → Unicode Normalization
  → Layer 1 (Regex) + Layer 2 (Presidio NLP) → Merge/Dedup
  → Layer 3 (Financial Recognizers) → Layer 4 (Allow-List)
  → Placeholder Generation → Output Validator → Response

Adding New Patterns

See CONTRIBUTING.md for detailed instructions.

Quick version:

1. Add _PatternDef to regex_patterns.py (with score and optional group)
2. Add tests in test_regex_patterns.py
3. Verify allow-list compatibility
4. Update README.md "Supported Entity Types" table
5. Run pytest tests/ -v

Document Contexts

Related Documentation

• CLAUDE.md — Detailed build specification and internal notes
• docs/architecture.md — Pipeline deep dive
• docs/deployment.md — Deployment guide
• docs/allow-list-guide.md — Allow-list customization
• SECURITY.md — Vulnerability reporting