[Feature] add Korean Foreigner Registration Number recognizer (#1825)

* add frn recognizer

* make copilot happy

---------

Co-authored-by: Sharon Hart <sharonh.dev@gmail.com>

Author: RektPunk

docs/supported_entities.md

@@ -99,10 +99,12 @@ For more information, refer to the [adding new recognizers documentation](analyz
 ### Korea
 | FieldType  | Description                                                                                             | Detection Method                         |
 |------------|---------------------------------------------------------------------------------------------------------|------------------------------------------|
-| KR_BRN     | The Korean Business Registration Number (BRN) is a 10-digit number assigned to business entities for taxation purposes. | Pattern match, context and custom logic. |
-| KR_RRN     | The Korean Resident Registration Number (RRN) is a 13-digit number issued to all Korean residents. | Pattern match, context and custom logic. |
 | KR_DRIVER_LICENSE    |  The Korean driver license number is a 12-digit number. | Pattern match, context and custom logic. |
+| KR_FRN     | The Korean Foreigner Registration Number (FRN) is a 13-digit number. | Pattern match, context and custom logic. |
 | KR_PASSPORT| The Korean Passport Number  | Pattern match, context. |
+| KR_BRN     | The Korean Business Registration Number (BRN) is a 10-digit number assigned to business entities for taxation purposes. | Pattern match, context and custom logic. |
+| KR_RRN     | The Korean Resident Registration Number (RRN) is a 13-digit number issued to all Korean residents. | Pattern match, context and custom logic. |
+
 
 ### Thai
 | FieldType  | Description                                                                                             | Detection Method                         |

presidio-analyzer/presidio_analyzer/conf/default_recognizers.yaml

@@ -175,6 +175,13 @@ recognizers:
     type: predefined
     enabled: false
 
+  - name: KrFrnRecognizer
+    supported_languages: 
+    - ko
+    - kr
+    type: predefined
+    enabled: false
+
   - name: ThTninRecognizer
     supported_languages:
     - th

presidio-analyzer/presidio_analyzer/predefined_recognizers/__init__.py

@@ -39,6 +39,7 @@
 from .country_specific.korea.kr_driver_license_recognizer import (
     KrDriverLicenseRecognizer,
 )
+from .country_specific.korea.kr_frn_recognizer import KrFrnRecognizer
 from .country_specific.korea.kr_passport_recognizer import KrPassportRecognizer
 from .country_specific.korea.kr_rrn_recognizer import KrRrnRecognizer
 
@@ -162,6 +163,7 @@
     "KrBrnRecognizer",
     "KrRrnRecognizer",
     "KrDriverLicenseRecognizer",
+    "KrFrnRecognizer",
     "ThTninRecognizer",
     "LangExtractRecognizer",
     "AzureOpenAILangExtractRecognizer",

presidio-analyzer/presidio_analyzer/predefined_recognizers/country_specific/korea/__init__.py

@@ -2,10 +2,14 @@
 
 from .kr_brn_recognizer import KrBrnRecognizer
 from .kr_driver_license_recognizer import KrDriverLicenseRecognizer
+from .kr_frn_recognizer import KrFrnRecognizer
 from .kr_passport_recognizer import KrPassportRecognizer
 from .kr_rrn_recognizer import KrRrnRecognizer
 
 __all__ = [
+    "KrDriverLicenseRecognizer",
+    "KrPassportRecognizer",
+    "KrFrnRecognizer",
     "KrBrnRecognizer",
     "KrDriverLicenseRecognizer",
     "KrPassportRecognizer",

presidio-analyzer/presidio_analyzer/predefined_recognizers/country_specific/korea/kr_frn_recognizer.py

@@ -0,0 +1,88 @@
+from typing import List, Optional, Tuple
+
+from presidio_analyzer import Pattern
+from presidio_analyzer.predefined_recognizers.country_specific.korea.kr_rrn_recognizer import (  # noqa: E501
+    KrRrnRecognizer,
+)
+
+
+class KrFrnRecognizer(KrRrnRecognizer):
+    """
+    Recognize Korean Foreigner Registration Number (FRN).
+
+    The Korean FRN is a 13-digit number issued to registered foreigners in Korea.
+    The format is YYMMDD-GHIJKLX where:
+    - YYMMDD represents the birth date.
+    - G determines gender and century (5-8).
+        - 5: Male, 1900-1999 birth
+        - 6: Female, 1900-1999 birth
+        - 7: Male, 2000-2099 birth
+        - 8: Female, 2000-2099 birth
+        - (Note: 9 and 0 are sometimes used for 1800s birth, but rare)
+
+    For FRNs issued before October 2020:
+    - HIJKL is a serial number assigned by district
+    - X is a check digit calculated using the preceding 12 digits
+
+    For FRNs issued after October 2020:
+    - HIJKLX is a random number
+
+    Reference: https://en.wikipedia.org/wiki/Resident_registration_number
+
+    :param patterns: List of patterns to be used by this recognizer
+    :param context: List of context words to increase confidence in detection
+    :param supported_language: Language this recognizer supports
+    :param supported_entity: The entity this recognizer can detect
+    :param replacement_pairs: List of tuples with potential replacement values
+    for different strings to be used during pattern matching.
+    This can allow a greater variety in input, for example by removing dashes.
+    """
+
+    PATTERNS = [
+        Pattern(
+            "FRN (Medium)",
+            r"(?<!\d)\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])(-?)[5-8]\d{6}(?!\d)",
+            0.5,
+        )
+    ]
+
+    CONTEXT = [
+        "외국인등록번호",
+        "Korean FRN",
+        "FRN",
+        "Foreigner Registration Number",
+        "Korean Foreigner Registration Number",
+        "외국인번호",
+    ]
+
+    def __init__(
+        self,
+        patterns: Optional[List[Pattern]] = None,
+        context: Optional[List[str]] = None,
+        supported_language: str = "ko",
+        supported_entity: str = "KR_FRN",
+        replacement_pairs: Optional[List[Tuple[str, str]]] = None,
+        name: Optional[str] = None,
+    ):
+        super().__init__(
+            patterns=patterns if patterns else self.PATTERNS,
+            context=context if context else self.CONTEXT,
+            supported_language=supported_language,
+            supported_entity=supported_entity,
+            replacement_pairs=replacement_pairs,
+            name=name,
+        )
+
+    def _validate_checksum(self, frn: str) -> bool:
+        """
+        Validate the checksum of Korean FRN.
+
+        The checksum is calculated using the preceding 12 digits.
+        X = (13 - (2A+3B+4C+5D+6E+7F+8G+9H+2I+3J+4K+5L) mod 11) mod 10
+
+        :param frn: The FRN to validate
+        :return: True if checksum is valid, False otherwise
+        """
+        digit_sum = super()._compute_checksum(frn)
+        checksum = (13 - (digit_sum % 11)) % 10
+        return checksum == int(frn[12])

presidio-analyzer/presidio_analyzer/predefined_recognizers/country_specific/korea/kr_rrn_recognizer.py

@@ -1,4 +1,4 @@
-from typing import List, Optional, Tuple, Union
+from typing import List, Optional, Tuple
 
 from presidio_analyzer import EntityRecognizer, Pattern, PatternRecognizer
 
@@ -70,7 +70,7 @@ def __init__(
             name=name,
         )
 
-    def validate_result(self, pattern_text: str) -> Union[bool, None]:
+    def validate_result(self, pattern_text: str) -> Optional[bool]:
         """
         Validate the pattern logic e.g., by running checksum on a detected pattern.
 
@@ -112,6 +112,20 @@ def _validate_region_code(self, region_code: int) -> bool:
         """
         return True if 0 <= region_code <= 95 else False
 
+    def _compute_checksum(self, rn: str) -> int:
+        """
+        Compute the weighted digit sum used for the RRN checksum calculation.
+
+        The sum is calculated over the first 12 digits of the RRN using
+        the weights [2, 3, 4, 5, 6, 7, 8, 9, 2, 3, 4, 5].
+
+        :param rn: The resident registration number as a string.
+            Only the first 12 digits are used in the computation.
+        :return: The integer sum of the products of digits and weights.
+        """
+        weights = [2, 3, 4, 5, 6, 7, 8, 9, 2, 3, 4, 5]
+        return sum(int(rn[i]) * weights[i] for i in range(12))
+
     def _validate_checksum(self, rrn: str) -> bool:
         """
         Validate the checksum of Korean RRN.
@@ -122,21 +136,6 @@ def _validate_checksum(self, rrn: str) -> bool:
         :param rrn: The RRN to validate
         :return: True if checksum is valid, False otherwise
         """
-
-        digit_sum = (
-            2 * int(rrn[0])
-            + 3 * int(rrn[1])
-            + 4 * int(rrn[2])
-            + 5 * int(rrn[3])
-            + 6 * int(rrn[4])
-            + 7 * int(rrn[5])
-            + 8 * int(rrn[6])
-            + 9 * int(rrn[7])
-            + 2 * int(rrn[8])
-            + 3 * int(rrn[9])
-            + 4 * int(rrn[10])
-            + 5 * int(rrn[11])
-        )
+        digit_sum = self._compute_checksum(rrn)
         checksum = (11 - (digit_sum % 11)) % 10
-
         return checksum == int(rrn[12])

presidio-analyzer/tests/test_kr_frn_recognizer.py

@@ -0,0 +1,60 @@
+import pytest
+
+from tests import assert_result_within_score_range
+from presidio_analyzer.predefined_recognizers.country_specific.korea.kr_frn_recognizer import KrFrnRecognizer
+
+@pytest.fixture(scope="module")
+def recognizer():
+    return KrFrnRecognizer()
+
+@pytest.fixture(scope="module")
+def entities():
+    return ["KR_FRN"]
+
+@pytest.mark.parametrize(
+    "text, expected_len, expected_positions, expected_score_ranges",
+    [
+        # Valid FRNs, but medium match
+        ("911124-5678901", 1, ((0, 14),), ((0.5, 0.5),), ),
+        ("9111245678901", 1, ((0, 13),), ((0.5, 0.5),), ),
+        ("000505-7637892", 1, ((0, 14),), ((0.5, 0.5),), ),
+        ("0005056637892", 1, ((0, 13),), ((0.5, 0.5),), ),
+        ("His Korean FRN is 911124-5678901", 1, ((18, 32),), ((0.5, 0.5),), ),
+
+        # Valid FRNs, strong match by validate_result()
+        ("911124-5678906", 1, ((0, 14),), ((1.0, 1.0),), ),
+        ("9111245678906", 1, ((0, 13),), ((1.0, 1.0),), ),
+        ("050912-6000012", 1, ((0, 14),), ((1.0, 1.0),), ),
+        ("0509126000012", 1, ((0, 13),), ((1.0, 1.0),), ),
+        ("His FRN is 9111245678906", 1, ((11, 24),), ((1.0, 1.0),), ),
+
+        # Invalid FRNs 
+        ("001332-1234567", 0, (), (),),
+        ("0013321234567", 0, (), (),),
+        ("960121+1021413", 0, (), (),),
+        ("960111-10214131", 0, (), (),),
+        ("960303-0021413", 0, (), (),),
+        ("760413-1212134", 0, (), (),),
+        ("000402-2214431", 0, (), (),),
+        ("051102-9234110", 0, (), (),),
+    ],
+)
+def test_when_all_frns_then_succeed(
+    text,
+    expected_len,
+    expected_positions,
+    expected_score_ranges,
+    recognizer,
+    entities,
+    max_score,
+):
+    results = recognizer.analyze(text, entities)
+    assert len(results) == expected_len
+    for res, (st_pos, fn_pos), (st_score, fn_score) in zip(
+        results, expected_positions, expected_score_ranges
+    ):
+        if fn_score == "max":
+            fn_score = max_score
+        assert_result_within_score_range(
+            res, entities[0], st_pos, fn_pos, st_score, fn_score
+        )