Exceptions reference¶

Module: piighost.exceptions

Every error the library raises derives from PIIGhostError, so one except PIIGhostError covers the whole family. Between the root and the leaves sit the grouping classes, one per subsystem, which a caller catches to react to a stage rather than to a single failure. The module depends on nothing outside the standard library, so every class imports without an optional extra, including the errors raised by components that need one.

from piighost.exceptions import PIIGhostError

PIIGhostSecurityWarning is the one name in the module outside this tree. Being a warning and not an error, it is described at the end of the page.

The hierarchy¶

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

The PIIGhostError tree, each grouping class to the left of the errors it covers.

Of the thirty-three error classes, twenty are raised by a component and thirteen exist only to be caught. ConfigError counts on both sides, a grouping class that is also raised on its own.

Data models¶

Module: piighost.models. SpanError, DetectionError, and EntityError group the validation failures of the frozen data models. Each is raised from __post_init__, so an invalid value fails at construction and never reaches a stage.

The invariants these errors enforce are in Data models, and the ports that exchange the models in Extending PIIGhost.

Detectors¶

Module: piighost.components.detector.ner. DetectorError groups two failures of BaseNERDetector, so they reach the model-backed detectors only. A regex, exact-match, composite, or chunked detector raises neither.

Both are covered in Detectors, with the max_chars and auto_chunk arguments that govern the second.

Text helpers¶

Module: piighost.text. TextError groups the failures of the word-boundary helpers and carries one subclass.

An empty fragment would yield zero-width spans a Span refuses, so the failure would otherwise surface as a SpanOrderingError far from its cause. ExactMatchDetector checks its configured values at construction, so a config typo fails at load rather than on the first message. LLMDetector does not raise it, because a model's output is untrusted, so a blank extracted value is dropped with a warning instead.

Anonymizer¶

Module: piighost.components.anonymizer. AnonymizerError groups the render stage's failures and carries one subclass.

The disjoint-span assumption behind it is in Anonymizer, and the stage that upholds it in Pipeline.

Detection overrides¶

Module: piighost.components.override. OverrideError groups the failures of the whitelist and blacklist stage and carries one subclass.

The other two conflict strategies resolve the collision instead of raising. Every [override] key is in the configuration reference.

Guard rails¶

Module: piighost.pipeline. GuardError groups the guard-stage failures and carries one subclass.

A guard raises nothing itself. It returns a verdict, and the pipeline turns a flagged one into this error, as described in Guard rails.

Integrations¶

Module: piighost.integrations. MiddlewareError groups the failures of the integration layer. The first two below come from the shared TextDeidentifier, which backs the LangChain middleware, the LlamaIndex query engine, and the Pydantic AI hooks alike. The third belongs to the LangChain middleware alone.

The three are covered in LangChain integration, with the strategies that decide whether the second is raised at all.

Crypto¶

Module: piighost.crypto. HasherError and CipherError group the constructor failures of the at-rest primitives, one subclass each.

Both fail closed at construction, so a misconfigured store never starts. What these primitives protect is in Security, and the memory backends that take them in Conversation memory.

Remote client¶

Module: piighost.integrations.client. ClientError groups the remote client's failures and carries one subclass.

The status guard is all it covers. A 2xx body missing an expected key surfaces as a KeyError, not a RemoteError. The client's methods are in API client.

Configuration¶

Module: piighost.config. ConfigError groups the load-time and build-time failures, and unlike the other grouping classes it is also raised on its own.

Catching ConfigError covers all three. Every key and every secret variable is in the configuration reference, and the piighost CLI reports the same three from validate, as described in CLI.

Errors carrying data¶

Three errors expose the values behind the failure as attributes. Every other error carries its message only.

PIIGhostSecurityWarning¶

A UserWarning, outside the PIIGhostError tree, so it never fails a call and the standard warnings filters govern it. It marks a setup that runs but keeps PII readable, so a knowing choice still works while a forgotten one is loud. Two sites emit it, both at construction.

The backend comparison is in Conversation memory, and the redactor in Observation.

See also¶

• Pipeline: the stage order the errors above follow.
• Guard rails: the verdict behind PIIRemainingError.
• LangChain integration: the strategies behind the middleware errors.
• Configuration reference: every key the configuration errors validate.
• Security: what the fail-closed choices protect against.