Where to start

In short

piighost hides the confidential data of a text before an AI model reads it, then puts the real values back in the reply. It is a Python library, with no graphical interface. It plugs into LangChain, Pydantic AI, LlamaIndex or Claude Code, or is used remotely through the piighost-api server. It is configured with a TOML or JSON file and the piighost command. The legal and technical reasons to de-identify are explained in Why de-identify?.

The path of a message:

1. The user writes a message with their real data, for example their name and email.
2. piighost finds the sensitive values, for example names, emails, phone numbers or secrets.
3. It replaces them with placeholders. A placeholder is a stand-in text, such as <<PERSON:1>>, which stays the same over the whole conversation.
4. The model replies with these placeholders.
5. piighost puts the real values back in the displayed reply.

What this domain documentation is. It describes what piighost must do. How to use it is in the technical documentation. It defines:

• the needs of each profile, that is the compliance officer, the developer, the operator and the application user.
• the rules each process follows, each with its identifier, such as BR-MSG-05.
• the acceptance tests that check each need.
• where in the code each rule applies.

Its goal. De-identifying a conversation with an LLM is still a new practice, and its rules are written down nowhere. This documentation writes them down, so that they can be discussed, checked and improved together. Anyone can propose a need or challenge a rule.

How to read it. Start with Needs by profile to find what concerns your profile. When they disagree, the code and the tests are right. The terms are defined in the glossary.

I want to understand…

Why piighost works this way

Each rule follows from a design decision. The Design decisions page explains them in the order they arose, with an example for each.

• De-identify a text:
  • DEC-01 DEC-01 Design decisions Replace each confidential value with a placeholder: Replace each confidential value with a placeholder.
  • DEC-02 DEC-02 Design decisions Find each value and its exact position: Find each value and its exact position.
  • DEC-03 DEC-03 Design decisions Wrap each placeholder in << and >>: Wrap each placeholder in << and >>.
  • DEC-04 DEC-04 Design decisions Say in the placeholder what type of data it stands for: Say in the placeholder what type of data it stands for.
  • DEC-05 DEC-05 Design decisions Give each entity its own identifier: Give each entity its own identifier.
  • DEC-06 DEC-06 Design decisions Group the detections of the same entity: Group the detections of the same entity.
  • DEC-07 DEC-07 Design decisions Keep a single span when two detections overlap: Keep a single span when two detections overlap.
  • DEC-08 DEC-08 Design decisions Keep the mapping to restore the real values: Keep the mapping to restore the real values.
  • DEC-09 DEC-09 Design decisions Let people correct the detection: Let people correct the detection.
  • DEC-10 DEC-10 Design decisions Reread the protected text before sending, as an option: Reread the protected text before sending, as an option.
• Hold a conversation:
  • DEC-11 DEC-11 Design decisions Keep the same placeholder for the whole conversation: Keep the same placeholder for the whole conversation.
  • DEC-12 DEC-12 Design decisions Require the conversation identifier: Require the conversation identifier.
  • DEC-13 DEC-13 Design decisions Neutralize a placeholder typed by the user: Neutralize a placeholder typed by the user.
  • DEC-14 DEC-14 Design decisions Refuse a placeholder the model made up: Refuse a placeholder the model made up.
  • DEC-15 DEC-15 Design decisions Leave unmasked a value the assistant mentions first: Leave unmasked a value the assistant mentions first.
• Let an agent act:
  • DEC-16 DEC-16 Design decisions Give the real value to tools, and the placeholder to the model: Give the real value to tools, and the placeholder to the model.
  • DEC-17 DEC-17 Design decisions Restore the reply while it arrives: Restore the reply while it arrives.
• Go to production:
  • DEC-18 DEC-18 Design decisions Protect the stored memory: Protect the stored memory.
  • DEC-19 DEC-19 Design decisions Prefer protection over availability: Prefer protection over availability.
  • DEC-20 DEC-20 Design decisions Configure a pipeline from a file and from the catalog: Configure a pipeline from a file and from the catalog.
• The architecture:
  • DEC-21 DEC-21 Design decisions Make each step a replaceable port: Make each step a replaceable port.
  • DEC-22 DEC-22 Design decisions Make the steps that wait asynchronous: Make the steps that wait asynchronous.

Change the code

To change the code, the technical documentation says which pages to read and which files to open. See Change piighost's code.

The domain documentation groups

• Needs:
  • Needs by profile
• Processes:
  • Protect a message
  • Follow a conversation
  • Impose a deny list and an allow list
  • Let a tool act
  • Show a streamed reply
• Integrations:
  • Plug the protection into an agent and its tools
• Operations:
  • Configure a pipeline by file, catalog and command line
  • Store conversations and protect traces
• Architecture:
  • Add or replace a pipeline component
• Tests:
  • Run and write tests
  • Acceptance tests
• Reference:
  • Glossary
  • Design decisions
  • Open points

Cross-cutting watch points

1. The conversation identifier decides how placeholders are shared. A call without an identifier is refused, by LangChain, the Claude Code hooks and the server. An application that names default shares its placeholders between all its users. Only the piighost anonymize command falls back to default, to try out a single text. See Follow a conversation.
2. Correcting an old message can renumber the placeholders, and a reply of the model can then be restored with the name of another person. See Follow a conversation.
3. Real values stay stored outside the model. The model only sees placeholders, but two places keep the real values. piighost's memory keeps them in clear text if its storage is not encrypted. The history the agent records, with LangGraph or Pydantic AI, keeps the text of the messages restored. Some texts do not go through piighost either. This is the case of the result of a Claude Code tool that piighost does not read, such as Grep. It is also the case of the result of a tool whose setting sends it to the model in clear text, see Let a tool act. Encrypt the memory, and protect the agent's history as personal data. See Store conversations and Plug the protection into an agent.
4. The technical traces carry the text in clear by default. Configure a trace redactor before you send them to a third-party service. See Store conversations and protect traces.
5. Erasing a conversation does not clear the other server instances right away. The storage and the instance that receives the request are cleared. The other instances keep a copy of the values in their placeholder cache, until the lifetime of that cache ends. With no lifetime set, the copy stays until the full cache evicts it. See Store conversations.
6. An LLM detector or guard rail refuses the message when it cannot read the answer of its own LLM. The message does not leave, and the application gets an error. The fail_open setting lets the message leave without that detection or without that check. See the watch points of Needs by profile and DEC-19 DEC-19 Design decisions Prefer protection over availability.