llm-mask

A Python library that masks sensitive data in documents (PII, tokens, URLs, company names, etc.) using a local OpenAI-compatible LLM, and restores the original text via a saved mapping — no data leaves your infrastructure.

Installation

pip install llm-mask

Requirements

A running local LLM server with an OpenAI-compatible API, e.g. vLLM, LM Studio, or Ollama.

Quick start

from llm_mask import MaskingClient

client = MaskingClient(
    base_url="http://localhost:8001/v1",   # your LLM server
    model="local-model",
    language="ru",   # "ru" or "en"
)

text = "Привет, меня зовут Иван, работаю в Apple. Email: ivan@apple.com"

# ── mask ──────────────────────────────────────────────────────────────
masked_text, mapping = client.mask(text)
# masked_text → "Привет, меня зовут <person_1>, работаю в <company_1>. Email: <email_1>"
# mapping     → {"Иван": "<person_1>", "Apple": "<company_1>", "ivan@apple.com": "<email_1>"}

# ── unmask (no LLM call) ───────────────────────────────────────────────
original = client.unmask(masked_text, mapping)
# original → original text restored exactly

Attribute-style access also works:

result = client.mask(text)
result.masked_text
result.mapping

File & directory helpers

# Mask a file (nothing written to disk by default)
result = client.mask_file("document.md")

# Write masked file + mapping JSON to disk
result = client.mask_file(
    "document.md",
    save_masked=True,          # → document_masked.md
    save_mapping=True,         # → document_mapping.json
    mapping_dir="./mappings",
)

# Restore from files (no LLM)
original = client.unmask_file("document_masked.md", "document_mapping.json")

# Mask a whole directory
results = client.mask_directory(
    "./docs",
    pattern="*.md",
    overwrite_originals=False,          # writes *_masked.md next to originals
    mapping_store_path="./mappings.json",
)

Configuration

Entity types

Mapping file format

{
  "source_file": "document.md",
  "masked_at": "2026-03-05T14:22:00Z",
  "mapping": {
    "Apple": "<company_1>",
    "https://api.company.com": "<url_1>"
  }
}

Development

git clone https://github.com/KodakV/llm-mask
cd llm-mask
pip install -e ".[dev]"
pytest

See CONTRIBUTING.md for contribution guidelines.

License

MIT