piighost: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

PIIGhost is a composable PII de-identification pipeline for LLM agents. It detects, anonymizes, and deanonymizes sensitive entities using pluggable detectors (regex, GLiNER2, spaCy, Transformers, LLM), with a LangChain middleware for LangGraph agents, TOML/JSON-driven configuration, and an HTTP client for the companion piighost-api server. The design is hexagonal: every stage is a port (an Any* runtime_checkable Protocol) with a Base* template ABC, and configuration couples to the core in one direction only.

Development Commands

uv sync                      # Install dependencies (dev group included)
make format                  # Auto-fix: ruff format + ruff check --fix
make lint                    # Blocking gate: ruff format --check + ruff check + pyrefly + bandit
uv run pytest                # Run all tests (integration tests deselected by default)
uv run pytest tests/pipeline/test_pipeline.py -k "test_name"  # Run a single test
uv run pytest -m integration # Run integration tests (load torch/gliner2/spacy)
make docs-build              # Build EN + FR docs (zensical)
make docs-watch              # Serve EN docs with live reload (docs-watch-fr for FR)

make lint is a real gate (non-mutating, fails on any issue); use make format to auto-fix. Tests marked integration load heavy optional dependencies and are excluded by the default addopts. asyncio_mode = "auto", so async tests need no decorator.

Architecture

Each pipeline stage is a package under src/piighost/components/ whose base.py holds the port (Any* Protocol) and a Base* template ABC; concrete adapters are sibling modules.

Anonymization Pipeline

AnonymizationPipeline (pipeline/base.py, extends BaseAnonymizationPipeline) runs the stages in order. Only the detector is required: the linker defaults to ExactEntityLinker, the anonymizer to Anonymizer(LabelCounterPlaceholderFactory()), and the overlap resolver to ConfidenceOverlapResolver (the render stage assumes disjoint spans); the expand, entity-resolve, override, and guard stages default to disabled.