Exceptions

Defines the shared base exception for normalized errors raised by gllm-* libraries.

BaseError(message=None, *, debug_info=None)

Bases: Exception

Root of normalized errors raised by gllm-* libraries.

1. Every concrete subclass must define code using the format GLLM-<LIB>-<NAME> (for example, GLLM-INF-AUTH).
2. Every concrete subclass must define default_message.
3. Codes are registered at class definition and must be unique across all loaded libraries.
4. Intermediate base classes that are never raised directly must pass abstract=True in the class statement.
5. When combining BaseError with built-in exceptions, BaseError must come first, for example: class X(BaseError, ValueError).

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	DebugInfo	Structured internal detail about this error.

Initializes the error.

Parameters:

Name	Type	Description	Default
message	str | None	Message overriding default_message. Defaults to None.	None
debug_info	DebugInfo | None	Structured internal detail. Defaults to None, which results in a DebugInfo containing only class_name.	None

Raises:

Type	Description
TypeError	If neither message nor default_message is available.

__init_subclass__(abstract=False, **kwargs)

Validates and registers a concrete subclass.

Parameters:

Name	Type	Description	Default
abstract	bool	Whether the subclass is an abstract base that is never raised directly. Defaults to False.	False
**kwargs	Any	Additional class keyword arguments passed to the parent.	{}

Raises:

Type	Description
TypeError	If a concrete subclass lacks default_message, has a missing or malformed code, or reuses a code registered by another class.

__str__()

Returns the error message.

Returns:

Name	Type	Description
str	str	The error message.

DebugInfo

Bases: TypedDict

Minimum schema of the debug_info attached to a BaseError.

This is a type-level contract only; no runtime validation is performed. Libraries may add extra keys (e.g. response_detail, status_code) for their own errors.

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	Message of the original error, when one was caught.
traceback	str	Formatted traceback of the original error, when one was caught.