anonlm-pii 0.1.5

Open-source PII anonymization agent with reproducible benchmarking for OpenAI-compatible models

AnonLM

AnonLM is an open-source Python library for LLM-based PII anonymization with reproducible benchmarking.

It provides:

• A configurable anonymization engine for OpenAI-compatible providers.
• A stable Python API for anonymize/deanonymize workflows.
• A unified CLI for anonymization and benchmark execution.
• Benchmark history artifacts for auditability and experiment tracking.

Installation

pip install anonlm-pii

For development:

python -m venv .venv
source .venv/bin/activate
pip install -e .[dev,test]

Quickstart (Python API)

from anonlm import anonymize

result = anonymize("Contact Jane Doe at [e-mail] or [phone].")
print(result.anonymized_text)
print(result.mapping_forward)
print(result.chunking.chunk_count)
print(result.chunking.chunks)
print(result.linking.link_count)

Quickstart (CLI)

# Text input
anonlm anonymize --text "Contact Jane Doe at [e-mail]"

# File input -> JSON output
anonlm anonymize --file input.txt --output output.json

# Benchmark run
anonlm benchmark run --dataset datasets/pii_mvp_dataset.csv --split dev

Configuration

Configuration precedence is:

1. Explicit CLI flags
2. Environment variables (ANONLM_*)
3. Provider defaults

Core environment variables:

Variable	Description
ANONLM_PROVIDER	openai, openrouter, groq, or custom
ANONLM_MODEL_NAME	Model identifier
ANONLM_BASE_URL	OpenAI-compatible base URL
ANONLM_API_KEY_ENV	Env var name containing API key
ANONLM_API_KEY	API key value
ANONLM_TEMPERATURE	LLM temperature
ANONLM_MAX_CHUNK_CHARS	Chunk size
ANONLM_CHUNK_OVERLAP_CHARS	Chunk overlap

Provider examples:

# OpenAI
export ANONLM_PROVIDER=openai
export ANONLM_API_KEY=sk-...

# OpenRouter
export ANONLM_PROVIDER=openrouter
export ANONLM_API_KEY=...
export ANONLM_MODEL_NAME=openai/gpt-4o-mini

# Groq
export ANONLM_PROVIDER=groq
export ANONLM_API_KEY=...
export ANONLM_MODEL_NAME=llama-3.3-70b-versatile

# Custom OpenAI-compatible endpoint
export ANONLM_PROVIDER=custom
export ANONLM_BASE_URL=https://your.endpoint/v1
export ANONLM_API_KEY=...

Benchmarking

Run benchmark with deterministic document-based splits (dev, val, final):

anonlm benchmark run --dataset datasets/pii_mvp_dataset.csv --split dev --verbose

Optional benchmark controls:

anonlm benchmark run \
  --dataset datasets/pii_mvp_dataset.csv \
  --split val \
  --history-dir runs/benchmarks \
  --threshold-f1 0.80

Artifacts:

• JSON run detail: runs/benchmarks/<timestamp>__<split>.json
• CSV summary index: runs/benchmarks/index.csv

See docs/benchmarking.md for protocol and interpretation guidelines.

Public API

• anonlm.anonymize(text: str, config: AnonLMConfig | None = None) -> AnonymizationResult
• anonlm.deanonymize(text: str, mapping_reverse: dict[str, str]) -> str
• anonlm.create_engine(config: AnonLMConfig | None = None) -> AnonymizationEngine

AnonymizationResult includes chunking metadata in result.chunking (and in result.to_dict()["chunking"]):

• chunk_count: total chunks processed
• chunks: chunk content list in processing order
• max_chunk_chars: chunk size setting used
• chunk_overlap_chars: overlap setting used

AnonymizationResult includes linking metadata in result.linking (and in result.to_dict()["linking"]):

• link_count: number of alias links applied
• links: list of applied links with type, from, to, from_canonical, to_canonical, from_token, to_token

Project status

Current status: 0.x (early API hardening). Expect minor breaking changes until 1.0.0.

Next objectives

1. Reach >90% reliability with gpt-oss-20b on the current baseline dataset (datasets/pii_mvp_dataset.csv).
2. Build a stronger benchmark dataset, likely by adapting a PII dataset from Hugging Face and normalizing it to AnonLM's benchmark format.
3. Reach >=90% reliability with gpt-oss-20b on the new dataset.

License

Apache-2.0