Change piighost's code
This page is for whoever changes the code of piighost. For each common change, it points first to the page of the domain documentation that describes the rules involved, then to the files and tests to open. Read the rule before touching the code that applies it.
Start locally
- Stack: Python 3.11 or later,
uvpackage manager. The core depends only ontyping-extensions. Everything else is an extra ofpyproject.toml(langchain,redis,gliner2,config…), andallgathers them. - Install:
uv syncat the root of the repository. - Test:
uv run pytest, thenmake lintbefore any merge. Details in Run and write tests. - Try:
uv run piighost anonymize "Write to claire.dubois@example.com". The first run downloads the catalog groupcatalog:piighost/generic. - Services: none for the tests. Redis, an SQL database or
piighost-apiare used only in operation. See Store conversations and Configure a pipeline. - Examples: standalone scripts in
examples/, run withuv run examples/<script>.py.
Find where to change
| Type of change | Read first | Then |
|---|---|---|
| Add a detector | Add or replace a component | components/detector/regex.py or components/detector/ner/spacy.py, config/models/detector_model.py, tests/components/detector/test_contract.py |
| Change how overlaps are arbitrated | Protect a message | components/overlap_resolver/, tests/components/overlap_resolver/ |
| Change the form of the placeholders | Glossary, Add or replace a component | components/placeholder/, tags.py, tests/components/placeholder/ |
| Touch the conversation or the human correction | Follow a conversation | pipeline/thread.py, tests/pipeline/test_thread.py, test_thread_hitl.py |
| Change the deny list or the allow list | Impose a deny list and an allow list | components/override/, tests/components/override/test_override.py |
| Change how tool calls are handled | Let a tool act | integrations/langchain/middleware.py (awrap_tool_call), integrations/pydantic_ai/hooks.py, tests/integrations/langchain/test_middleware.py |
| Change the stream restoration | Show a streamed reply | components/placeholder/streaming.py, tests/components/placeholder/test_streaming*.py |
| Add an acceptance test | Acceptance tests | tests/acceptance/, an AT-<need>-<n> identifier in the docstring |
| Add a configuration key | Configure a pipeline | config/models/, config/settings.py, tests/config/ |
Change the piighost command | Configure a pipeline | cli/__init__.py, tests/cli/test_cli.py |
| Add a storage or change the encryption | Store conversations | conversation_memory/, crypto/, tests/conversation_memory/ |
| Change the LangChain middleware or another integration | Plug the protection into an agent | integrations/, integrations/_deidentify.py, tests/integrations/ |
| Add a tool to the Claude Code hooks | Plug the protection into an agent | integrations/claude_code/hooks.py (_TOOL_OUTPUT_TEXT_FIELDS), tests/integrations/test_claude_code_hooks.py |
For how a contribution goes (branch, commits, review), see Contributing.