pii-inference 0.1.1

Python bindings for privacy-filter.cpp — fast GGML PII/NER token classification

privacy-filter

Fast PII/NER detection for Python — thin bindings over privacy-filter.cpp, a minimal GGML inference engine for OpenAI's privacy-filter token-classification models.

Detect names, emails, phone numbers and other PII with precise UTF-8 byte offsets, far faster than a stock Hugging Face Transformers pipeline. The upstream pf library and ggml are statically linked into a single compiled extension via nanobind + scikit-build-core, so an installed wheel is fully self-contained.

Features

• 🔎 Entity spans with byte offsets — every detection carries start/end/score/label.
• 🧩 Merging & dedup helpers — fold token-level spans into PERSON / MONEY / ADDRESS and collapse repeats.
• 🌍 Multilingual — works on non-ASCII text, offsets stay correct.
• 📦 Self-contained wheels — one abi3 wheel per platform, no external libggml to locate.
• ⚡ Releases the GIL during inference; load a model once and reuse it.

Scope: this release is CPU-only and targets CPython 3.12+. Prebuilt wheels are published for Linux x86_64 (manylinux) and macOS arm64 (Apple Silicon).

Installation

From PyPI (coming soon)

🚧 Not yet published. Once released, install with:

pip install pii-inference

From a prebuilt wheel (GitHub Releases)

Each release attaches abi3 wheels for Linux x86_64 and macOS arm64. Grab the one for your platform:

pip install https://github.com/solipsy/pii-inference/releases/download/v0.1.0/privacy_filter-0.1.0-cp312-abi3-macosx_11_0_arm64.whl

From source

Building from source compiles the C++ engine, so you need a C++17 compiler and CMake ≥ 3.21 (CMake/Ninja are fetched automatically by the build). The upstream engine and its nested ggml are git submodules:

git clone --recursive https://github.com/solipsy/pii-inference.git
cd pii-inference
pip install .          # or: uv sync && uv pip install -e . --no-build-isolation

Already cloned without --recursive? Run git submodule update --init --recursive.

Quick start

You supply a GGUF model at runtime (it is not bundled — see Getting a model):

from privacy_filter import PrivacyFilter

text = "Contact Jane Doe at [e-mail] or [phone]."

with PrivacyFilter("model.gguf", device="cpu", n_threads=0) as pf:
    for e in pf.classify(text, threshold=0.5):
        print(f"{e.label:12} {e.score:.3f}  {e.text(text)!r}")

FIRSTNAME    0.589  'Jane'
LASTNAME     0.855  'Doe'
EMAIL        0.991  '[e-mail]'
PHONE        0.987  '[phone]'

Entity exposes .start/.end (UTF-8 byte offsets), .score, .label, and .text(source). There are also merge_entities() / dedupe_entities() post-processing helpers, tokenization, long-document windowing, and device selection.

Documentation

Full usage and API reference live in docs/privacy-filter.md:

Topic
Quick start · Detecting entities	classify, thresholds
Byte offsets & redaction	non-ASCII-safe slicing
Merging & deduplication	PERSON / MONEY / ADDRESS, dedup
Tokenization · Windowing	lower-level access
API reference	PrivacyFilter, Entity, Span, functions
Building wheels	cibuildwheel, CI

Testing

uv run pytest                                   # model-free tests
PF_TEST_MODEL=/path/to/model.gguf uv run pytest # full suite incl. classify/tokenize

Maintainers: release/publishing steps live in PUBLISHING.md.

Roadmap

• Publish to PyPI
• Windows wheel
• Optional GPU builds (CUDA / Vulkan / Metal)
• Expose per-token logits (needs a small upstream addition)

License

MIT — see LICENSE. Bindings for the upstream privacy-filter.cpp project.