Upload folder using huggingface_hub

README.md

@@ -7,16 +7,20 @@ tags:
   - pii
   - token-classification
   - named-entity-recognition
-  - security
+  - transformers
+  - bert
   - synthetic-data
 pipeline_tag: token-classification
-library_name: maskara
+library_name: transformers
+base_model: google/bert_uncased_L-2_H-128_A-2
 datasets:
-  - somukandula/maskara-synthetic-pii
+  - somukandula/maskara-extensive-pii
+  - ai4privacy/pii-masking-300k
 metrics:
   - precision
   - recall
   - f1
+  - accuracy
 model-index:
   - name: maskara
     results:
@@ -24,185 +28,167 @@ model-index:
           type: token-classification
           name: PII span detection
         dataset:
-          type: somukandula/maskara-synthetic-pii
-          name: Maskara Synthetic PII
-          split: validation
+          type: somukandula/maskara-extensive-pii
+          name: Maskara Extensive PII
+          split: test
         metrics:
-          - type: accuracy
-            value: 0.997638167217761
-            name: Token accuracy
           - type: precision
-            value: 0.9712230215827338
+            value: 0.6761385753211366
             name: Span precision
           - type: recall
-            value: 0.989010989010989
+            value: 0.6948
             name: Span recall
           - type: f1
-            value: 0.9800362976406534
+            value: 0.6853422765831524
             name: Span F1
+          - type: accuracy
+            value: 0.9303269147627125
+            name: Token accuracy
 ---
 
 # Maskara
 
-Maskara is a local PII span detector for privacy-preserving LLM middleware. It
-finds sensitive values in prompts before they are sent to cloud model providers,
-so a local SDK can replace them with stable fake twins and restore the original
-values after the model responds.
+Maskara is a real Hugging Face Transformers token-classification model for
+local PII span detection in LLM prompts.
+
+It is trained to identify sensitive spans before prompts are sent to cloud LLM
+providers. The intended product flow is:
 
-This repository contains the first CPU-trained Maskara detector. It is a small
-custom token classifier, not a Transformers checkpoint. It is designed to run
-inside the `maskara` Python SDK alongside deterministic regex and validator
-detectors.
+1. Detect PII locally.
+2. Replace detected spans with stable fake twins.
+3. Send only the protected prompt to the LLM provider.
+4. Restore the original values locally in the response.
 
-## What This Model Does
+## Model
 
-The model predicts BIO token tags for common sensitive entities:
+- Architecture: `BertForTokenClassification`
+- Base model: `google/bert_uncased_L-2_H-128_A-2`
+- Framework: Hugging Face Transformers + PyTorch
+- Output: BIO token tags
+- Checkpoint format: `model.safetensors`
+
+This replaces the earlier perceptron baseline with a standard ML checkpoint
+that can be loaded with `AutoModelForTokenClassification`.
+
+## Labels
+
+The model predicts BIO tags for:
 
-- `PERSON_NAME`
-- `EMAIL`
-- `PHONE`
 - `ADDRESS`
-- `LOCATION`
+- `API_KEY`
 - `CREDIT_CARD`
+- `DATE_OF_BIRTH`
+- `DRIVER_LICENSE`
+- `EMAIL`
+- `IP_ADDRESS`
+- `LOCATION`
+- `PASSWORD`
+- `PERSON_NAME`
+- `PHONE`
 - `SSN`
-- `API_KEY`
 - `USERNAME`
-- `PASSWORD`
-
-Maskara uses this model for fuzzy spans such as names, locations, addresses,
-and usernames. Structured and high-risk values such as credit cards, SSNs,
-emails, phone numbers, API keys, and passwords should still be protected first
-by deterministic rules and validators.
 
-## How It Helps
-
-LLM applications often need cloud model quality, but prompts can contain names,
-emails, phone numbers, addresses, payment test cards, credentials, or internal
-identifiers. Maskara helps by keeping the privacy boundary local:
+## Training Data
 
-1. Detect sensitive spans on the user's machine.
-2. Replace those spans with fake but plausible values.
-3. Send only the protected prompt to the LLM provider.
-4. Restore original values locally in the response.
+The training corpus contains 75,000 examples:
 
-The model improves coverage where pure regex is brittle, especially for names
-and location-like text in normal prose.
+- 67,500 train
+- 3,750 validation
+- 3,750 test
 
-## Training Data
+The final local training run used:
 
-The model was trained on synthetic data generated by the Maskara repository:
+- 30,000 training examples
+- 1,000 validation examples
+- 1,000 test examples
+- 2 epochs
 
-- Dataset: [`somukandula/maskara-synthetic-pii`](https://huggingface.co/datasets/somukandula/maskara-synthetic-pii)
-- Generator: `scripts/generate_synthetic_dataset.py`
-- Train split: 800 examples
-- Validation split: 120 examples
-- Test split: 120 examples
-- Locales: `en-US`, `en-IN`, `en-GB`
-- Domains: chat prompts, email drafts, support tickets, delivery prompts,
-  finance prompts, JSON snippets, code/log snippets, calendar messages, and
-  hard negatives
+Sources:
 
-The dataset uses fake identities, reserved example domains, and payment
-processor test-card-style values. It does not contain real user vault data.
+- Maskara synthetic v2 prompt/data generator
+- Public PII examples normalized from `ai4privacy/pii-masking-300k`
 
-## Training Procedure
+The generator covers chat prompts, email drafts, support tickets, delivery
+messages, JSON snippets, code/log snippets, identity prompts, finance prompts,
+calendar messages, travel/map requests, and hard negatives.
 
-The checked-in model was trained locally on CPU with a simple online perceptron
-token classifier.
+## Training Command
 
 ```bash
-python scripts/generate_synthetic_dataset.py --output-dir data/synthetic
-python scripts/train_token_perceptron.py \
-  --data-dir data/synthetic \
-  --output maskara/models/pii_token_perceptron.json \
-  --epochs 10
+python scripts/build_extensive_pii_dataset.py \
+  --output-dir data/extensive \
+  --synthetic-size 50000 \
+  --public-sample-size 50000
+
+python scripts/train_transformer_pii_model.py \
+  --data-dir data/extensive \
+  --base-model google/bert_uncased_L-2_H-128_A-2 \
+  --output-dir outputs/maskara-transformer \
+  --epochs 2 \
+  --batch-size 64 \
+  --max-train-samples 30000 \
+  --max-eval-samples 1000
 ```
 
-Training features include token text, lowercase form, prefixes, suffixes,
-token shape, neighboring tokens, title-case flags, digit flags, `@`, and dash
-signals.
-
 ## Evaluation
 
-Validation metrics from the local training run:
-
-| Metric | Value |
-|---|---:|
-| Token accuracy | 0.9976 |
-| Span precision | 0.9712 |
-| Span recall | 0.9890 |
-| Span F1 | 0.9800 |
-
-End-to-end Maskara leakage evaluation on the synthetic test split:
+Held-out test metrics from the final run:
 
 | Metric | Value |
 |---|---:|
-| Examples | 120 |
-| Cloud leakage rate | 0.0 |
-| p95 protection latency | ~1.35 ms |
+| Span precision | 0.6761 |
+| Span recall | 0.6948 |
+| Span F1 | 0.6853 |
+| Token accuracy | 0.9303 |
+| Eval loss | 0.3250 |
 
-These numbers are from synthetic data and should not be interpreted as
-production guarantees. The detector is an MVP baseline for local development.
+These are honest first-checkpoint metrics, not inflated benchmark claims. This
+model is now a real ML baseline, and the next quality step is to train longer
+on the full 75K corpus or run paid HF Jobs/GPU training on the 1M+ OpenPII
+datasets.
 
 ## Usage
 
-Install the local SDK from the Maskara repository, then:
-
 ```python
-from maskara import Maskara
-
-maskara = Maskara()
-
-prompt = "Draft a reply to Maya Rao at maya.rao@example.org."
-protected, ctx = maskara.protect(prompt)
+from transformers import AutoTokenizer, AutoModelForTokenClassification, pipeline
 
-# Send `protected` to your LLM provider.
-# Then restore the provider response locally:
-final = maskara.restore(protected, ctx)
-```
+model_id = "somukandula/maskara"
 
-Direct model inference from this repo's artifact:
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+model = AutoModelForTokenClassification.from_pretrained(model_id)
 
-```python
-from maskara.ml import PerceptronPiiDetector
+detector = pipeline(
+    "token-classification",
+    model=model,
+    tokenizer=tokenizer,
+    aggregation_strategy="simple",
+)
 
-detector = PerceptronPiiDetector("pii_token_perceptron.json")
-spans = detector.detect("Email Maya Rao at maya.rao@example.org.")
-print(spans)
+print(detector("Email Maya Rao at maya.rao@example.org before shipping."))
 ```
 
-## Files
+## How It Helps
 
-- `pii_token_perceptron.json`: trained perceptron weights and label list
-- `labels.json`: BIO labels emitted by the model
-- `model_metadata.json`: training, dataset, and evaluation metadata
-- `eval_results.json`: validation and leakage evaluation metrics
-- `inference.py`: minimal standalone inference helper for this artifact
-- `requirements.txt`: minimal runtime requirements for standalone use
+Maskara helps developers use cloud LLMs without casually sending raw personal
+data to providers. This model handles fuzzy spans such as names, locations,
+addresses, usernames, and mixed natural-language context. In the SDK, it should
+be combined with deterministic detectors for structured high-risk values such
+as credit cards, SSNs, emails, phone numbers, API keys, private keys, JWTs, and
+connection strings.
 
 ## Limitations
 
-- This is a custom lightweight model, not a general-purpose NER model.
-- It was trained on synthetic data only.
-- It currently focuses on English examples.
-- It should be used together with deterministic detectors for structured PII.
-- It may miss real-world names, addresses, and secrets outside the synthetic
-  distribution.
-- It should not be trained on real local vault data.
+- The model is trained mostly on synthetic and normalized public PII examples.
+- It is English-focused.
+- It is a first real checkpoint; recall is not yet production-grade.
+- It should not be the only privacy layer.
+- Structured PII and secrets should still be protected by deterministic
+  validators first.
+- Do not train on real user vault data.
 
 ## Intended Use
 
-Use this model as part of local privacy middleware for LLM prompts. It is
-intended for local detection and pseudonymization workflows, not surveillance,
-identity resolution, or user profiling.
+Use this model locally inside privacy middleware, coding-agent wrappers, or LLM
+SDKs where prompts are pseudonymized before outbound provider calls.
 
-## Citation
-
-```bibtex
-@software{maskara2026,
-  title = {Maskara: Local PII Detection for Privacy-Preserving LLM Middleware},
-  author = {Maskara Contributors},
-  year = {2026},
-  url = {https://huggingface.co/somukandula/maskara}
-}
-```
+Do not use it for surveillance, identity resolution, or profiling.

config.json

@@ -0,0 +1,86 @@
+{
+  "add_cross_attention": false,
+  "architectures": [
+    "BertForTokenClassification"
+  ],
+  "attention_probs_dropout_prob": 0.1,
+  "bos_token_id": null,
+  "classifier_dropout": null,
+  "dtype": "float32",
+  "eos_token_id": null,
+  "hidden_act": "gelu",
+  "hidden_dropout_prob": 0.1,
+  "hidden_size": 128,
+  "id2label": {
+    "0": "O",
+    "1": "B-ADDRESS",
+    "2": "I-ADDRESS",
+    "3": "B-API_KEY",
+    "4": "I-API_KEY",
+    "5": "B-CREDIT_CARD",
+    "6": "I-CREDIT_CARD",
+    "7": "B-DATE_OF_BIRTH",
+    "8": "I-DATE_OF_BIRTH",
+    "9": "B-DRIVER_LICENSE",
+    "10": "I-DRIVER_LICENSE",
+    "11": "B-EMAIL",
+    "12": "I-EMAIL",
+    "13": "B-IP_ADDRESS",
+    "14": "I-IP_ADDRESS",
+    "15": "B-LOCATION",
+    "16": "I-LOCATION",
+    "17": "B-PASSWORD",
+    "18": "I-PASSWORD",
+    "19": "B-PERSON_NAME",
+    "20": "I-PERSON_NAME",
+    "21": "B-PHONE",
+    "22": "I-PHONE",
+    "23": "B-SSN",
+    "24": "I-SSN",
+    "25": "B-USERNAME",
+    "26": "I-USERNAME"
+  },
+  "initializer_range": 0.02,
+  "intermediate_size": 512,
+  "is_decoder": false,
+  "label2id": {
+    "B-ADDRESS": 1,
+    "B-API_KEY": 3,
+    "B-CREDIT_CARD": 5,
+    "B-DATE_OF_BIRTH": 7,
+    "B-DRIVER_LICENSE": 9,
+    "B-EMAIL": 11,
+    "B-IP_ADDRESS": 13,
+    "B-LOCATION": 15,
+    "B-PASSWORD": 17,
+    "B-PERSON_NAME": 19,
+    "B-PHONE": 21,
+    "B-SSN": 23,
+    "B-USERNAME": 25,
+    "I-ADDRESS": 2,
+    "I-API_KEY": 4,
+    "I-CREDIT_CARD": 6,
+    "I-DATE_OF_BIRTH": 8,
+    "I-DRIVER_LICENSE": 10,
+    "I-EMAIL": 12,
+    "I-IP_ADDRESS": 14,
+    "I-LOCATION": 16,
+    "I-PASSWORD": 18,
+    "I-PERSON_NAME": 20,
+    "I-PHONE": 22,
+    "I-SSN": 24,
+    "I-USERNAME": 26,
+    "O": 0
+  },
+  "layer_norm_eps": 1e-12,
+  "max_position_embeddings": 512,
+  "model_type": "bert",
+  "num_attention_heads": 2,
+  "num_hidden_layers": 2,
+  "pad_token_id": 0,
+  "tie_word_embeddings": true,
+  "transformers_version": "5.10.2",
+  "type_vocab_size": 2,
+  "use_cache": false,
+  "vocab_size": 30522
+}

dataset_summary.json

@@ -0,0 +1,21 @@
+{
+  "total": 75000,
+  "train": 67500,
+  "validation": 3750,
+  "test": 3750,
+  "labels": [
+    "ADDRESS",
+    "API_KEY",
+    "CREDIT_CARD",
+    "DATE_OF_BIRTH",
+    "DRIVER_LICENSE",
+    "EMAIL",
+    "IP_ADDRESS",
+    "LOCATION",
+    "PASSWORD",
+    "PERSON_NAME",
+    "PHONE",
+    "SSN",
+    "USERNAME"
+  ]
+}

maskara_training_metadata.json

@@ -0,0 +1,46 @@
+{
+  "base_model": "google/bert_uncased_L-2_H-128_A-2",
+  "labels": [
+    "O",
+    "B-ADDRESS",
+    "I-ADDRESS",
+    "B-API_KEY",
+    "I-API_KEY",
+    "B-CREDIT_CARD",
+    "I-CREDIT_CARD",
+    "B-DATE_OF_BIRTH",
+    "I-DATE_OF_BIRTH",
+    "B-DRIVER_LICENSE",
+    "I-DRIVER_LICENSE",
+    "B-EMAIL",
+    "I-EMAIL",
+    "B-IP_ADDRESS",
+    "I-IP_ADDRESS",
+    "B-LOCATION",
+    "I-LOCATION",
+    "B-PASSWORD",
+    "I-PASSWORD",
+    "B-PERSON_NAME",
+    "I-PERSON_NAME",
+    "B-PHONE",
+    "I-PHONE",
+    "B-SSN",
+    "I-SSN",
+    "B-USERNAME",
+    "I-USERNAME"
+  ],
+  "train_examples": 30000,
+  "validation_examples": 1000,
+  "test_examples": 1000,
+  "metrics": {
+    "eval_loss": 0.32501307129859924,
+    "eval_precision": 0.6761385753211366,
+    "eval_recall": 0.6948,
+    "eval_f1": 0.6853422765831524,
+    "eval_accuracy": 0.9303269147627125,
+    "eval_runtime": 1.1923,
+    "eval_samples_per_second": 838.744,
+    "eval_steps_per_second": 13.42,
+    "epoch": 2.0
+  }
+}

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:13e40e2a9eb1fd3acb8a48bc4d2f2cf1ef96d976cca1487cb7d9de0c209552ba
+size 17495980

requirements.txt

@@ -1 +1,3 @@
-maskara
+transformers
+torch
+safetensors

tokenizer_config.json

@@ -0,0 +1,15 @@
+{
+  "backend": "tokenizers",
+  "cls_token": "[CLS]",
+  "do_lower_case": true,
+  "is_local": false,
+  "local_files_only": false,
+  "mask_token": "[MASK]",
+  "model_max_length": 1000000000000000019884624838656,
+  "pad_token": "[PAD]",
+  "sep_token": "[SEP]",
+  "strip_accents": null,
+  "tokenize_chinese_chars": true,
+  "tokenizer_class": "BertTokenizer",
+  "unk_token": "[UNK]"
+}

training_args.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:43ec08ad7eef4313d7cdfe51cd602b688b733c856694e277ce686cc0fa3cc688
+size 5201