v0.3.0 model card

README.md

@@ -0,0 +1,134 @@
+---
+license: apache-2.0
+language:
+  - en
+  - de
+  - fr
+  - es
+  - it
+  - multilingual
+base_model:
+  - urchade/gliner_multi_pii-v1
+library_name: gliner
+tags:
+  - pii
+  - privacy
+  - ner
+  - llm-safety
+  - gdpr
+  - pii-redaction
+  - multilingual
+  - onnx
+pipeline_tag: token-classification
+---
+
+# nullpii
+
+Multilingual PII detection. ONNX-exported GLiNER built on
+[`urchade/gliner_multi_pii-v1`](https://huggingface.co/urchade/gliner_multi_pii-v1)
+(mDeBERTa-v3 base + GLiNER head, ~278M params). ~1.2 GB FP32.
+12-category span output.
+
+**Hobby / experiment.** A nights-and-weekends project. No SLA, no
+roadmap commitments. If it helps you, great.
+
+Companion runtime: [`nullpii`](https://www.npmjs.com/package/nullpii)
+(npm) + [`@lbroth/nullpii-gateway`](https://www.npmjs.com/package/@lbroth/nullpii-gateway)
+(Anthropic Messages API proxy).
+Source: [github.com/lBroth/nullpii](https://github.com/lBroth/nullpii).
+
+## What gets detected
+
+12 categories. ML-trained (8): `account_number`, `private_address`,
+`private_date`, `private_email`, `private_person`, `private_phone`,
+`private_url`, `secret`. Zero-shot prompted + regex post-pass (4):
+`private_passport`, `private_driver_license`, `private_vehicle_id`,
+`private_geolocation`. Pure regex (2): `private_ip`, `private_mac`.
+
+Full label table + adversarial-input coverage matrix:
+[GitHub README §What gets caught](https://github.com/lBroth/nullpii#what-gets-caught).
+
+## Two runtime modes
+
+This repo ships the raw ONNX + tokenizer + `gliner_config.json`. F1
+depends on which runtime you pair it with:
+
+| Mode | What it is | Best for |
+|---|---|---|
+| **`nullpii-bare`** | this ONNX + GLiNER decoder + 1400-char chunking. No post-processing. | benchmark parity with other GLiNER family models. |
+| **`nullpii`** | the npm package full runtime: adversarial-input preprocessor (NFKC + transliteration + URL/HTML decode + zero-width strip), 50+ recognizer regex pack with validators (IBAN mod-97, Luhn, VIN ISO 3779, etc.), base64 decode-then-classify, never-PII filter, boundary refinement, reversible in-memory vault. | production PII sanitization, OOD generalization. |
+
+Held-out OOD macro F1 (`nullpii`): **0.7784** across `presidio-synthetic`,
+`isotonic-{en,de,fr,it}-heldout`, `ai4privacy-300k-heldout`, `tab-echr`.
+
+Full 9-tool × 16-dataset matrix vs Piiranha, DeBERTa-PII, Presidio,
+Nemotron-PII, OpenAI privacy-filter, GLiNER native:
+[github.com/lBroth/nullpii/tree/main/packages/eval/published-bench](https://github.com/lBroth/nullpii/tree/main/packages/eval/published-bench).
+
+## Latency
+
+M5 Pro CPU, Node 24, `nullpii` runtime:
+
+| Input | p50 | p95 | p99 |
+|---:|---:|---:|---:|
+| 100 chars | 23 ms | 25 ms | 27 ms |
+| 1,000 chars | 95 ms | 113 ms | 114 ms |
+| 10,000 chars | 938 ms | 972 ms | 1,122 ms |
+
+Cold start (first call, includes ONNX load): ~756 ms.
+
+## Usage
+
+```bash
+npm install nullpii onnxruntime-node
+```
+
+```ts
+import { sanitize, restore } from 'nullpii';
+
+const safe = await sanitize('Email John Smith at john@acme.io');
+// → 'Email {{PII_PRIVATE_PERSON_0_…}} at {{PII_PRIVATE_EMAIL_0_…}}'
+
+// ... your LLM call (OpenAI, Anthropic, Gemini, anything) ...
+
+const back = restore(reply, safe.sessionId);
+// → original text restored
+```
+
+The npm package downloads this model on first `sanitize()` into
+`~/.cache/nullpii/`. Pre-warm with `npx nullpii prefetch`.
+
+## Direct ONNX (no runtime)
+
+```py
+# Python — minimum viable: tokenizer + ONNX inference + decoder
+from gliner import GLiNER
+m = GLiNER.from_pretrained('lBroth/nullpii', load_onnx_model=True)
+spans = m.predict_entities(
+    text='Email John at john@acme.io',
+    labels=['private_person', 'private_email'],
+)
+```
+
+## Limitations
+
+- Detector misses (no model is 100% accurate).
+- Not a HIPAA de-identifier — diagnoses, ICD codes, dosages,
+  biometric / genetic identifiers are out of scope.
+- `private_ip` / `private_mac` come from the regex pack, not the model.
+- Detection is best-effort. Defence in depth, not the sole privacy
+  control.
+
+## Attribution
+
+- Base model: [`urchade/gliner_multi_pii-v1`](https://huggingface.co/urchade/gliner_multi_pii-v1)
+  (GLiNER, Zaratiana et al., NAACL 2024) — Apache-2.0.
+- mDeBERTa-v3 base — MIT.
+- Includes Nemotron-PII derivative content — CC-BY-4.0.
+
+See [`NOTICE`](https://github.com/lBroth/nullpii/blob/main/NOTICE) for the full
+attribution + license posture.
+
+## License
+
+Apache-2.0.