Base

Base class for safe, normalized multimodal exceptions.

`ComponentError(*, debug_info=None, _message=None, message_values=None)`

Bases: MultimodalError

Abstract family for component setup, configuration, and availability failures.

Use this family when a processor cannot be configured or a required backend or model cannot be prepared.

Example

Catch setup errors before requesting media processing.

from gllm_multimodal.exceptions import ComponentError, MediaBackendUnavailableError

try:
    raise MediaBackendUnavailableError(backend="FFmpeg")
except ComponentError as error:
    print(error.message)

Output:

The selected FFmpeg backend is unavailable. Check that it is installed, or select another backend.

`MediaError(*, debug_info=None, _message=None, message_values=None)`

Bases: MultimodalError

Abstract family for failures about media content or its source.

Use this family when a file is missing, unreadable, or unsuitable as input.

Example

Catch any media input or source error with one handler.

from gllm_multimodal.exceptions import MediaError, MediaSourceNotFoundError

try:
    raise MediaSourceNotFoundError(source_path="/data/video.mp4")
except MediaError as error:
    print(error.message)

Output:

We could not find /data/video.mp4. Check that it exists and is available to this application.

`MediaOperationError(*, debug_info=None, _message=None, message_values=None)`

Bases: MultimodalError

Abstract family for failures while an operation processes accepted input.

Use this family when decoding, extracting, or converting accepted media fails.

Example

Handle a processing failure after an input has been accepted.

from gllm_multimodal.exceptions import MediaOperationError, MediaOperationTimeoutError

try:
    raise MediaOperationTimeoutError()
except MediaOperationError as error:
    print(error.message)

Output:

Media processing exceeded its time limit. Reduce media size or adjust the processing limit.

`MultimodalError(*, debug_info=None, _message=None, message_values=None)`

Bases: BaseError

Base class for normalized, user-safe errors raised by this package.

Concrete subclasses define a stable code and complete default message. Lower-level diagnostic text is excluded by default; only allowlisted values are retained in debug_info. to_safe_dict() keeps diagnostics optional so callers can choose a compact user message or a richer debug payload. verbose() formats the sanitized payload for developer logs; str() remains the public message.

For diagnostic context, pass debug_info with operation, stage, modality, and source_kind. Optional fields include mime_type, size_bytes, and bounded media details. Unsupported fields are omitted.

Attributes:

Name	Type	Description
`reference_id`		Per-error identifier for correlation by the consuming app.

Example

Catch any error raised by the multimodal package and return its safe message to the caller.

from gllm_multimodal.exceptions import MediaInputInvalidError, MultimodalError

try:
    raise MediaInputInvalidError(valid_input="Provide media bytes.")
except MultimodalError as error:
    print(error.to_safe_dict()["message"])

Output:

No media could be loaded from the supplied input. Provide media bytes.

Initialize the safe public message and bounded diagnostics.

Parameters:

Name	Type	Description	Default
`debug_info`	`DebugInfo \| None`	Candidate diagnostic fields, filtered through the package's sanitizer.	`None`
`_message`	`str \| None`	Internal override for a more specific safe message.	`None`
`message_values`	`Mapping[str, object] \| None`	Values for placeholders in `default_message`. Missing optional fields use `optional_message_defaults`.	`None`

Raises:

Type	Description
`KeyError`	If a placeholder has no value or optional default.
`ValueError`	If a required placeholder has a blank value.

`to_safe_dict(*, include_debug_info=False)`

Return public error fields, optionally including sanitized diagnostics.

Parameters:

Name	Type	Description	Default
`include_debug_info`	`bool`	Include allowlisted media and error context for debugging. Defaults to `False` for a compact user-facing form.	`False`

Returns:

Type	Description
`dict[str, Any]`	Error code, complete safe message, and reference ID; optionally
`dict[str, Any]`	includes a freshly sanitized `debug_info` mapping.

`verbose()`

Format the public message and sanitized diagnostics for developer logs.

Returns:

Type	Description
`str`	Error class, code, reference ID, message, and allowlisted debug fields.