limits

README.md

@@ -28,6 +28,43 @@ Python rules do the identifiers they can prove. A transformer NER head adds phon
 - **Additive labels:** XLM-RoBERTa-large token classifier, BIO tags `phone` / `pii`, threshold 0.95
 - **This snapshot:** seed `202609160`, **epoch 5** of a seven-epoch schedule
 
+## What NERGAL detects — and what it does not
+
+NERGAL masks **contact details and selected identifiers in Polish text**. It is not a general-purpose anonymizer: names, postal addresses and other personal information can remain in the output. Its corpus-masking policy also includes public, institutional and company contacts and identifiers.
+
+### Detection scope
+
+These are target categories, not a guarantee that every occurrence or format is detected.
+
+| Category | Values in scope | Replacement |
+|---|---|---|
+| Phone contacts | Phone, fax and SMS contact numbers, including foreign, emergency, short/service and vanity numbers; extensions and number alternatives | `[Telefon]` |
+| Email | Email addresses, including recoverable broken or incomplete addresses | `[PII]` |
+| Personal identifiers | PESEL, passport and identity-document numbers | `[PII]` |
+| Organization identifiers | NIP/VAT, REGON, KRS, GEMI, LEI and equivalent foreign company registration numbers; labelled DUNS, BDO and RPWDL register-book numbers | `[PII]` |
+| Financial identifiers | Bank/account numbers, including Polish accounts and foreign IBANs | `[PII]` |
+| Property identifiers | Land-register (księga wieczysta, KW) numbers | `[PII]` |
+| Electronic contacts and access | e-Doręczenia and ePUAP addresses, explicitly labelled numeric access PINs (including `pin=` URL values), GG account IDs | `[PII]` |
+
+Context matters: a number that resembles a phone or identifier is not automatically in scope. Rules use labels, format checks and, for some unlabelled identifiers, checksums; the model adds contextual detections. Coverage varies by category, and the aggregate benchmark below does not establish recall for every category.
+
+### Outside detection scope
+
+NERGAL is not designed to remove:
+
+- **Personal names**, including private individuals and public officials; organization names.
+- **Postal/street addresses, dates of birth and ages.**
+- **Social-media handles, ordinary URLs and filenames.** An in-scope value inside a URL, such as a labelled numeric PIN, can still be masked.
+- **Vehicle registration plates and generic serial, model or version codes.**
+- **Document, case, article, funding and procurement references**, including procedure UUIDs; ISBNs, ORCIDs, TERYT codes, EAN/GTIN product codes and CNIL website-registration references.
+- Prices, list numbers, generic labels without values, clearly fictitious examples and already-redacted placeholders.
+
+These are intended exclusions; false positives can still mask some of this content.
+
+### Known gaps in 1.0.3
+
+Unlabelled phones and identifiers, unusual formatting and damaged text can escape detection. **VINs and obfuscated emails** (such as `name (at) domain.pl`) are approved annotation targets, but that approval alone does not establish reliable support in the released 1.0.3 model. Do not rely on it to remove them consistently.
+
 ## Versions
 
 841-dev, union at 0.95, 354 gold spans. Same weights and API is a patch; new capability is minor; API, threshold, or weight recipe is major. A release that changes these numbers updates `hybrid.json` `eval` and this table.