Exceptions

Defines the normalized exceptions raised by gllm-privacy.

Every concrete error has a stable code (GLLM-PRIV-<NAME>) and a default_message. Each error also keeps the builtin ancestry of the error it replaced (ValueError, ImportError or RuntimeError), so existing except clauses keep matching.

debug_info never holds the analyzed text, request payloads, response bodies, headers, or URL query strings.

recovery says whether retrying can succeed. Remote timeout, connection, rate limit and server errors are retryable, and a rate limit or server error carries retry_after_seconds when the service sends Retry-After. Every other error keeps the {"retryable": False} default.

`BasePrivacyError(message=None, *, debug_info=None, recovery=None)`

Bases: BaseError

Root of the normalized errors raised by gllm-privacy.

This class is abstract and is never raised directly. Every concrete subclass defines its own code (GLLM-PRIV-<NAME>) and default_message.

Attributes:

Name	Type	Description
`code`	`str \| None`	Stable error code. Defined by each concrete subclass.
`default_message`	`str \| None`	Message used when no message is given. Defined by each concrete subclass.
`message`	`str`	The message of this error.
`debug_info`	`PrivacyDebugInfo`	Structured internal detail about this error.
`recovery`	`RecoveryInfo`	Whether retrying can succeed. Defaults to `{"retryable": False}`.

`BaseRemoteRecognizerError(message=None, *, debug_info=None, recovery=None)`

Bases: BasePrivacyError, RuntimeError

Base class of the errors raised when a remote NER service call fails.

This class is abstract and is never raised directly. Catch it to handle every remote recognizer failure. The original transport error is chained as __cause__, and its sanitized detail is stored in debug_info.

Attributes:

Name	Type	Description
`code`	`str \| None`	Stable error code. Defined by each concrete subclass.
`default_message`	`str \| None`	Message used when no message is given. Defined by each concrete subclass.
`message`	`str`	The message of this error.
`debug_info`	`PrivacyDebugInfo`	Structured internal detail, such as `recognizer`, `endpoint` and `status_code`.

`InvalidConfigError(message=None, *, debug_info=None, recovery=None)`

Bases: BasePrivacyError, ValueError

Raised when a recognizer, chunker or other component is given an invalid configuration.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-PRIV-INVALID-CONFIG`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`PrivacyDebugInfo`	Structured internal detail, such as `parameter`.

`InvalidInputError(message=None, *, debug_info=None, recovery=None)`

Bases: BasePrivacyError, ValueError

Raised when the input of an analyzer or anonymizer is missing or invalid.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-PRIV-INVALID-INPUT`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`PrivacyDebugInfo`	Structured internal detail, such as `parameter`.

`MissingDependencyError(message=None, *, debug_info=None, recovery=None)`

Bases: BasePrivacyError, ImportError

Raised when an optional dependency needed by a component is not installed.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-PRIV-MISSING-DEPENDENCY`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`PrivacyDebugInfo`	Structured internal detail about this error.

`ModelInferenceError(message=None, *, debug_info=None, recovery=None)`

Bases: BasePrivacyError, RuntimeError

Raised when the NER model fails while predicting entities in the text.

The original error is chained as __cause__, and its detail is stored in debug_info.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-PRIV-MODEL-INFERENCE`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`PrivacyDebugInfo`	Structured internal detail about this error.

`ModelLoadError(message=None, *, debug_info=None, recovery=None)`

Bases: BasePrivacyError, RuntimeError

Raised when the NER model, tokenizer or pipeline cannot be loaded.

The original error is chained as __cause__, and its detail is stored in debug_info.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-PRIV-MODEL-LOAD`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`PrivacyDebugInfo`	Structured internal detail about this error.

`ModelOutputError(message=None, *, debug_info=None, recovery=None)`

Bases: BasePrivacyError, ValueError

Raised when the NER model returns a result that does not match its input.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-PRIV-MODEL-OUTPUT`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`PrivacyDebugInfo`	Structured internal detail about this error.

`PrivacyDebugInfo`

Bases: DebugInfo

Structured internal detail attached to the errors raised by gllm-privacy.

Extends DebugInfo with the keys specific to privacy errors. This is a type-level contract only.

Attributes:

Name	Type	Description
`class_name`	`str`	Name of the exception class. Always present.
`error_type`	`str`	Type name of the original error, when one was caught.
`original_message`	`str`	Sanitized message of the original error, when one was caught.
`traceback`	`str`	Formatted stack frames of the original error, when one was caught.
`parameter`	`str`	Name of the input or configuration parameter involved, when applicable.
`language`	`str`	Language code involved, when applicable.
`recognizer`	`str`	Name of the recognizer class involved, when applicable.
`endpoint`	`str`	Remote endpoint as scheme, host and path only, when applicable.
`status_code`	`int`	HTTP status code returned by the remote service, when applicable.

`PrivacyRuntimeError(message=None, *, debug_info=None, recovery=None)`

Bases: BasePrivacyError, RuntimeError

Raised when an internal step of gllm-privacy fails unexpectedly.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-PRIV-RUNTIME`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`PrivacyDebugInfo`	Structured internal detail about this error.

`RemoteRecognizerAuthError(message=None, *, debug_info=None, recovery=None)`

Bases: BaseRemoteRecognizerError

Raised when the remote NER service rejects the credentials (HTTP 401 or 403). Do not retry as is.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-PRIV-REMOTE-AUTH`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`PrivacyDebugInfo`	Structured internal detail about this error.

`RemoteRecognizerConnectionError(message=None, *, debug_info=None, recovery=None)`

Bases: BaseRemoteRecognizerError

Raised when the remote NER service cannot be reached. Safe to retry.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-PRIV-REMOTE-CONNECTION`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`PrivacyDebugInfo`	Structured internal detail about this error.
`recovery`	`RecoveryInfo`	`{"retryable": True}`.

`RemoteRecognizerInvalidResponseError(message=None, *, debug_info=None, recovery=None)`

Bases: BaseRemoteRecognizerError

Raised when the remote NER service returns a response in an unexpected format.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-PRIV-REMOTE-INVALID-RESPONSE`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`PrivacyDebugInfo`	Structured internal detail about this error.

`RemoteRecognizerRateLimitError(message=None, *, debug_info=None, recovery=None)`

Bases: BaseRemoteRecognizerError

Raised when the remote NER service throttles the request (HTTP 429). Retry after a delay.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-PRIV-REMOTE-RATE-LIMIT`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`PrivacyDebugInfo`	Structured internal detail about this error.
`recovery`	`RecoveryInfo`	`{"retryable": True}`, plus `retry_after_seconds` when the service sends `Retry-After`.

`RemoteRecognizerRequestError(message=None, *, debug_info=None, recovery=None)`

Bases: BaseRemoteRecognizerError

Raised when the remote NER request fails for any other reason, such as another HTTP 4xx status.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-PRIV-REMOTE-REQUEST`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`PrivacyDebugInfo`	Structured internal detail about this error.

`RemoteRecognizerServerError(message=None, *, debug_info=None, recovery=None)`

Bases: BaseRemoteRecognizerError

Raised when the remote NER service fails on its side (HTTP 5xx). Safe to retry.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-PRIV-REMOTE-SERVER`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`PrivacyDebugInfo`	Structured internal detail about this error.
`recovery`	`RecoveryInfo`	`{"retryable": True}`, plus `retry_after_seconds` when the service sends `Retry-After`.

`RemoteRecognizerTLSError(message=None, *, debug_info=None, recovery=None)`

Bases: BaseRemoteRecognizerError

Raised when the TLS handshake with the remote NER service fails. Do not retry as is.

This covers a rejected or invalid client certificate (mTLS), and a server certificate that cannot be verified.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-PRIV-REMOTE-TLS`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`PrivacyDebugInfo`	Structured internal detail about this error.

`RemoteRecognizerTimeoutError(message=None, *, debug_info=None, recovery=None)`

Bases: BaseRemoteRecognizerError

Raised when the remote NER service does not respond within the timeout. Safe to retry.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-PRIV-REMOTE-TIMEOUT`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`PrivacyDebugInfo`	Structured internal detail about this error.
`recovery`	`RecoveryInfo`	`{"retryable": True}`.

`UnsupportedLanguageError(message=None, *, debug_info=None, recovery=None)`

Bases: BasePrivacyError, ValueError

Raised when a component is asked to process a language it does not support.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-PRIV-UNSUPPORTED-LANGUAGE`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`PrivacyDebugInfo`	Structured internal detail, such as `language`.

`UnsupportedTokenizerError(message=None, *, debug_info=None, recovery=None)`

Bases: BasePrivacyError, ValueError

Raised when a tokenizer cannot provide the character offsets needed to chunk text.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-PRIV-UNSUPPORTED-TOKENIZER`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`PrivacyDebugInfo`	Structured internal detail about this error.