Référence des exceptions

Module : piighost.exceptions

Chaque erreur levée par la librairie dérive de PIIGhostError, donc un seul except PIIGhostError couvre toute la famille. Entre la racine et les feuilles se trouvent les classes de regroupement, une par sous-système, qu'un appelant attrape pour réagir à un étage plutôt qu'à une défaillance précise. Chaque classe s'importe sans extra optionnel, parce que le module ne dépend de rien en dehors de la librairie standard. C'est vrai aussi des erreurs levées par des composants qui exigent un extra.

from piighost.exceptions import PIIGhostError

PIIGhostSecurityWarning est le seul nom du module en dehors de cet arbre. Étant un avertissement et non une erreur, il est décrit en fin de page.

La hiérarchie

L'arbre PIIGhostError, chaque classe de regroupement au-dessus des erreurs qu'elle couvre.

PIIGhostError
- SpanError
  - NegativeSpanStartError
  - SpanOrderingError
- DetectionError
  - ConfidenceError
- EntityError
  - EmptyEntityError
  - MixedLabelError
- DetectorError
  - LabelMappingError
  - TextTooLongError
  - UnreadableOutputError
  - BridgePayloadError
  - BridgeSpanRangeError
- TextError
  - EmptyFragmentError
- AnonymizerError
  - OverlappingSpansError
- OverrideError
  - ConflictingOverrideError
- GuardError
  - PIIRemainingError
- MiddlewareError
  - UnrecognizableFactoryError
  - InventedPlaceholderError
  - MissingThreadIdError
- HasherError
  - EmptyPepperError
- CipherError
  - InvalidKeyLengthError
- ClientError
  - RemoteError
- ConfigError
  - ConfigFileError
  - ConfigValidationError

Sur les trente-cinq classes d'erreur, vingt-deux sont levées par un composant et treize n'existent que pour être attrapées. ConfigError compte des deux côtés, parce que c'est une classe de regroupement qui est aussi levée pour elle-même.

Modèles de données

Module : piighost.models. SpanError, DetectionError et EntityError regroupent les échecs de validation des modèles de données gelés. Chacune est levée depuis __post_init__, donc une valeur invalide échoue à la construction et n'atteint jamais un étage.

Exception	Levée par	Levée quand
`NegativeSpanStartError`	`Span.__post_init__`	`start` est négatif
`SpanOrderingError`	`Span.__post_init__`	`end` n'est pas strictement supérieur à `start`, ce qui décrit un intervalle vide ou inversé
`ConfidenceError`	`Detection.__post_init__`	`confidence` tombe hors de l'intervalle fermé 0 à 1
`EmptyEntityError`	`Entity.__post_init__`	l'entité ne regroupe aucune détection
`MixedLabelError`	`Entity.__post_init__`	les détections regroupées ne partagent pas toutes le même label

Les invariants que ces erreurs font respecter sont dans Référence des modèles de données, et les ports qui échangent les modèles dans Étendre piighost.

Détecteurs

Module : piighost.components.detector.ner. DetectorError regroupe cinq défaillances. Deux appartiennent à BaseNERDetector, et ne touchent donc que les détecteurs à modèle. Une appartient à LLMDetector, et donc aussi à LLMGuardRail. Les deux dernières appartiennent à BridgeDetector, qui contrôle chaque span que lui rend son runner au lieu de lui faire confiance. Un détecteur regex, exact-match, composite ou chunked n'en lève aucune.

Exception	Levée par	Levée quand
`LabelMappingError`	`BaseNERDetector.__init__`	deux labels externes pointent vers un même label interne, ce qui rendrait la recherche inverse ambiguë
`TextTooLongError`	`BaseNERDetector`, à la détection	un texte dépasse `max_chars` alors que `auto_chunk` est désactivé, plutôt que de n'analyser que le début du texte
`UnreadableOutputError`	`LLMDetector`, à la détection	le modèle rend une sortie que le détecteur ne sait pas lire, un JSON cassé ou un résultat sans son champ `entities`, alors que `fail_open` est désactivé
`BridgePayloadError`	`BridgeDetector`, à la détection	le runner rend un span auquel il manque un champ, ou un décalage qui n'est pas un entier. Un flottant est refusé lui aussi
`BridgeSpanRangeError`	`BridgeDetector`, à la détection	le runner rend un span vide ou inversé, qui dépasse le texte, ou, en unités UTF-16, qui coupe un caractère en deux

Les cinq sont traitées dans Détecteurs, avec les arguments max_chars et auto_chunk qui gouvernent TextTooLongError, l'argument fail_open qui gouverne UnreadableOutputError, et l'offset_unit dans laquelle se lisent les décalages du bridge.

Utilitaires de texte

Module : piighost.text. TextError regroupe les défaillances des utilitaires de frontière de mot et porte une seule sous-classe.

Exception	Levée par	Levée quand
`EmptyFragmentError`	`boundary_wrap`, `find_all_word_boundary` et `ExactMatchDetector.__init__`	le fragment cherché est vide, ce qui correspondrait à chaque position du texte

Sans cette erreur, un fragment vide produirait des spans de largeur nulle, qu'un Span refuse. La défaillance remonterait alors en SpanOrderingError, loin de sa cause. ExactMatchDetector vérifie ses valeurs configurées à la construction, donc une faute dans la config échoue au chargement plutôt qu'au premier message. LLMDetector ne la lève pas, parce que la sortie d'un modèle n'est pas fiable. Il écarte une valeur extraite vide avec un avertissement.

Anonymizer

Module : piighost.components.anonymizer. AnonymizerError regroupe les défaillances de l'étage de rendu et porte une sous-classe.

Exception	Levée par	Levée quand
`OverlappingSpansError`	`Anonymizer.render`	deux spans se chevauchent encore quand la réécriture en une passe les atteint

L'hypothèse de spans disjoints derrière cette erreur est dans Référence Anonymizer, et l'étage qui la garantit dans Pipeline.

Overrides de détection

Module : piighost.components.override. OverrideError regroupe les défaillances de l'étage de la liste à masquer et de la liste à laisser en clair, et porte une sous-classe.

Exception	Levée par	Levée quand
`ConflictingOverrideError`	`DetectionOverride.apply`	un span de la liste à masquer chevauche un span de la liste à laisser en clair sous la stratégie de conflit `raise`

Les deux autres stratégies de conflit tranchent la collision au lieu de lever. Chaque clé [override] est dans la référence de configuration.

Garde-fous

Module : piighost.pipeline. GuardError regroupe les défaillances de l'étage garde-fou et porte une sous-classe.

Exception	Levée par	Levée quand
`PIIRemainingError`	le pipeline, après l'étage garde-fou	un garde-fou renvoie un verdict signalé

Un garde-fou ne lève rien lui-même. Il renvoie un verdict, et le pipeline transforme un verdict signalé en cette erreur, comme décrit dans Garde-fous.

Intégrations

Module : piighost.integrations. MiddlewareError regroupe les défaillances de la couche d'intégration. Les deux premières ci-dessous viennent du TextDeidentifier partagé, qui porte aussi bien le middleware LangChain que le query engine LlamaIndex et les hooks Pydantic AI. La troisième appartient au seul middleware LangChain.

Exception	Levée par	Levée quand
`UnrecognizableFactoryError`	`TextDeidentifier.__init__`	le pipeline n'expose aucun recognizer de jeton, parce que sa placeholder factory n'a pas de grammaire retrouvable
`InventedPlaceholderError`	`TextDeidentifier.deanonymize` et `deanonymize_stream`	le texte restauré porte encore un jeton que le pipeline n'a jamais émis, sous la stratégie `RAISE` de placeholder inventé
`MissingThreadIdError`	le middleware LangChain et les hooks Claude Code, à chaque tour	la config LangGraph ne porte pas de `thread_id`, ou l'événement du hook pas de `session_id`

Les trois sont traitées dans Intégration LangChain, avec les stratégies qui décident si la deuxième est levée du tout.

Crypto

Module : piighost.crypto. HasherError et CipherError regroupent les défaillances de construction des primitives de chiffrement au repos, une sous-classe chacune.

Exception	Levée par	Levée quand
`EmptyPepperError`	`BaseHasher.__init__`	le poivre est vide, ce qui laisserait des PII à faible entropie attaquables par force brute
`InvalidKeyLengthError`	`AesGcmCipher.__init__`	la clé AES ne fait pas 16, 24 ou 32 octets

Les deux échouent en fermeture à la construction, donc un store mal configuré ne démarre jamais. Ce que ces primitives protègent est dans Sécurité, et les backends de mémoire qui les prennent dans Référence de la mémoire de conversation.

Client distant

Module : piighost.integrations.client. ClientError regroupe les défaillances du client distant et porte une sous-classe.

Exception	Levée par	Levée quand
`RemoteError`	`PIIGhostClient`, à chaque appel	le `piighost-api` distant répond avec un statut non-2xx

Le contrôle porte sur le statut seulement. Un corps 2xx auquel manque une clé attendue remonte en KeyError, pas en RemoteError. Les méthodes du client sont dans Client distant.

Configuration

Module : piighost.config. ConfigError regroupe les défaillances de chargement et de construction. Contrairement aux autres classes de regroupement, elle est aussi levée pour elle-même.

Exception	Levée par	Levée quand
`ConfigFileError`	`load_config`	le fichier est absent, illisible, ou du TOML ou JSON invalide, ou une référence du catalogue renvoie autre chose que du TOML
`ConfigValidationError`	`load_config`	les données analysées échouent à la validation du schéma. L'erreur emballe alors la `ValidationError` de pydantic dans la famille de la librairie
`ConfigError`	`load_pipeline`, `load_thread_pipeline`, et le `build()` d'une config de composant	le point d'entrée ne correspond pas à la section `[memory]` déclarée, une variable d'environnement de secret est absente ou malformée, ou une mémoire déclare un hasher ou un cipher mais pas les deux

Attraper ConfigError couvre les trois. Chaque clé et chaque variable de secret est dans la référence de configuration, et le CLI piighost rapporte les trois mêmes depuis validate, comme décrit dans Interface en ligne de commande.

Erreurs porteuses de données

Trois erreurs exposent les valeurs derrière la défaillance en attributs. Toutes les autres ne portent que leur message.

Exception	Attribut	Contient
`PIIRemainingError`	`detections`	les détections résiduelles derrière le signalement, vide quand le garde-fou raisonne par score et ne localise rien
`InventedPlaceholderError`	`tokens`	les jetons inventés, dans leur ordre d'apparition
`RemoteError`	`status_code`	le statut HTTP renvoyé par le serveur

`PIIGhostSecurityWarning`

PIIGhostSecurityWarning est un UserWarning, en dehors de l'arbre PIIGhostError. Il ne fait donc jamais échouer un appel, et les filtres standards de warnings le gouvernent. Il signale une configuration qui tourne mais garde les données confidentielles lisibles. Comme ce n'est qu'un avertissement, un choix assumé fonctionne encore, et un oubli reste bruyant. Deux endroits l'émettent, tous deux à la construction.

Émis par	Émis quand
`warn_plaintext`, appelé depuis `RedisConversationMemory` et `SqlAlchemyConversationMemory`	un backend persistant est construit sans hasher ni cipher, donc son store garde les données confidentielles en clair
`BaseAnonymizationPipeline.__init__`	aucun `observation_redactor` n'est posé, `trace_clear_text` est désactivé, et le tracer exporte, donc les traces enregistreraient du texte en clair

La comparaison des backends est dans Référence de la mémoire de conversation, et le masqueur dans Observation.

Voir aussi

Pipeline : l'ordre des étages que les erreurs ci-dessus suivent.
Garde-fous : le verdict derrière PIIRemainingError.
Intégration LangChain : les stratégies derrière les erreurs du middleware.
Référence de configuration : chaque clé que les erreurs de configuration valident.
Sécurité : ce que les échecs en fermeture protègent.