llmfy-guardrails 0.1.0

llmfy-guardrails is the guardrails plugin for llmfy: PIIGuard, a text-based PII detector/masker (PIIType, PIIStrategy, PIIDetection/PIIDetectionResult), independent of the LLM/flow layers in the core package.

How to install

# Using UV
uv add llmfy-guardrails

# Using pip
pip install llmfy-guardrails

Installing llmfy-guardrails pulls in llmfy (for the shared LLMfyException hierarchy) and pydantic automatically.

PII Guard — PERSON_NAME / ADDRESS detection

Most PIITypes are regex-based and work with no extra install. PIIType.PERSON_NAME/PIIType.ADDRESS are the exception — they're backed by an optional spaCy NER model, loaded lazily on first use:

# Using UV
uv add "llmfy-guardrails[spacy]"
uv add https://github.com/irufano/spacy_ner_pii/releases/download/v0.1.0/xx_ent_pii_sm-0.1.0-py3-none-any.whl

# Using pip
pip install "llmfy-guardrails[spacy]"
pip install https://github.com/irufano/spacy_ner_pii/releases/download/v0.1.0/xx_ent_pii_sm-0.1.0-py3-none-any.whl

xx_ent_pii_sm isn't published to PyPI, so it can't be pulled in as a normal extra — install it manually from the release wheel above.

Note that PIIGuard() defaults to detecting every PIIType, including these two — pass exclude_types=[PIIType.PERSON_NAME, PIIType.ADDRESS] if you don't want this dependency.

How to use

from llmfy_guardrails import PIIGuard, PIIStrategy, PIIType

guard = PIIGuard(exclude_types=[PIIType.PERSON_NAME, PIIType.ADDRESS])  # strategy=TOKENIZE (default)
result = guard.detect("Contact john.doe@example.com or call (555) 123-4567.")

print(result.processed_text)  # "Contact [EMAIL_1] or call [PHONE_NUMBER_1]."
restored = guard.restore(result.processed_text, result.detections)
print(restored)  # "Contact john.doe@example.com or call (555) 123-4567."

See llmfy_guardrails/example/pii_example.py for a full walkthrough of every strategy (TOKENIZE, MASK, REDACT, PARTIAL), custom types, and the NER-backed types.

Develop as Contributor

Commit message format

Commit subjects follow Conventional Commits:

<type>: <short summary>

[optional body]

• type is one of: feat, fix, refactor, chore, ci, docs, test.
• For a breaking change, prefix the subject with [breaking-changes], e.g. [breaking-changes] refactor: consolidate detection logic.
• Keep the summary in the imperative mood (e.g. "add", not "added"/"adds").
• The release workflow copies each commit's subject and body verbatim into the GitHub release changelog, so write both to be read standalone (see .github/workflows/release.yml).

Version bump rules (automatic tagging)

Every push to main is scanned by .github/workflows/auto-tag.yml, which tags a new release automatically — no manual git tag needed. The bump is decided per commit subject, in this precedence order (highest across all new commits wins):

A breaking marker always forces MAJOR regardless of type — use it deliberately when a feat or fix must ship as a major version, e.g. [breaking-changes] feat: ... or feat!: ..., both equivalent.

Build package

uv build

Manual / backfill release

Tagging is automatic (see above). To manually cut or re-run a release, use the workflow_dispatch trigger on release.yml (GitHub Actions UI → "Release & Publish" → "Run workflow", tag input vX.Y.Z) instead of pushing a tag by hand.

After deploy on local

After CI creates or moves the tag, your local tag ref may be stale. To sync:

git fetch --tags --force

The --force flag is needed because git fetch --tags alone won't update tags that already exist locally.

Package Development on local

uv sync --group dev

Check Lints

uvx ruff check --statistics . 2>&1 | tail -60