PIIGhost

README EN - README FR / Documentation EN - Documentation FR

piighost is a Python library that keeps PII (personally identifiable information) from reaching a language model, while keeping the application fully functional.

The library spots PII with detectors (regex, NER, or another LLM) and replaces each value with a stable placeholder, for example john.doe@example.com becomes <<EMAIL:1>>. The model only ever works on de-identified text. When the LLM returns placeholders, piighost puts the real values back in place, the end user sees john.doe@example.com and never notices the de-identification. The same mechanism protects tool-using agents. A tool that needs the real address receives it in clear, while the LLM that decides to call it still sees only <<EMAIL:1>>.

Finally, the library keeps the mapping between a value and its placeholder across the whole conversation. If john.doe@example.com shows up again three messages later, the placeholder stays <<EMAIL:1>>, so the model can follow the thread.

[!NOTE] piighost performs reversible de-identification. Because the mapping between a value and its placeholder is kept so the data can be restored, this is pseudonymisation under the GDPR, not permanent anonymisation. The real values stay stored for the duration of the conversation and must be protected accordingly.

The LLM only sees placeholders. The tool receives the real address, the user gets a clear-text reply, and your agent code stays the same.

Quickstart

uv add piighost

De-identify a text

ExactMatchDetector de-identifies a dictionary of known values without downloading a model.

import asyncio

from piighost.components.detector import ExactMatchDetector
from piighost.pipeline import AnonymizationPipeline

detector = ExactMatchDetector({"John Doe": "PERSON", "john.doe@example.com": "EMAIL"})
pipeline = AnonymizationPipeline(detector)

result = asyncio.run(pipeline.anonymize("Write to John Doe at john.doe@example.com."))
print(result.text)  # Write to <<PERSON:1>> at <<EMAIL:1>>.

Conversations and agents (LangChain)

The middleware wraps a conversational pipeline and handles each agent turn. The LLM only sees placeholders, tools receive the real values, the user gets a clear-text reply.

uv add 'piighost[middleware]'

from langchain.agents import create_agent
from piighost.integrations.middleware import PIIAnonymizationMiddleware

# pipeline: a ThreadAnonymizationPipeline, see the conversation guide
agent = create_agent(
    model="openai:gpt-5.4",
    tools=[send_email],
    middleware=[PIIAnonymizationMiddleware(pipeline=pipeline)],
)

For a real detector, the conversational pipeline and a full LangChain example, see the Quickstart and the LangChain integration.

Documentation

• Get started: installation, quickstart, first pipeline
• How-to: basic usage, LangChain integration, ready-made detectors
• Reference: pipeline, middleware, detectors, CLI
• Concepts: why de-identify, architecture, placeholder factories, security

Project

• Contributing: contribution guide and report a bug
• Ecosystem:
  • piighost.athroniaeth.cloud: presentation site
  • piighost-api: piighost inference API
  • piighost-chat: example interface with HITL
• License: MIT