KVCHub/Kava-Privacy-636k-mlx

Kava Privacy

A small Transformer encoder, trained entirely from scratch (random weight initialization, no pretrained backbone), that finds and redacts personally identifiable information (PII) in free text. Built with MLX and tuned to run fast on Apple Silicon's GPU / Neural Engine.

It tags each token as one of 9 entity types using BIO labeling, then a thin redaction layer replaces detected spans with [TYPE] placeholders.

Entity type	Example
NAME	John Smith
EMAIL	jane.doe@gmail.com
PHONE	555-123-4567
DOB	March 3, 1994
ADDRESS	782 Willow Creek Dr, Boulder, CO
SSN	501-22-9384
CREDIT_CARD	4485-1122-9834-7710
IP	203.0.113.44
HANDLE	@jane_doe

Model details

• Architecture: 4-layer pre-norm Transformer encoder, 4 attention heads, 128 hidden dim, learned positional + word + digit-shape-feature embeddings, linear BIO tag head.
• Parameters: ~636K
• Size on disk: ~2.4 MB (kava_privacy.safetensors)
• Framework: MLX (mlx-core, mlx.nn)
• Training data: fully synthetic — programmatically generated sentences and multi-sentence paragraphs with realistic fake names, emails, phone numbers, addresses, SSNs, credit card numbers, IPs, and social handles inserted into varied templates. No real user data was used or seen during training.
• Vocabulary: word-level, with out-of-vocabulary tokens collapsed to structural "shape" keys (e.g. digit-run patterns like D3-D3-D4 for phone numbers) so the model generalizes to PII values it never saw literally during training, rather than memorizing exact strings.

Validation results

Token-level accuracy on a held-out synthetic validation set (2,500 examples):

Label	Accuracy
O (non-PII)	100.0%
NAME (B-/I-)	99.8% / 100.0%
EMAIL	100.0%
PHONE (B-/I-)	100.0% / 100.0%
DOB (B-/I-)	100.0% / 99.9%
ADDRESS (B-/I-)	100.0% / 100.0%
SSN	100.0%
CREDIT_CARD (B-/I-)	99.7% / 99.6%
IP	99.8%
HANDLE	100.0%

Real-world caveat: synthetic-data accuracy is not the same as accuracy on arbitrary real text. Manual testing on unseen, hand-written paragraphs (not drawn from training templates) showed the model reliably catches emails, phone numbers, SSNs, IP addresses, handles, and single names, but can still:

• miss a surname immediately following a correctly-tagged first name,
• leave a word or two un-redacted in the middle of a multi-part address,
• miss credit card numbers formatted with spaces instead of dashes.

Treat this as a solid first-generation model, not a guarantee of zero PII leakage — always spot-check redacted output for sensitive use cases.

Files in this repository

This is a complete, self-contained bundle — everything needed to load and run the model is included, with no dependency on transformers or mlx_lm (this is a custom architecture, not a recognized HF model type, so those libraries can't load it):

• kava_privacy.safetensors — the trained weights (~2.4 MB, ~636K params)
• config.json — architecture hyperparameters (dim, layers, heads, label set)
• vocab.json — the word/shape vocabulary used at training time
• kava_privacy.py — the model class + tokenizer + inference code that reads the two files above and builds the matching nn.Module

Quick start

1. Get the files from the Files tab of this repo

[https://huggingface.co/KVCHub/Kava-Privacy-636k-mlx/tree/main). Download the zip file

2. Install the dependencies (Apple Silicon Mac required):

Make sure you have pip installed before running the next command

pip install mlx numpy

3. Run it:

Cd into the Kava-privacy-mlx folder unzipped

python3 kava_privacy.py "Email me at jane.doe@gmail.com or call 555-123-4567. My SSN is 501-22-9384."
# Email me at [EMAIL] or call [PHONE]. My SSN is [SSN].

Or use it as a library from a Python script:

First install the libary

pip install kava-privacy

Sample Code:

from kava_privacy import KavaPrivacy

kp = KavaPrivacy(model_name="636k")

redacted, entities = kp.redact("Email me at jane.doe@gmail.com or call 555-123-4567.")
print(redacted)
# Output: "Email me at [EMAIL] or call [PHONE]."

You can restrict redaction to specific entity types:

redacted, entities = kp.redact(text, entity_types={"EMAIL", "PHONE"})

Intended use

Lightweight, fully offline, on-device PII redaction for text — e.g. scrubbing logs, chat exports, support tickets, or documents before further processing or sharing. Designed to run fast and privately on Apple Silicon without sending any text to a remote API.

Limitations

• Trained only on English-language synthetic text; performance on other languages, heavily abbreviated text, or unusual formatting is untested.
• Not a substitute for a compliance-grade PII detection system (e.g. for HIPAA/GDPR obligations) — it has no formal accuracy guarantees.
• As with any small model, novel PII formats or rare name patterns may be missed. Always review redacted output before treating it as safe to share.

License

MIT