Errors

Structured BaseError taxonomy and reference IDs for ID Regulation pipelines.

Concrete errors subclass gllm_core.exceptions.BaseError with GLLM-DPO-* codes. Soft-fail paths construct an instance, record it once, and attach to_public_dict() without raising. Hard-fail paths raise the same instance.

DebugInfo

Bases: DebugInfo

Diagnostic schema for ID Regulation errors (extends gllm-core DebugInfo).

Attributes:

Name	Type	Description
class_name	str	Exception class name. Always present on constructed errors.
error_type	str	Type name of the original error, when one was caught.
original_message	str	Detail message of the original error, when caught.
traceback	str	Traceback of the original error, when available.

IDRegulationBaseError(message=None, *, debug_info=None, reference_id=None, context=None, recovery=None, retryable=None, exc=None)

Bases: BaseError

Abstract root for ID Regulation GLLM-DPO-* errors.

Adds occurrence reference_id, kind, context, recovery, and public payload helpers. Soft-fail and raise paths share the same concrete instances. Concrete subclasses in error_types are the metadata source of truth.

Initialize with optional overrides for message, diagnostics, and recovery.

Prefer constructing concrete subclasses directly at known call sites. Use exc= to populate sanitized debug_info; use raise ... from exc separately to set the Python exception chain.

Parameters:

Name	Type	Description	Default
message	str | None	Message overriding default_message.	None
debug_info	DebugInfo | None	Structured diagnostics.	None
reference_id	str | None	Correlation id. Defaults to a new UUID.	None
context	dict[str, Any] | None	Safe metadata.	None
recovery	RecoveryInfo | None	Instance recovery override.	None
retryable	bool | None	Override recovery["retryable"].	None
exc	BaseException | None	Cause used to build debug_info when debug_info is omitted. Defaults to None.	None

error property

Return self for call sites that previously used a payload wrapper.

to_debug_dict()

Return to_public_dict() plus sanitized debug_info for diagnostics.

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Caller payload with optional debugInfo.

to_dict()

Alias for to_public_dict() (historical name used by stage payloads).

to_public_dict()

Return the JSON-serializable public error object (camelCase keys).

Omits debug_info so diagnostic data does not leak onto caller-facing surfaces.

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Structured error payload.

with_recorded(recorded=True)

Mark this occurrence as recorded and return self.

Parameters:

Name	Type	Description	Default
recorded	bool	New recorded flag. Defaults to True.	True

Returns:

Name	Type	Description
IDRegulationBaseError	IDRegulationBaseError	This instance.

IDRegulationUnsupportedBackendError(message=None, *, debug_info=None, reference_id=None, context=None, recovery=None, retryable=None, exc=None)

Bases: IDRegulationValidationError, TypeError

Unsupported graph backend; remains catchable as TypeError for factories.

IDRegulationValidationError(message=None, *, debug_info=None, reference_id=None, context=None, recovery=None, retryable=None, exc=None)

Bases: IDRegulationBaseError, ValueError

Validation/config failure that remains catchable as ValueError.

attach_error_fields(result, error)

Merge structured error fields into an indexer-style result dict.

Parameters:

Name	Type	Description	Default
result	dict[str, Any]	Mutable indexer result payload.	required
error	IDRegulationBaseError	Structured error to attach.	required

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: The same result dict with error_message and error.

build_log_kwargs(reference_id, **extra)

Build extra= kwargs for structured logging with a reference id.

Parameters:

Name	Type	Description	Default
reference_id	str	Correlation id for this failure occurrence.	required
**extra	Any	Additional structured fields. A code key is renamed to error_code for AppJSONFormatter compatibility.	{}

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Mapping with an extra dict suitable for logger kwargs.

classify_compliance_llm_exception(exc)

Map an LLM / template exception to a compliance error code.

Parameters:

Name	Type	Description	Default
exc	Exception	Caught compliance LLM or template exception.	required

Returns:

Name	Type	Description
IDRegulationErrorCode	IDRegulationErrorCode	Best-matching compliance error code.

classify_indexer_exception(exc, *, operation='write')

Map an indexer exception to a stable code and public message.

Parameters:

Name	Type	Description	Default
exc	Exception	Caught indexer/backend exception.	required
operation	Literal['write', 'delete', 'read']	Indexer operation for transient fallback codes. Defaults to "write".	'write'

Returns:

Type	Description
tuple[IDRegulationErrorCode, str]	tuple[IDRegulationErrorCode, str]: Stable code and default public message.

classify_route_load_exception(exc)

Classify a chunker-router / assessor load failure for retryability.

Parameters:

Name	Type	Description	Default
exc	Exception	Caught load/parse exception.	required

Returns:

Type	Description
tuple[IDRegulationErrorCode, bool]	tuple[IDRegulationErrorCode, bool]: Mapped code and whether a retry may help.

digest_source(source)

Return a 12-character hex digest of a source path (never the path itself).

Parameters:

Name	Type	Description	Default
source	str	Source path or identifier.	required

Returns:

Name	Type	Description
str	str	First 12 hex characters of the SHA-256 digest.

json_decode_error_type()

Return json.JSONDecodeError without importing json at module load for typing.

log_id_regulation_error(logger, error, *, level=logging.WARNING, detail=None, exc_info=False)

Log a structured ID Regulation error with code and reference id in the message.

Parameters:

Name	Type	Description	Default
logger	Logger	Logger that receives the structured warning/error.	required
error	IDRegulationBaseError	Typed failure to log.	required
level	int	Logging level. Defaults to logging.WARNING.	WARNING
detail	str | None	Extra safe detail appended to the message. Defaults to None.	None
exc_info	bool | BaseException | None	When truthy, also emit a scrubbed traceback at DEBUG. Defaults to False.	False

map_error_code_to_route_reason(code)

Map a registry error code to its snake-case route reason value.

Parameters:

Name	Type	Description	Default
code	IDRegulationErrorCode | str	Registry enum member or GLLM-DPO-* string.	required

Returns:

Name	Type	Description
str	str	Snake-case reason used in route_decision.reasons.

map_route_reason_to_error_code(reason)

Map a route reason value to an IDRegulationErrorCode.

Parameters:

Name	Type	Description	Default
reason	str	Snake-case route reason from a route decision payload.	required

Returns:

Name	Type	Description
IDRegulationErrorCode	IDRegulationErrorCode	Matching registry code.

map_route_reasons_to_error_codes(reasons)

Map snake-case route reasons to stable error-code strings for automation.

Parameters:

Name	Type	Description	Default
reasons	list[str]	Route reason values.	required

Returns:

Type	Description
list[str]	list[str]: GLLM-DPO-* code strings in the same order.

new_reference_id()

Generate a unique correlation id for an ID Regulation failure.

record_id_regulation_failure(error, *, logger=None, level=logging.WARNING, detail=None, exc_info=False, force=False)

Record a failure once to the centralized sink (default: structured logger).

Parameters:

Name	Type	Description	Default
error	IDRegulationBaseError	Typed failure to record.	required
logger	Logger | None	Logger used when no custom sink is registered. Defaults to None.	None
level	int	Logging level for the default sink. Defaults to logging.WARNING.	WARNING
detail	str | None	Extra safe detail for the default sink. Defaults to None.	None
exc_info	bool | BaseException | None	Exception context for the default sink. Defaults to False.	False
force	bool	When True, record again even if already recorded. Defaults to False.	False

Returns:

Name	Type	Description
IDRegulationBaseError	IDRegulationBaseError	The same error marked as recorded.

register_error_catalog(types, *, by_code, by_enum, messages, retryable)

Install the concrete-class catalog into this module (called from error_types).

Parameters:

Name	Type	Description	Default
types	tuple[type[IDRegulationBaseError], ...]	Ordered concrete error classes.	required
by_code	dict[str, type[IDRegulationBaseError]]	Lookup by GLLM-DPO-* code string.	required
by_enum	dict[IDRegulationErrorCode, type[IDRegulationBaseError]]	Lookup by enum member.	required
messages	dict[IDRegulationErrorCode, str]	Default message per code.	required
retryable	dict[IDRegulationErrorCode, bool]	Retry flag per code.	required

register_failure_sink(sink)

Register or clear the centralized failure sink used by hosts.

Parameters:

Name	Type	Description	Default
sink	FailureSink | None	Callable receiving a failure record, or None to clear.	required

resolve_error_type(code)

Return the concrete error class for a registry code, loading the catalog if needed.

Parameters:

Name	Type	Description	Default
code	IDRegulationErrorCode | str	Enum member or GLLM-DPO-* string.	required

Returns:

Type	Description
type[IDRegulationBaseError]	type[IDRegulationBaseError]: Concrete class registered for code.

sanitize_context(context)

Keep only allowlisted context keys and truncate string values.

Parameters:

Name	Type	Description	Default
context	dict[str, Any] | None	Raw context mapping.	required

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Allowlisted context suitable for structured errors.