Veil 0.2.0

This release adds an agent skill: a folder of instructions that teaches an AI coding agent to use Veil. The Python package itself is unchanged from 0.1.0.

Why

An agent that opens a document has already sent it to its model. The skill teaches the agent a different order: run Veil on the file by path, read only the anonymized copy, and restore the originals into an output file it does not read back.

What's new

• skills/veil/ — an Agent Skill in plain Markdown plus one Python script. It works with any model and any runtime that can read files and run a shell command.
  • SKILL.md: the workflow, option tables and rules for handling tokens.
  • scripts/veil_tool.py: a file-based helper with check, anonymize, scan, reconstruct and session commands. It prints counts, types, offsets and scores, never the original values. Session files are written owner-only (0600), and it exits with code 2 and writes nothing if a detector cannot load.
  • references/: the CLI, profiles and custom patterns, the Python API, the LLM proxy and the HTTP API.
• docs/agent-skill/ — documentation for the skill: installation, workflow, helper script reference, choosing options, and troubleshooting.
• tests/test_skill.py — checks that the helper's output never contains an original value.

Use it

pip install "git+https://github.com/SpinettaInc/veil.git@v0.2.0"
python -m spacy download en_core_web_sm

git clone --branch v0.2.0 https://github.com/SpinettaInc/veil.git
ln -s "$PWD/veil/skills/veil" ~/.claude/skills/veil     # or your agent's skills directory

python veil/skills/veil/scripts/veil_tool.py check
python veil/skills/veil/scripts/veil_tool.py anonymize notes.txt \
    --out work/notes.anon.txt --session work/session.json
python veil/skills/veil/scripts/veil_tool.py reconstruct work/reply.md \
    --out reply.md --session work/session.json

The skill folder is not part of the installed package, so it comes from a checkout of the repository.

Notes

• The package version reported by veil version is still 0.1.0: no code under src/ changed in this release.
• The skill is a set of instructions. It cannot stop an agent that ignores it from opening the original file, and no detector finds every sensitive value.
• Veil remains alpha software, licensed under GPLv3.

Full changelog: v0.1.0...v0.2.0

Veil 0.1.0

First public release of Veil, a privacy-preserving proxy for LLMs. It detects personal data in text, replaces it with tokens ([PERSON_1]) or fake values, sends the anonymized text to the model, and restores the originals in the reply.

You:      "My SSN is 123-45-6789, help with taxes"
LLM sees: "My SSN is [SSN_1], help with taxes"
You see:  "For your SSN 123-45-6789, I recommend..."

Install

pip install "git+https://github.com/SpinettaInc/veil.git@v0.1.0"
python -m spacy download en_core_web_sm

Python 3.10 or newer. Optional extras: faker, rarity, desktop, full.

What's in it

• Detection: spaCy NER plus validated regex patterns (e-mail, phone, SSN, credit cards, IBAN, IPv4/IPv6, medical record numbers, dates, addresses), with optional Presidio in hybrid mode. Loose patterns need a cue word nearby.
• Profiles: paranoid, balanced and minimal, defined in YAML. Custom profiles can change weights and add their own regex detectors and token labels.
• Replacement modes: token, faker and semantic. One person keeps one token across spellings, titles and partial names.
• Reconstruction tolerates tokens the model rewrote (EMAIL_1, [email 1], <Email_1>).
• LLM proxy (VeilProxy) for OpenAI, Anthropic and Ollama: keeps the anonymized conversation itself, anonymizes the system prompt and any supplied history, and streams already-reconstructed text.
• Fail closed: if a requested detector cannot load, Veil raises instead of anonymizing less. Misspelt profiles and modes are errors too.
• CLI: veil anonymize, detect, score, reconstruct, stats, serve, app.
• HTTP API (veil serve) with per-session mappings, a JSONL audit log that records counts and timings only, and batch anonymization.
• Desktop app (Gradio) and a Guardrails AI validator.

Quality

CI runs lint, the test suite, a labeled precision benchmark in both detection modes with a minimum F1 of 0.95, and a randomised round-trip fuzz. On the benchmark corpus F1 is 0.96 with en_core_web_sm (0.97 in hybrid mode) and 1.00 with en_core_web_lg.

Good to know

• Only token mode round-trips unambiguously; prefer it for proxy use.
• The API server has no built-in authentication and binds to 127.0.0.1 by default.
• Detection is English-only for now.
• This is an alpha (0.x): the Python API may still change.

Licensed under the GNU General Public License v3.0. Full details are in the changelog and the docs.