euredact 0.3.3__tar.gz → 0.3.4__tar.gz

{euredact-0.3.3 → euredact-0.3.4}/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## 0.3.4 (2026-07-30)
+
+### Fixed
+
+- **Recovered the latency 0.3.3 gave away, without giving back its recall.**
+  0.3.3 made `\b` catch identifiers glued to a non-ASCII letter by rewriting it
+  to a three-branch lookaround union on all 303 patterns. Correct, but it cost
+  **1.8× on short records and 2.8× on real documents**, and its ASCII branch
+  manufactured boundaries *inside* words at non-ASCII letters — truncating
+  `@Ciarán` to `@Ciar` and typing `FICIAIRES`, a fragment of `BÉNÉFICIAIRES`,
+  as a national ID.
+
+  The boundary is now chosen per occurrence. Next to a digit, the ASCII reading
+  alone is *exactly* the union — a Unicode letter is never an ASCII word
+  character, so the ASCII branch already succeeds everywhere the Unicode branch
+  does — and one lookaround replaces the alternation. Everywhere else plain `\b`
+  stays, which is what a Greek e-mail local part needs.
+
+  | | 186 chars | 3,424 chars |
+  |---|---:|---:|
+  | pure Python | 3.0 ms → **907 µs** | 58 ms → **13.6 ms** |
+  | with `pyahocorasick` | 2.3 ms → **775 µs** | 42 ms → **10.9 ms** |
+  | with `[fast]` | 878 µs → **516 µs** | 14.4 ms → **5.3 ms** |
+
+  Within 4% of the pre-0.3.3 baseline, with all five glued-identifier cases and
+  both Unicode e-mail cases still detected. Per-type precision, recall and F1
+  are **byte-identical** across all 152,300 corpus documents.
+
+- **Social handles containing a non-ASCII letter were masked only up to it.**
+  `@Ciarán` came back as `@Ciar`, leaving `án` in the clear, because the pattern's
+  character class was ASCII-only and the old boundary let the match stop mid-word.
+  The class is now Unicode-aware, so the whole handle is masked. The TypeScript
+  SDK already had this right; the two now agree.
+
+- **German social-security numbers were unredacted whenever the document used
+  the abbreviation `SVNR`.** The pattern and its context gate were both correct;
+  the cue list simply had `SV-Nummer` and `Sozialversicherung` and not the short
+  form people actually type.
+
+  Measured across all 152,300 corpus documents, this was **every** German
+  social-security number the rule missed — 204 of them, in the clear:
+
+  | | recall before | after |
+  |---|---:|---:|
+  | `SOCIAL_SECURITY`, country hints | 84.16% | **100.00%** |
+  | `SOCIAL_SECURITY`, blind | 83.77% | **99.61%** |
+
+  No false-positive cost: 0 before, 0 after, and no other entity type moved.
+  `SV-Nr` and `RVNR` are added alongside it — the same gap for the other two
+  spellings, and the health-insurance rule already carries `KVNR` next to
+  `KV-Nummer` for exactly this reason.
+
+  Found by per-type measurement rather than a report. `SOCIAL_SECURITY` was the
+  only type below 90% recall that was not a known cloud-tier case, which is
+  what made it worth chasing.
+
+### Added
+
+- **`tests/metrics.py`** — per-entity-type precision, recall, F1 and
+  false-positive counts over the corpus, both detection modes, with `--csv`.
+  `eval_full.py` renders an HTML report; this is the plain-text counterpart with
+  its matching rules stated in the module docstring, so a figure quoted from it
+  can be reproduced and argued with.
+
+  Writing it surfaced two flaws in the shared evaluation config, both of which
+  had been quietly distorting published numbers:
+
+  - `HEALTH_ID` had no entry in `CATEGORY_MAP`, so its 252 labels could never be
+    matched — counted as 252 misses *and* charging the engine's correct
+    `HEALTH_INSURANCE` detections as 252 false positives. `SECRET` was also
+    unmapped and worked only by accident, its fallback happening to be a real
+    entity type. Both are mapped now, which slightly raises measured recall.
+  - False positives were attributed to a category that may carry no labels at
+    all: every `BIC` detection was charged to a zero-support `BIC` row while the
+    corpus labels them `SWIFT_BIC`, splitting one type's precision across two
+    rows and reporting it as 0.00%.
+
 ## 0.3.3 (2026-07-29)
 
 ### Fixed
@@ -68,8 +145,21 @@
   deliberately supported. `re.ASCII` is unusable for the same reason, since it
   would also narrow `\w`.
 
-  Costs about 20% latency on short documents from the added lookarounds.
-  Accuracy on the corpus is unchanged.
+  **This is expensive.** The rewritten boundary is a lookaround union rather
+  than a single opcode, and every pattern carries it: **1.8× on short records
+  and 2.8× on real documents** (497 µs → 878 µs, and 5.2 ms → 14.4 ms, with
+  `[fast]` installed). An earlier revision of this entry said "about 20%" —
+  that was measured on 186-character synthetic records only and extrapolated,
+  wrongly, to real documents.
+
+  `[fast]` is close to required as a result: the RE2 prefilter absorbs most of
+  the cost by not running patterns that cannot match. Accuracy on the corpus is
+  unchanged.
+
+  Recovering the speed without giving back the five silent misses is open — the
+  likely route is to ASCII-ise only those boundaries that abut a digit or an
+  ASCII-only class, and leave plain `\b` where the neighbouring element is
+  Unicode-capable, rather than applying the union to all 303 patterns.
 
 ### Added
 
@@ -171,9 +261,14 @@
   Identical digits: `0612345678` is both a valid Dutch mobile number and a
   valid Danish CPR. Only the document distinguishes them.
 
-  On 152,300 documents, blind detection (no `countries=`) improved from
-  **95.6% to 98.3% precision** and from **94.90% to 98.38% type-correct**,
-  closing the gap to hinted detection from 3.4 points to 0.3.
+  On all 152,300 documents, blind detection (no `countries=`) improved from
+  **95.6% to 98.3% precision** and from **96.10% to 98.84% type-correct**,
+  closing the precision gap to hinted detection from 3.4 points to 0.3.
+
+  (An earlier revision of this entry quoted 94.90% → 98.38% for type-correct.
+  Those came from a 30,000-document prefix of the corpus, which is drawn from
+  one dataset and is not representative; they were labelled as full-corpus in
+  error. The figures above are measured over all 152,300.)
 
   Weights are derived from the corpus, not hand-tuned. Inference influences
   scoring only; it can never cause a miss.

{euredact-0.3.3 → euredact-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: euredact
-Version: 0.3.3
+Version: 0.3.4
 Summary: European PII redaction SDK — rule engine for 31 countries
 Project-URL: Documentation, https://github.com/euredact/euredact#readme
 Project-URL: Repository, https://github.com/euredact/euredact
@@ -792,11 +792,17 @@ Each `PatternDef` can specify:
 Measured on one core, all 31 countries loaded, `detect_dates=True`. Cost scales
 with document length, so the input size is stated rather than averaged away.
 
-| Input | Base | With `[fast]` |
-|---|---:|---:|
-| Short record (186 chars) | 723 µs — 1,383/s | **496 µs — 2,017/s** |
-| Real document (3,424 chars) | 10.4 ms — 96/s | **5.4 ms — 187/s** |
-| Memory per country | ~50 KB compiled patterns | |
+| Input | Pure Python | Aho-Corasick | With `[fast]` |
+|---|---:|---:|---:|
+| Short record (186 chars) | 907 µs — 1,103/s | 775 µs — 1,290/s | **516 µs — 1,938/s** |
+| Real document (3,424 chars) | 13.6 ms — 73/s | 10.9 ms — 92/s | **5.3 ms — 190/s** |
+| Memory per country | ~50 KB | ~50 KB | ~50 KB |
+
+Making `\b` catch identifiers glued to a non-ASCII letter costs something, but
+only where it must: next to a digit the ASCII reading alone is exactly
+equivalent, so one lookaround replaces a three-way alternation, and plain `\b`
+stays everywhere else. 0.3.3 applied the union to all 303 patterns and was
+1.8×/2.8× slower for it.
 
 ```bash
 pip install euredact[fast]

{euredact-0.3.3 → euredact-0.3.4}/README.md

@@ -751,11 +751,17 @@ Each `PatternDef` can specify:
 Measured on one core, all 31 countries loaded, `detect_dates=True`. Cost scales
 with document length, so the input size is stated rather than averaged away.
 
-| Input | Base | With `[fast]` |
-|---|---:|---:|
-| Short record (186 chars) | 723 µs — 1,383/s | **496 µs — 2,017/s** |
-| Real document (3,424 chars) | 10.4 ms — 96/s | **5.4 ms — 187/s** |
-| Memory per country | ~50 KB compiled patterns | |
+| Input | Pure Python | Aho-Corasick | With `[fast]` |
+|---|---:|---:|---:|
+| Short record (186 chars) | 907 µs — 1,103/s | 775 µs — 1,290/s | **516 µs — 1,938/s** |
+| Real document (3,424 chars) | 13.6 ms — 73/s | 10.9 ms — 92/s | **5.3 ms — 190/s** |
+| Memory per country | ~50 KB | ~50 KB | ~50 KB |
+
+Making `\b` catch identifiers glued to a non-ASCII letter costs something, but
+only where it must: next to a digit the ASCII reading alone is exactly
+equivalent, so one lookaround replaces a three-way alternation, and plain `\b`
+stays everywhere else. 0.3.3 applied the union to all 303 patterns and was
+1.8×/2.8× slower for it.
 
 ```bash
 pip install euredact[fast]

{euredact-0.3.3 → euredact-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "euredact"
-version = "0.3.3"
+version = "0.3.4"
 description = "European PII redaction SDK — rule engine for 31 countries"
 requires-python = ">=3.10"
 license = "Apache-2.0"

{euredact-0.3.3 → euredact-0.3.4}/src/euredact/__init__.py

@@ -22,7 +22,7 @@ from __future__ import annotations
 
 from typing import Iterator
 
-__version__ = "0.3.3"
+__version__ = "0.3.4"
 
 from euredact.rules.bic_registry import set_bic_registry
 from euredact.rules.context import DocumentContext

{euredact-0.3.3 → euredact-0.3.4}/src/euredact/rules/countries/_shared.py

@@ -218,7 +218,11 @@ class SharedConfig(CountryConfig):
             # Must be preceded by whitespace or start-of-string, 1-30 alphanumeric/underscore/dot chars
             PatternDef(
                 entity_type=EntityType.SOCIAL_HANDLE,
-                pattern=r"(?<!\w)@[a-zA-Z][a-zA-Z0-9_.]{1,29}\b",
+                # Unicode-aware: an ASCII-only class cannot match "@Ciarán"
+                # at all, and the boundary rewrite used to paper over that by
+                # stopping at "@Ciar" and masking a fragment while leaving "án"
+                # in the clear. [^\W\d_] is "a letter in any script".
+                pattern=r"(?<!\w)@[^\W\d_][\w.]{1,29}\b",
                 validator=None,
                 description="Social media handle (@username)",
             ),

{euredact-0.3.3 → euredact-0.3.4}/src/euredact/rules/countries/de.py

@@ -132,6 +132,14 @@ class DEConfig(CountryConfig):
                     "Rentenversicherung", "RV-Nummer", "Sozialversicherung",
                     "SV-Nummer", "Versicherungsnummer", "Rentenversicherungsnummer",
                     "Sozialversicherungsnummer",
+                    # The punctuation-free abbreviations. "SVNR" alone accounted
+                    # for every German social-security number this rule missed
+                    # across the corpus — 204 of them, unredacted, because the
+                    # list had "SV-Nummer" and "Sozialversicherung" but not the
+                    # form people actually type. "SV-Nr" and "RVNR" are the same
+                    # gap for the other two spellings; cf. KVNR alongside
+                    # KV-Nummer on the health-insurance rule.
+                    "SVNR", "SV-Nr", "RVNR",
                 ],
                 requires_context=True,
             ),

{euredact-0.3.3 → euredact-0.3.4}/src/euredact/rules/matchers.py

@@ -98,33 +98,66 @@ def _silence_stderr() -> Iterator[None]:
 # Which rule is "right" is arguable: Python's is self-consistent, JS's is
 # script-dependent. But for a redaction tool the argument is settled by the
 # failure direction. Python's principled rule leaves a national ID glued to a
-# non-ASCII letter unredacted; JS's limitation catches it. Over-detection is
-# recoverable, a silent miss is not.
+# non-ASCII letter unredacted; JS's limitation catches it.
 #
 # So \b is rewritten at compile time rather than in 303 pattern sources.
-# re.ASCII is not usable here: it would also narrow \w, breaking Unicode e-mail
-# local parts, which are deliberately supported.
+# re.ASCII is not usable: it would also narrow \w, breaking Unicode e-mail local
+# parts, which are deliberately supported.
 #
-# The rewrite is a *union* of both readings, not a swap to the ASCII one.
-# Neither alone is sufficient, and swapping regresses the other direction:
+# The rewrite is chosen per boundary, by what sits next to it.
 #
-#   "ЕГН7523169263"           needs the ASCII reading   (Н and 7 are both
-#                             word characters to Python, so no boundary)
-#   "Mail: αλέξης@example.gr" needs the Unicode reading (α is not an ASCII
-#                             word character, so no boundary)
+# **Next to a digit** — the ASCII reading alone is *exactly* the union of both
+# readings, because a Unicode letter is never an ASCII word character, so the
+# ASCII branch already succeeds everywhere the Unicode branch does. One
+# lookaround replaces a three-way alternation.
 #
-# Taking either one alone trades one silent miss for another — swapping to
-# ASCII-only was measured to drop the Greek address entirely. The union fires
-# wherever *either* reading sees a boundary, which is the over-detecting
-# direction on both counts and matches what Node already does on all seven
-# cases.
-_ASCII_WORD_BOUNDARY = (
-    r"(?:\b|(?<![0-9A-Za-z_])(?=[0-9A-Za-z_])|(?<=[0-9A-Za-z_])(?![0-9A-Za-z_]))"
-)
+# **Anything else** — plain \b, which is what "Mail: αλέξης@example.gr" needs:
+# α is not an ASCII word character, so an ASCII-only boundary would refuse to
+# start the match and the address would go unredacted.
+#
+# An earlier version applied the three-branch union everywhere. It was correct
+# but cost 1.8x on short records and 2.8x on real documents, and its ASCII branch
+# manufactured boundaries *inside* words at non-ASCII letters — truncating
+# "@Ciarán" to "@Ciar" and typing the fragment "FICIAIRES" of "BÉNÉFICIAIRES" as
+# a national ID. Choosing per boundary is both faster and cleaner.
+_ASCII_WORD = "0-9A-Za-z_"
+
+
+def _digit_only_element(source: str, i: int) -> bool:
+    """Does the pattern element starting at *source[i]* match only digits?"""
+    if source.startswith(r"\d", i):
+        return True
+    if i >= len(source) or source[i] != "[":
+        return False
+    close = source.find("]", i + 1)
+    if close < 0:
+        return False
+    body = source[i + 1:close]
+    return bool(body) and not body.startswith("^") and all(
+        c.isdigit() or c == "-" for c in body
+    )
+
+
+def _preceding_element_is_digits(source: str, i: int) -> bool:
+    """Looking left from *source[i]*, skip a quantifier and test the element."""
+    j = i - 1
+    if j >= 0 and source[j] == "}":
+        brace = source.rfind("{", 0, j)
+        if brace < 0:
+            return False
+        j = brace - 1
+    elif j >= 0 and source[j] in "+*?":
+        j -= 1
+    if j < 0:
+        return False
+    if source[j] == "]":
+        open_ = source.rfind("[", 0, j)
+        return open_ >= 0 and _digit_only_element(source, open_)
+    return j >= 1 and source[j - 1] == "\\" and source[j] == "d"
 
 
 def _ascii_word_boundaries(pattern: str) -> str:
-    """Rewrite every ``\b`` in *pattern* to the union boundary above.
+    """Rewrite each ``\b`` in *pattern* per the reasoning above.
 
     Skips escaped backslashes and character classes, where ``\b`` means a
     backspace rather than a boundary. Neither occurs in the shipped patterns
@@ -136,9 +169,13 @@ def _ascii_word_boundaries(pattern: str) -> str:
     while i < len(pattern):
         ch = pattern[i]
         if ch == "\\" and i + 1 < len(pattern):
-            nxt = pattern[i + 1]
-            if nxt == "b" and not in_class:
-                out.append(_ASCII_WORD_BOUNDARY)
+            if pattern[i + 1] == "b" and not in_class:
+                if _digit_only_element(pattern, i + 2):
+                    out.append(f"(?<![{_ASCII_WORD}])")
+                elif _preceding_element_is_digits(pattern, i):
+                    out.append(f"(?![{_ASCII_WORD}])")
+                else:
+                    out.append(r"\b")
             else:
                 out.append(pattern[i:i + 2])
             i += 2

{euredact-0.3.3 → euredact-0.3.4}/tests/eval_full.py

@@ -36,6 +36,13 @@ CATEGORY_MAP: dict[str, set[str]] = {
     "VIN": {EntityType.VIN.value},
     "PASSPORT": {EntityType.PASSPORT.value},
     "HEALTH_INSURANCE": {EntityType.HEALTH_INSURANCE.value, EntityType.NATIONAL_ID.value},
+    # The corpus also labels these two, and neither had an entry. SECRET worked
+    # by accident — the {SECRET} fallback happens to be a real engine type —
+    # but HEALTH_ID could never match anything, so all 252 of them scored as
+    # misses *and* charged the engine's correct HEALTH_INSURANCE detections as
+    # false positives. A harness gap, not an engine one.
+    "HEALTH_ID": {EntityType.HEALTH_INSURANCE.value, EntityType.NATIONAL_ID.value},
+    "SECRET": {EntityType.SECRET.value},
     "CHAMBER_OF_COMMERCE": {EntityType.CHAMBER_OF_COMMERCE.value, EntityType.VAT.value},
     "IP_ADDRESS": {EntityType.IP_ADDRESS.value},
     "IPV6_ADDRESS": {EntityType.IPV6_ADDRESS.value},

euredact-0.3.4/tests/metrics.py

@@ -0,0 +1,268 @@
+"""Per-entity-type precision, recall, F1 and false-positive counts.
+
+`eval_full.py` renders an HTML report with recall and precision per type and
+country. This is the plain-text counterpart: one row per PII type, four numbers,
+both detection modes, and definitions stated rather than implied — so a figure
+quoted from it can be reproduced and argued with.
+
+    python tests/metrics.py                    # both modes, whole corpus
+    python tests/metrics.py --mode blind
+    python tests/metrics.py --limit 20000
+    python tests/metrics.py --csv out.csv
+
+Definitions
+-----------
+Matching is span-overlap plus type-acceptability, the same rule `eval_full.py`
+uses: a detection matches a ground-truth label when their spans overlap **and**
+the detection's entity type is in that label category's acceptable set (see
+``CATEGORY_MAP``). Overlap rather than exact equality, because the engine's
+notion of where an identifier ends can legitimately differ by a separator.
+
+    TP   a labelled span with at least one matching detection
+    FN   a labelled span with none
+    FP   a detection that satisfied no label — including one that landed on a
+         labelled span under the wrong type, which is both a miss and a false
+         positive, and a duplicate detection of an already-satisfied label
+
+Rows are keyed on the **ground-truth category**, since that is what the corpus
+labels. A false positive is charged to the category its entity type would have
+satisfied (printed as the type→category map below, so the attribution is
+auditable). Types the corpus never labels get their own row and have no recall.
+
+DOB is reported but excluded from the totals: bare dates are handled by the
+cloud tier, and the rules engine only emits them with a keyword or structural
+cue, so its recall here is not a defect.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import os
+import sys
+import time
+from collections import Counter, defaultdict
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+import euredact  # noqa: E402
+from euredact.rules.registry import CountryRegistry  # noqa: E402
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from eval_full import CATEGORY_MAP, DOB_CATEGORIES, EXCLUDED_CATEGORIES  # noqa: E402
+
+DATA_DIR = Path(os.environ.get(
+    "EUREDACT_CORPUS",
+    "/Users/jorenjanssens/Library/Mobile Documents/com~apple~CloudDocs/Werken/JNJS/"
+    "Apps/PII-EuroMask/Data-Generation",
+))
+
+#: The ten canonical datasets. `euromask_international_10k.json.bak` is
+#: deliberately absent: it is the *same* 10,000 documents with the same texts,
+#: differing only in carrying 640 BIC labels that were removed as false
+#: positives when the dataset was corrected. Including it would double-count
+#: those documents and score the engine against labels known to be wrong.
+DATASETS = [
+    "euromask_allcountries_20k.json",
+    "euromask_dach_south_20k.json",
+    "euromask_eastern_20k.json",
+    "euromask_el_cy_mt_20k.json",
+    "euromask_ie_baltics_uk_20k.json",
+    "euromask_international_10k.json",
+    "euromask_nordic_20k.json",
+    "euromask_secrets_5k.json",
+    "euromask_training_core.json",
+    "euromask_training_core2.json",
+]
+
+
+def canonical_category_of_type(support: Counter[str]) -> dict[str, str]:
+    """Entity type -> the category a false positive of that type is charged to.
+
+    Preference order: the category named after the type *if the corpus labels
+    it*, then whichever candidate the corpus labels most often, then the one
+    with the fewest acceptable types, then alphabetical.
+
+    Both halves of that are load-bearing. Without the support check, BIC false
+    positives were charged to a ``BIC`` row with zero support while every real
+    label sat under ``SWIFT_BIC`` — one type's precision split across two rows,
+    reading as 0.00%. Without the name check first, TAX_ID false positives were
+    charged to NATIONAL_ID purely because it is a hundred times larger, even
+    though TAX_ID has a real row of its own.
+    """
+    owners: dict[str, list[str]] = defaultdict(list)
+    for category, types in CATEGORY_MAP.items():
+        for etype in types:
+            owners[etype].append(category)
+    resolved = {}
+    for etype, cats in owners.items():
+        resolved[etype] = sorted(
+            cats,
+            key=lambda c: (
+                0 if (c == etype and support.get(c, 0)) else 1,  # own row, if real
+                -support.get(c, 0),                              # else the busiest
+                len(CATEGORY_MAP[c]), c,
+            ),
+        )[0]
+    return resolved
+
+
+def load(limit: int | None):
+    records = []
+    for name in DATASETS:
+        path = DATA_DIR / name
+        if not path.exists():
+            print(f"missing: {path}", file=sys.stderr)
+            continue
+        records.extend(json.loads(path.read_text()))
+        if limit and len(records) >= limit:
+            break
+    return records[:limit] if limit else records
+
+
+def evaluate(records, hinted: bool):
+    known = set(CountryRegistry().available_countries)
+    support: Counter[str] = Counter()
+    for item in records:
+        for pii in item.get("PII") or []:
+            if pii["PII_category"] not in EXCLUDED_CATEGORIES:
+                support[pii["PII_category"]] += 1
+    charge_to = canonical_category_of_type(support)
+    tp: Counter[str] = Counter()
+    fn: Counter[str] = Counter()
+    fp: Counter[str] = Counter()
+    euredact._instance = None
+    t0 = time.time()
+
+    for item in records:
+        text = item["source_text"]
+        expected = item.get("PII") or []
+        if not expected:
+            continue
+        countries = [c for c in {p["PII_country"] for p in expected} if c in known]
+        detections = euredact.redact(
+            text, countries=(countries or None) if hinted else None,
+            detect_dates=True, cache=False,
+        ).detections
+
+        labels = []
+        for pii in expected:
+            category = pii["PII_category"]
+            if category in EXCLUDED_CATEGORIES:
+                continue
+            idx = text.find(pii["PII_identifier"])
+            if idx < 0:
+                continue  # not present verbatim; not scoreable
+            labels.append((idx, idx + len(pii["PII_identifier"]), category))
+
+        matched_detections = set()
+        for start, end, category in labels:
+            acceptable = CATEGORY_MAP.get(category, {category})
+            hit = None
+            for i, d in enumerate(detections):
+                if (d.start < end and d.end > start
+                        and d.entity_type.value in acceptable):
+                    hit = i
+                    break
+            if hit is None:
+                fn[category] += 1
+            else:
+                tp[category] += 1
+                matched_detections.add(hit)
+
+        for i, d in enumerate(detections):
+            if i in matched_detections:
+                continue
+            # Strict: a detection that did not satisfy a label is a false
+            # positive, including one that landed on a labelled span under the
+            # wrong type. That case is a miss *and* a false positive — the
+            # value is masked but filed wrongly, which is exactly what
+            # type-aware downstream handling gets hurt by. Exempting it would
+            # let mistypes disappear from both columns and flatter precision.
+            fp[charge_to.get(d.entity_type.value, d.entity_type.value)] += 1
+
+    return tp, fn, fp, time.time() - t0, charge_to
+
+
+def report(tp, fn, fp, elapsed, rows_csv=None, label=""):
+    keys = sorted(set(tp) | set(fn) | set(fp))
+    core = [k for k in keys if k not in DOB_CATEGORIES]
+
+    def prf(k):
+        t, f_n, f_p = tp[k], fn[k], fp[k]
+        p = t / (t + f_p) if t + f_p else 0.0
+        r = t / (t + f_n) if t + f_n else 0.0
+        f1 = 2 * p * r / (p + r) if p + r else 0.0
+        return t, f_p, f_n, p, r, f1
+
+    print(f"\n{label}  ({elapsed:.0f}s)")
+    print(f"{'type':26s} {'support':>9s} {'TP':>8s} {'FP':>7s} {'FN':>7s} "
+          f"{'prec':>7s} {'recall':>7s} {'F1':>7s}")
+    print("-" * 84)
+    for k in core:
+        t, f_p, f_n, p, r, f1 = prf(k)
+        print(f"{k:26s} {t + f_n:9,} {t:8,} {f_p:7,} {f_n:7,} "
+              f"{p * 100:6.2f}% {r * 100:6.2f}% {f1 * 100:6.2f}%")
+
+    T, FP_, FN_ = (sum(tp[k] for k in core), sum(fp[k] for k in core),
+                   sum(fn[k] for k in core))
+    P = T / (T + FP_) if T + FP_ else 0.0
+    R = T / (T + FN_) if T + FN_ else 0.0
+    F = 2 * P * R / (P + R) if P + R else 0.0
+    print("-" * 84)
+    print(f"{'TOTAL (excl. DOB)':26s} {T + FN_:9,} {T:8,} {FP_:7,} {FN_:7,} "
+          f"{P * 100:6.2f}% {R * 100:6.2f}% {F * 100:6.2f}%")
+    for k in keys:
+        if k in DOB_CATEGORIES:
+            t, f_p, f_n, p, r, f1 = prf(k)
+            print(f"{k + ' (cloud tier)':26s} {t + f_n:9,} {t:8,} {f_p:7,} {f_n:7,} "
+                  f"{p * 100:6.2f}% {r * 100:6.2f}% {f1 * 100:6.2f}%")
+
+    if rows_csv is not None:
+        for k in keys:
+            t, f_p, f_n, p, r, f1 = prf(k)
+            rows_csv.append({"mode": label, "type": k, "support": t + f_n, "tp": t,
+                             "fp": f_p, "fn": f_n, "precision": round(p * 100, 4),
+                             "recall": round(r * 100, 4), "f1": round(f1 * 100, 4)})
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--mode", choices=["hinted", "blind", "both"], default="both")
+    ap.add_argument("--limit", type=int, default=None)
+    ap.add_argument("--csv", type=Path, default=None)
+    args = ap.parse_args()
+
+    records = load(args.limit)
+    if not records:
+        print("No datasets found; set EUREDACT_CORPUS.")
+        return 77
+    labelled = sum(1 for r in records if r.get("PII"))
+    print(f"datasets : {len(DATASETS)} files "
+          f"(the .bak is excluded — see module docstring)")
+    print(f"records  : {len(records):,} ({labelled:,} carrying labels)")
+
+    rows: list[dict] = [] if args.csv else None
+    modes = ["hinted", "blind"] if args.mode == "both" else [args.mode]
+    charge_to = None
+    for mode in modes:
+        tp, fn, fp, elapsed, charge_to = evaluate(records, hinted=(mode == "hinted"))
+        report(tp, fn, fp, elapsed, rows, label=f"{mode} detection")
+
+    print("\nfalse positives are charged to the category their type would satisfy:")
+    shown = sorted({f"{t}->{c}" for t, c in charge_to.items() if t != c})
+    print("  " + ", ".join(shown) if shown else "  (all types map to themselves)")
+
+    if args.csv:
+        with args.csv.open("w", newline="") as fh:
+            w = csv.DictWriter(fh, fieldnames=list(rows[0]))
+            w.writeheader()
+            w.writerows(rows)
+        print(f"\ncsv written to {args.csv}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())