Upload folder using huggingface_hub

README.md

@@ -1,19 +1,208 @@
-# Maskara PII Token Perceptron
+---
+license: mit
+language:
+  - en
+tags:
+  - privacy
+  - pii
+  - token-classification
+  - named-entity-recognition
+  - security
+  - synthetic-data
+pipeline_tag: token-classification
+library_name: maskara
+datasets:
+  - somukandula/maskara-synthetic-pii
+metrics:
+  - precision
+  - recall
+  - f1
+model-index:
+  - name: maskara
+    results:
+      - task:
+          type: token-classification
+          name: PII span detection
+        dataset:
+          type: somukandula/maskara-synthetic-pii
+          name: Maskara Synthetic PII
+          split: validation
+        metrics:
+          - type: accuracy
+            value: 0.997638167217761
+            name: Token accuracy
+          - type: precision
+            value: 0.9712230215827338
+            name: Span precision
+          - type: recall
+            value: 0.989010989010989
+            name: Span recall
+          - type: f1
+            value: 0.9800362976406534
+            name: Span F1
+---
 
-This directory contains the first CPU-trained Maskara span model.
+# Maskara
 
-- Model type: averaged perceptron token classifier
-- Labels: BIO tags for synthetic Maskara PII entities
-- Training data: generated by `scripts/generate_synthetic_dataset.py`
-- Training command: `python scripts/train_token_perceptron.py --data-dir data/synthetic --output maskara/models/pii_token_perceptron.json --epochs 10`
+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.
 
-Validation from the local run:
+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.
 
-- Token accuracy: 0.9976
-- Span precision: 0.9712
-- Span recall: 0.9890
-- Span F1: 0.9800
+## What This Model Does
 
-This is an MVP detector intended to augment deterministic rules. Structured
-PII such as cards, emails, SSNs, phone numbers, and secrets should still be
-handled by validators and regex detectors first.
+The model predicts BIO token tags for common sensitive entities:
+
+- `PERSON_NAME`
+- `EMAIL`
+- `PHONE`
+- `ADDRESS`
+- `LOCATION`
+- `CREDIT_CARD`
+- `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:
+
+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 model improves coverage where pure regex is brittle, especially for names
+and location-like text in normal prose.
+
+## Training Data
+
+The model was trained on synthetic data generated by the Maskara repository:
+
+- 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
+
+The dataset uses fake identities, reserved example domains, and payment
+processor test-card-style values. It does not contain real user vault data.
+
+## Training Procedure
+
+The checked-in model was trained locally on CPU with a simple online perceptron
+token classifier.
+
+```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
+```
+
+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:
+
+| Metric | Value |
+|---|---:|
+| Examples | 120 |
+| Cloud leakage rate | 0.0 |
+| p95 protection latency | ~1.35 ms |
+
+These numbers are from synthetic data and should not be interpreted as
+production guarantees. The detector is an MVP baseline for local development.
+
+## 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)
+
+# Send `protected` to your LLM provider.
+# Then restore the provider response locally:
+final = maskara.restore(protected, ctx)
+```
+
+Direct model inference from this repo's artifact:
+
+```python
+from maskara.ml import PerceptronPiiDetector
+
+detector = PerceptronPiiDetector("pii_token_perceptron.json")
+spans = detector.detect("Email Maya Rao at maya.rao@example.org.")
+print(spans)
+```
+
+## Files
+
+- `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
+
+## 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.
+
+## 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.
+
+## 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}
+}
+```

eval_results.json

@@ -0,0 +1,19 @@
+{
+  "validation": {
+    "token_accuracy": 0.997638167217761,
+    "span_precision": 0.9712230215827338,
+    "span_recall": 0.989010989010989,
+    "span_f1": 0.9800362976406534
+  },
+  "synthetic_test_leakage": {
+    "examples": 120,
+    "leaked_examples": [],
+    "cloud_leakage_rate": 0.0,
+    "p95_protection_latency_ms": 1.3530830037780106
+  },
+  "notes": [
+    "Metrics are from synthetic data generated by the Maskara repo.",
+    "The model is intended to augment deterministic structured PII detectors.",
+    "These results are not production guarantees."
+  ]
+}

inference.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import json
+import math
+import re
+from pathlib import Path
+
+
+TOKEN_RE = re.compile(r"\w+|[^\w\s]", re.UNICODE)
+
+
+class MaskaraDetector:
+    def __init__(self, model_path: str = "pii_token_perceptron.json") -> None:
+        payload = json.loads(Path(model_path).read_text(encoding="utf-8"))
+        self.labels = payload["labels"]
+        self.weights = payload["weights"]
+
+    def detect(self, text: str) -> list[dict[str, object]]:
+        tokens = [
+            {"text": match.group(0), "start": match.start(), "end": match.end()}
+            for match in TOKEN_RE.finditer(text)
+        ]
+        predictions = [self._predict(tokens, index) for index in range(len(tokens))]
+        return _spans_from_tags(text, tokens, predictions)
+
+    def _predict(self, tokens: list[dict[str, object]], index: int) -> tuple[str, float]:
+        feats = _features(tokens, index)
+        scores = {
+            label: sum(self.weights.get(label, {}).get(feat, 0.0) for feat in feats)
+            for label in self.labels
+        }
+        ranked = sorted(scores.items(), key=lambda item: item[1], reverse=True)
+        label, score = ranked[0]
+        runner_up = ranked[1][1] if len(ranked) > 1 else 0.0
+        confidence = 1.0 / (1.0 + math.exp(-min(8.0, score - runner_up)))
+        return label, confidence
+
+
+def _spans_from_tags(
+    text: str, tokens: list[dict[str, object]], predictions: list[tuple[str, float]]
+) -> list[dict[str, object]]:
+    spans: list[dict[str, object]] = []
+    current_start = None
+    current_end = None
+    current_label = None
+    confidences: list[float] = []
+
+    for token, (tag, confidence) in zip(tokens, predictions):
+        if tag == "O":
+            if current_label is not None:
+                spans.append(_span(text, current_start, current_end, current_label, confidences))
+            current_start = current_end = current_label = None
+            confidences = []
+            continue
+        prefix, label = tag.split("-", 1)
+        if prefix == "B" or label != current_label:
+            if current_label is not None:
+                spans.append(_span(text, current_start, current_end, current_label, confidences))
+            current_start = int(token["start"])
+            current_label = label
+            confidences = []
+        current_end = int(token["end"])
+        confidences.append(confidence)
+
+    if current_label is not None:
+        spans.append(_span(text, current_start, current_end, current_label, confidences))
+    return [span for span in spans if span["confidence"] >= 0.60]
+
+
+def _span(text: str, start: int, end: int, label: str, confidences: list[float]) -> dict[str, object]:
+    return {
+        "start": start,
+        "end": end,
+        "text": text[start:end],
+        "label": label,
+        "confidence": sum(confidences) / max(1, len(confidences)),
+    }
+
+
+def _features(tokens: list[dict[str, object]], index: int) -> list[str]:
+    token = str(tokens[index]["text"])
+    lower = token.lower()
+    previous = str(tokens[index - 1]["text"]).lower() if index else "<BOS>"
+    next_token = str(tokens[index + 1]["text"]).lower() if index + 1 < len(tokens) else "<EOS>"
+    return [
+        "bias",
+        f"word={lower}",
+        f"prefix2={lower[:2]}",
+        f"prefix3={lower[:3]}",
+        f"suffix2={lower[-2:]}",
+        f"suffix3={lower[-3:]}",
+        f"shape={_shape(token)}",
+        f"prev={previous}",
+        f"next={next_token}",
+        f"prev+word={previous}|{lower}",
+        f"word+next={lower}|{next_token}",
+        f"is_title={token.istitle()}",
+        f"is_digit={token.isdigit()}",
+        f"has_digit={any(ch.isdigit() for ch in token)}",
+        f"has_at={'@' in token}",
+        f"has_dash={'-' in token}",
+    ]
+
+
+def _shape(token: str) -> str:
+    output = []
+    for char in token:
+        if char.isupper():
+            output.append("X")
+        elif char.islower():
+            output.append("x")
+        elif char.isdigit():
+            output.append("d")
+        else:
+            output.append(char)
+    return "".join(output)
+
+
+if __name__ == "__main__":
+    detector = MaskaraDetector()
+    print(detector.detect("Email Maya Rao at maya.rao@example.org."))

labels.json

@@ -0,0 +1,23 @@
+[
+  "B-ADDRESS",
+  "B-API_KEY",
+  "B-CREDIT_CARD",
+  "B-EMAIL",
+  "B-LOCATION",
+  "B-PASSWORD",
+  "B-PERSON_NAME",
+  "B-PHONE",
+  "B-SSN",
+  "B-USERNAME",
+  "I-ADDRESS",
+  "I-API_KEY",
+  "I-CREDIT_CARD",
+  "I-EMAIL",
+  "I-LOCATION",
+  "I-PASSWORD",
+  "I-PERSON_NAME",
+  "I-PHONE",
+  "I-SSN",
+  "I-USERNAME",
+  "O"
+]

model_metadata.json

@@ -0,0 +1,49 @@
+{
+  "model_name": "maskara",
+  "artifact": "pii_token_perceptron.json",
+  "model_type": "custom_perceptron_token_classifier",
+  "task": "pii_span_detection",
+  "language": ["en"],
+  "labels": [
+    "PERSON_NAME",
+    "EMAIL",
+    "PHONE",
+    "ADDRESS",
+    "LOCATION",
+    "CREDIT_CARD",
+    "SSN",
+    "API_KEY",
+    "USERNAME",
+    "PASSWORD"
+  ],
+  "bio_labels_file": "labels.json",
+  "dataset": {
+    "repo_id": "somukandula/maskara-synthetic-pii",
+    "train_examples": 800,
+    "validation_examples": 120,
+    "test_examples": 120,
+    "generator": "scripts/generate_synthetic_dataset.py",
+    "data_policy": "synthetic_only_no_real_user_vault_data"
+  },
+  "training": {
+    "script": "scripts/train_token_perceptron.py",
+    "epochs": 10,
+    "hardware": "local_cpu",
+    "features": [
+      "token_text",
+      "lowercase_token",
+      "prefixes",
+      "suffixes",
+      "token_shape",
+      "previous_token",
+      "next_token",
+      "titlecase_flag",
+      "digit_flags",
+      "at_sign_flag",
+      "dash_flag"
+    ]
+  },
+  "intended_sdk_use": "Run locally inside Maskara with deterministic validators and regex detectors.",
+  "hub_model_url": "https://huggingface.co/somukandula/maskara",
+  "hub_dataset_url": "https://huggingface.co/datasets/somukandula/maskara-synthetic-pii"
+}

requirements.txt

@@ -0,0 +1 @@
+maskara