| --- |
| license: cc-by-4.0 |
| base_model: nationaldesignstudio/rampart |
| base_model_relation: quantized |
| pipeline_tag: token-classification |
| library_name: mlx |
| tags: |
| - mlx |
| - mlx-swift |
| - bert |
| - token-classification |
| - pii |
| - redaction |
| - privacy |
| - minilm |
| - quantized |
| language: |
| - en |
| datasets: |
| - ai4privacy/pii-masking-openpii-1.5m |
| --- |
| |
| # rampart-mlx |
|
|
| A 4-bit **MLX** port of [`nationaldesignstudio/rampart`](https://huggingface.co/nationaldesignstudio/rampart) |
| — a tiny (~18.5M param) MiniLM-L6-H384 BERT that detects PII via a 35-label BIO |
| head (17 entity types). This version runs natively on Apple Silicon through |
| [MLX](https://github.com/ml-explore/mlx) and |
| [mlx-swift](https://github.com/ml-explore/mlx-swift) for on-device inference. |
|
|
| ## What this is |
|
|
| The upstream model ships **only** as 4-bit ONNX (`MatMulNBits` + INT8 |
| embeddings) — there is no PyTorch/safetensors checkpoint. This repo was produced |
| by recovering float weights from the ONNX graph, verifying an MLX |
| reimplementation reproduces ONNX Runtime **exactly** (100% token-label match, |
| max logit diff 1e-5), then re-quantizing natively with MLX. |
|
|
| | | Size | Token-label agreement vs ONNX-q4 | |
| |---|---|---| |
| | MLX fp32 (reconstructed) | 28 MB | 100.0% | |
| | **MLX 4-bit / group 64 (this repo)** | **11.6 MB** | 94.5% entity-type & PII-vs-O | |
|
|
| The small gap is from a *second* quantization on top of the already-q4 source |
| (true fp32 weights were never available upstream). |
|
|
| ## Files |
|
|
| - `model.safetensors` — quantized weights (MLX format: `weight`/`scales`/`biases`, 4-bit, group size 64) |
| - `config.json` — BERT config + `quantization` block (`group_size: 64`, `bits: 4`) |
| - `vocab.txt`, `tokenizer.json`, `tokenizer_config.json`, `special_tokens_map.json` |
| - `rampart_mlx.py` — `BertForTokenClassification` in MLX (the model module) |
| - `pii_rules.py` — deterministic regex/checksum layer (see below) |
| - `demo.py` — runnable end-to-end demo (neural model + deterministic layer) |
|
|
| ## Quick demo |
|
|
| ```bash |
| pip install mlx transformers huggingface_hub |
| huggingface-cli download sledgedev/rampart-mlx --local-dir rampart-mlx |
| cd rampart-mlx |
| |
| python demo.py # interactive prompt |
| python demo.py "my email is a@b.com and ssn 078-05-1120" |
| echo "card 4111 1111 1111 1111" | python demo.py |
| ``` |
|
|
| ``` |
| my email is a@b.com and ssn 078-05-1120 |
| EMAIL a@b.com ·rule |
| SSN 078-05-1120 ·rule |
| → my email is [EMAIL] and ssn [SSN] |
| ``` |
|
|
| ## The deterministic layer |
|
|
| The shipped weights are the **neural half** of Rampart only. Per the upstream |
| whitepaper, the full system pairs the model with a **deterministic layer** of |
| regexes + checksum/structural validators that is the *system of record* for the |
| classes the model alone is weak on. `pii_rules.py` reimplements that layer: |
|
|
| - **CREDIT_CARD** — 13–19 digit runs validated by the **Luhn** checksum (separator-agnostic) |
| - **SSN** — `NNN-NN-NNNN` with structural rules (rejects area `000`/`666`/`9xx`, group/serial `00`/`0000`) |
| - **EMAIL / URL / IP_ADDRESS** — pattern match (structure lives in the punctuation) |
|
|
| `demo.py` unions the model's spans with these, the deterministic layer winning on |
| overlap — so e.g. an SSN the model reads as `PHONE` is corrected to `SSN`. The |
| demo works on character offsets, so output preserves the original casing. |
|
|
| ## Usage (Swift / mlx-swift) |
|
|
| A complete mlx-swift implementation (BERT module, WordPiece tokenizer, PII span |
| extraction, and CLI) is available in the conversion project. Example output: |
|
|
| ``` |
| $ rampart-cli ./rampart-mlx "Email sarah.lee@acme.io or call (650) 555-2020. Passport A1234567." |
| EMAIL sarah.lee@acme.io |
| PHONE (650)555-2020 |
| PASSPORT a1234567 |
| ``` |
|
|
| > Note: a bare SwiftPM CLI binary can't locate MLX's Metal library; copy |
| > `mlx.metallib` (from the pip `mlx` wheel) next to the binary, or run inside an |
| > Xcode app target where Metal resources are bundled automatically. |
|
|
| ## Caveats |
|
|
| - The neural model alone is weak on SSNs/cards (it may read an SSN as `PHONE`) — |
| this matches ONNX Runtime. The bundled `pii_rules.py` deterministic layer is the |
| system of record for those classes and corrects them in `demo.py`. |
| - `demo.py` uses tokenizer character offsets, so output keeps the original casing; |
| the model itself is BERT-uncased. |
| - This repo contains the on-device **neural component**; it is not the complete |
| upstream redaction product. Use it accordingly. |
|
|
| ## Attribution |
|
|
| - Original model: [`nationaldesignstudio/rampart`](https://huggingface.co/nationaldesignstudio/rampart) (CC-BY-4.0) |
| - Base: [`nreimers/MiniLM-L6-H384-uncased`](https://huggingface.co/nreimers/MiniLM-L6-H384-uncased) |
| - Training data: [`ai4privacy/pii-masking-openpii-1.5m`](https://huggingface.co/datasets/ai4privacy/pii-masking-openpii-1.5m) |
|
|
| This derivative is released under the same **CC-BY-4.0** license. |
|
|
