HerBERT Polish legal NER (OCR-robust): weights + ONNX + card + examples

README.md

@@ -38,6 +38,10 @@ diacritics, confusable characters, fragmented surnames).
 — an interactive, **fully client-side** Polish legal-document anonymisation demo
 (same anonymiser family; the text never leaves your browser).
 
+**📂 Example cases:** [`examples/STRONG_CASES.md`](examples/STRONG_CASES.md) (hard
+inputs it handles — OCR garble, declension, ALL-CAPS) ·
+[`examples/KNOWN_LIMITATIONS.md`](examples/KNOWN_LIMITATIONS.md) (where it still fails).
+
 ## Labels (29, BIO scheme)
 
 `PER` (person) · `ORG` (organisation) · `LOC` (private address/location) ·

examples/STRONG_CASES.md

@@ -0,0 +1,50 @@
+# Where the model shines — hard cases handled well
+
+The flip side of [`KNOWN_LIMITATIONS.md`](KNOWN_LIMITATIONS.md): difficult inputs
+the model gets **right**. These are exactly the cases a plain dictionary / regex
+or a non-OCR-augmented model tends to miss.
+
+All inputs are synthetic (fictional names). Outputs are the model's **actual**
+predictions (quantized ONNX, recall-first PER threshold 0.2). Reproduce with
+[`strong_cases.py`](strong_cases.py).
+
+## OCR-garbled names (the variant's headline strength)
+
+Names corrupted by optical character recognition — still recognised:
+
+| Input | Behind the garble | Model |
+|---|---|---|
+| `Pozwany Damian Zotadek wniósł odpowiedź na pozew.` | *Damian Żołądek* (lost diacritics) | `PER 'Damian Zotadek'` |
+| `Z powództwa Jiga Bękowiki przeciwko spółce.` | *Jaga Bętkowski* (heavy garble) | `PER 'Jiga Bękowiki'` |
+| `Pełnomocnik: Ptek Gostoiski, adwokat.` | *Patryk Gostomski* (signature line) | `PER 'Ptek Gostoiski'` |
+
+## Polish inflection (declension)
+
+Polish surnames change form by grammatical case; the model tags the full inflected
+surface, not just the nominative:
+
+| Input | Case | Model |
+|---|---|---|
+| `Pozew skierowano przeciwko Jerzemu Sekule.` | dative | `PER 'Jerzemu Sekule'` |
+| `Sprawa dotyczy akt Wojciecha Michalika.` | genitive | `PER 'Wojciecha Michalika'` |
+
+## Tricky surface forms
+
+| Input | Why it's hard | Model |
+|---|---|---|
+| `Powódka Anna Nowak-Kowalska złożyła wniosek.` | hyphenated double surname → one span | `PER 'Anna Nowak-Kowalska'` |
+| `Stawiła się ALEKSANDRA ŚWIDERSKA, pełnomocnik.` | ALL-CAPS header/signature style | `PER 'ALEKSANDRA ŚWIDERSKA'` |
+| `Z poważaniem,` / `Iga Mełech` / `radca prawny` | short female first + rare surname in a low-cue signature | `PER 'Iga Mełech'` |
+
+## Multiple types + public/private distinction
+
+```
+Jan Kowalski, zam. ul. Słoneczna 5 w Krakowie, PESEL 02070803628.
+   PER      'Jan Kowalski'
+   LOC      'ul. Słoneczna 5'      ← private address (masked)
+   LOC_PUB  'Krakowie'             ← public city (kept by default)
+   ID       '02070803628'          ← national id (PESEL)
+```
+
+The model keeps the public place (`Krakowie`) visible while masking the private
+street address (`ul. Słoneczna 5`) — so the legal context survives anonymisation.

examples/strong_cases.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Hard cases the model handles WELL — the flip side of KNOWN_LIMITATIONS.md.
+
+All inputs are synthetic (fictional names). Outputs are the model's actual
+predictions (quantized ONNX, recall-first PER threshold 0.2). Reproduce:
+    python examples/strong_cases.py
+"""
+import json
+from pathlib import Path
+
+import numpy as np
+import onnxruntime as ort
+from transformers import AutoTokenizer
+
+ROOT = Path(__file__).resolve().parent.parent
+PER_THRESHOLD = 0.2
+
+tok = AutoTokenizer.from_pretrained(str(ROOT))
+cfg = json.load(open(ROOT / "config.json", encoding="utf-8"))
+id2label = {int(k): v for k, v in cfg["id2label"].items()}
+label2id = cfg["label2id"]
+sess = ort.InferenceSession(str(ROOT / "onnx" / "model_quantized.onnx"))
+in_names = {i.name for i in sess.get_inputs()}
+
+
+def softmax(x):
+    e = np.exp(x - x.max(-1, keepdims=True)); return e / e.sum(-1, keepdims=True)
+
+
+def predict(text):
+    enc = tok(text, return_offsets_mapping=True, return_tensors="np", truncation=True, max_length=512)
+    offs = enc["offset_mapping"][0]
+    feeds = {"input_ids": enc["input_ids"].astype(np.int64),
+             "attention_mask": enc["attention_mask"].astype(np.int64)}
+    if "token_type_ids" in in_names:
+        feeds["token_type_ids"] = np.zeros_like(enc["input_ids"], dtype=np.int64)
+    probs = softmax(sess.run(None, feeds)[0][0])
+    ids = probs.argmax(-1)
+    pb, pi = label2id["B-PER"], label2id["I-PER"]
+    spans, cur = [], None
+    for i, (s, e) in enumerate(offs):
+        if s == e:
+            if cur: spans.append(cur); cur = None
+            continue
+        lab = id2label[int(ids[i])]
+        if lab == "O" and probs[i, pb] + probs[i, pi] >= PER_THRESHOLD:
+            lab = "I-PER" if (cur and cur[2] == "PER") else "B-PER"
+        if lab == "O":
+            if cur: spans.append(cur); cur = None
+            continue
+        tag, et = lab.split("-", 1)
+        if tag == "B" or cur is None or cur[2] != et:
+            if cur: spans.append(cur)
+            cur = [int(s), int(e), et]
+        else:
+            cur[1] = int(e)
+    if cur: spans.append(cur)
+    return [{"type": t, "start": a, "end": b, "text": text[a:b]} for a, b, t in spans]
+
+
+CASES = [
+    ("Pozwany Damian Zotadek wniósł odpowiedź na pozew.", "OCR: missing diacritics (Żołądek)"),
+    ("Z powództwa Jiga Bękowiki przeciwko spółce.", "OCR: heavily garbled name (Jaga Bętkowski)"),
+    ("Pełnomocnik: Ptek Gostoiski, adwokat.", "OCR garble in a signature line (Patryk Gostomski)"),
+    ("Pozew skierowano przeciwko Jerzemu Sekule.", "inflected (dative) Polish name"),
+    ("Sprawa dotyczy akt Wojciecha Michalika.", "inflected (genitive) Polish name"),
+    ("Powódka Anna Nowak-Kowalska złożyła wniosek.", "hyphenated double surname (single span)"),
+    ("Stawiła się ALEKSANDRA ŚWIDERSKA, pełnomocnik.", "ALL-CAPS name (header/signature style)"),
+    ("Z poważaniem,\nIga Mełech\nradca prawny", "short female first + rare surname in a signature"),
+    ("Jan Kowalski, zam. ul. Słoneczna 5 w Krakowie, PESEL 02070803628.",
+     "private address (LOC) vs public city (LOC_PUB) + national ID"),
+]
+
+if __name__ == "__main__":
+    print(f"PER threshold = {PER_THRESHOLD}\n")
+    for text, note in CASES:
+        print(f"# {note}")
+        print(f"  input : {text.replace(chr(10), ' / ')}")
+        for e in predict(text):
+            print(f"     {e['type']:8} {e['text']!r}")
+        print()