fix: Remove overly broad NRP and PERSON entities from default PII detection (#47)

[srivatsan0611]

Purpose of this PR

The NRP and PERSON PII entities use regex patterns that are way too broad and cause massive false positives in production. This especially breaks non-English language support and makes the pre-flight masking mode basically unusable.

Current broken behavior

// Input (Spanish text)
"crea un nuevo cliente con email [email protected]"

// Current output
"<NRP> <NRP> con email <EMAIL_ADDRESS>"

// Problem: "crea un" and "nuevo cliente" are incorrectly flagged as PII

Why these patterns are problematic

NRP pattern: /\b[A-Za-z]+ [A-Za-z]+\b/g

• Matches literally any two consecutive words
• Examples: "crea un", "nuevo cliente", "hello world", "the user"

PERSON pattern: /\b[A-Z][a-z]+ [A-Z][a-z]+\b/g

• Matches any two capitalized words
• Examples: "New York", "The User", "European Union", "United States"

Impact

• Breaks pre-flight masking for non-English content (Spanish, French, Italian, etc.)
• Masks legitimate text like city names, country names, and common phrases
• Makes default configuration unusable for international applications
• No documentation explaining what "NRP" means or its limitations

Solution

1. Remove from default entity list

Keep the patterns available but exclude them from defaults:

const DEFAULT_PII_ENTITIES = Object.values(PIIEntity).filter(
  (entity) => entity !== PIIEntity.NRP && entity !== PIIEntity.PERSON
);

This makes the default config actually usable while maintaining backward compatibility.

2. Add deprecation warnings

When users explicitly include these entities, show a clear warning:

console.warn(
  `[openai-guardrails-js] DEPRECATION WARNING: PIIEntity.${entity} has been removed from default entities due to high false positive rates.
  - This pattern causes false positives in normal conversation, especially in non-English languages.
  - Consider using more specific region-based patterns like SG_NRIC_FIN, UK_NINO, etc.
  - See: https://github.com/openai/openai-guardrails-js/issues/47`
);

The warning only shows once per entity per session to avoid log spam.

3. Update documentation

Added clear documentation explaining:

• Why these entities were removed from defaults
• Migration path for users who need similar functionality
• Region-specific alternatives (SG_NRIC_FIN, UK_NINO, FI_PERSONAL_IDENTITY_CODE, KR_RRN)
• Recommendation to use NER services for actual person name detection

Why this works long-term

Backward compatibility: No breaking changes. Users with explicit entity configurations continue to work exactly as before.

Better defaults: The default configuration now works for international applications without masking normal text.

Clear migration path: Users who actually need person name detection or national registration numbers have better alternatives:

• Use region-specific patterns (recommended)
• Use NER services like OpenAI API or spaCy (best accuracy)
• Explicitly opt-in to NRP/PERSON with warnings (if they accept false positives)

Prevents future issues: Documentation and warnings educate users upfront about the limitations.

Testing

All tests pass (27/27 including 8 new tests):

• Verify NRP and PERSON excluded from defaults
• Verify Spanish text no longer produces false positives
• Verify capitalized phrases like city names no longer masked
• Verify explicit opt-in still works with deprecation warning
• Verify warning deduplication
• All existing PII detection tests continue passing

Manual verification with examples from the issue

Test 1: Spanish text (from issue #47)
Input:  "crea un nuevo cliente con email [email protected]"
Output: "crea un nuevo cliente con email <EMAIL_ADDRESS>"
Result: PASS - only email masked

Test 2: Capitalized phrases (from issue #47)
Input:  "Welcome to New York, The User can access the system"
Output: "Welcome to New York, The User can access the system"
Result: PASS - no false positives

Test 3: Other PII still works
Input:  "Contact me at [email protected]"
Output: "Contact me at <EMAIL_ADDRESS>"
Result: PASS - email detection still works

Files changed

• src/checks/pii.ts - Core implementation with new defaults and deprecation warnings
• src/__tests__/unit/checks/pii.test.ts - Added 8 comprehensive tests
• docs/ref/checks/pii.md - Updated with migration guide

Closes #47

[srivatsan0611]

Hi @gabor-openai , please do review this PR if possible, I've been using OpenAI tools alot and I really appreciate the kind of work you all do in the Agentic Workspace. Do consider this a very humble contribution if possible :)

[gabor-openai]

@codex pls review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 👍

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR addresses a critical usability issue where overly broad regex patterns for NRP and PERSON entities caused massive false positives in PII detection, particularly breaking non-English language support and making pre-flight masking mode unusable in production environments.

Key Changes:

• Removed NRP and PERSON entities from default PII detection while keeping them available for explicit opt-in
• Added deprecation warnings when these entities are explicitly configured to educate users about their limitations
• Implemented comprehensive test coverage (8 new tests) to verify the fix and backward compatibility

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
src/checks/pii.ts	Core implementation: Created DEFAULT_PII_ENTITIES constant that filters out NRP and PERSON, added deprecation warning system with deduplication, integrated warnings into main pii function
src/__tests__/unit/checks/pii.test.ts	Added comprehensive test suite covering: default exclusion, Spanish text false positive prevention, capitalized phrase handling, explicit opt-in behavior, deprecation warnings, and warning deduplication
docs/ref/checks/pii.md	Added detailed deprecation notice explaining the issue, impact on production usage, migration paths to region-specific patterns or NER services, and reference to GitHub issue #47

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The deprecation warning message says "To suppress this warning, remove PIIEntity.${entity} from your entities configuration." This is misleading because removing the entity is exactly what the user should do to fix the issue, not just to suppress the warning.

Consider rephrasing to something like: "This warning will appear when ${entity} is explicitly included in your entities configuration." or simply remove this line since the warning naturally disappears when the entity is removed.

Suggested change

` - To suppress this warning, remove PIIEntity.${entity} from your entities configuration.\n` +

[srivatsan0611]

@steven10a - hey Steven! Thanks for taking a look, is this significant or does the original "suppress warning" message make more sense?

[steven10a]

@srivatsan0611 Thank you for the PR, we'll be merging it later today. I would say this Copilot comment is not significant and doesn't need to be addressed. I did just push a commit to short the message as I felt it was verbose but that was also [nitpick].

[srivatsan0611]

Yes, saw that, what you pushed made more sense lol.
Thanks for the merge @steven10a :)

[gabor-openai]

LGTM TY!