presidio recognizers.instructions.md

Recognizer changes

Rules for adding or modifying PII recognizers. When reviewing, lead with the highest-impact gaps in this order:

1. Pattern accuracy. The pattern is as specific as the format allows, the score is calibrated to the pattern alone, the context words are the right ones, the checksum is correct where one exists (and none is invented where it doesn't — validate_result must not promote weak matches to 1.0), and the logic's source is documented, preferably an official specification.
2. Proper testing. A configuration-path test through RecognizerRegistryProvider (the load-bearing rule below), exact-score assertions rather than ranges, a lookalike negative, and context-enhancement coverage.
3. Construction paths that disagree (direct vs. add_recognizer() vs. YAML).
4. Changes to an existing recognizer's patterns, scores, or context made as a side effect of adding a new one — users depend on current detection behavior.
5. Language/country-code mismatch; missing exports, YAML entry, or docs row.

Give specific, actionable feedback: cite the file and line and propose the concrete fix. Do not comment on formatting — Ruff and CI own that.

The load-bearing rule: test the configuration path

Most predefined recognizers ship enabled: false, so the default test run never constructs them from configuration. Users, however, reach them exactly one way: flipping enabled: true in a registry YAML. A recognizer that works when built in Python can still be unreachable — or crash — when enabled in YAML.

Every new or changed recognizer needs at least one test that loads it through RecognizerRegistryProvider and asserts detection:

def test_recognizer_loads_and_detects_when_enabled_in_yaml(tmp_path):
    """Detection must work through the path users actually configure."""
    conf = tmp_path / "recognizers.yaml"
    conf.write_text(
        """
supported_languages:
  - en
recognizers:
  - name: MyRecognizer
    supported_languages:
      - en
    type: predefined
    enabled: true
    country_code: us
"""
    )
    registry = RecognizerRegistryProvider(conf_file=conf).create_recognizer_registry()
    analyzer = AnalyzerEngine(registry=registry, nlp_engine=nlp_engine)

    results = analyzer.analyze("Member ID ABC123456", language="en")

    assert [result.entity_type for result in results] == ["MY_ENTITY"]