Processing

Media processing exception family.

`MediaOperationConfigError(*, component, parameter, next_step, debug_info=None)`

Bases: MediaOperationError, ValueError

Report invalid or incomplete options for a media operation.

Use this when one processing call lacks a required option, such as frame timestamps, while the processor itself is configured and available.

Example

A frame extraction request omits its timestamps.

from gllm_multimodal.exceptions import MediaOperationConfigError

error = MediaOperationConfigError(
    component="Frame extraction",
    parameter="timestamps",
    next_step="Pass process_config.timestamps or call set_timestamps().",
)
print(error.message)

Output:

Frame extraction requires timestamps. Pass process_config.timestamps or call set_timestamps().

Initialize a configuration error with context and recovery guidance.

Parameters:

Name	Type	Description	Default
`component`	`str`	Name of the media operation that needs configuration.	required
`parameter`	`str`	Required option or setting that is missing or invalid.	required
`next_step`	`str`	Action for supplying or correcting the parameter.	required
`debug_info`	`DebugInfo \| None`	Optional diagnostic context, sanitized before storage.	`None`

`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.

`MediaOperationFailedError(*, task=None, reason=None, next_step=None, debug_info=None)`

Bases: MediaOperationError, RuntimeError

Report a failed media operation, including file inspection or content reading.

Use this when an accepted input cannot be processed and the cause can be summarized safely for the caller.

Example

Frame extraction fails because the decoder produces no frames.

from gllm_multimodal.exceptions import MediaOperationFailedError

error = MediaOperationFailedError(
    task="frame extraction",
    reason="the decoder produced no frames",
    next_step="Check the video file and try again.",
)
print(error.message)

Output:

The frame extraction operation failed: the decoder produced no frames. Check the video file and try again.

Initialize an operation failure with optional task guidance.

Parameters:

Name	Type	Description	Default
`task`	`str \| None`	Operation name included in the message. Defaults to `"media"`.	`None`
`reason`	`str \| None`	Safe summary of why the operation failed. Defaults to `"the cause is unknown"`.	`None`
`next_step`	`str \| None`	Suggested recovery action. Defaults to checking the input and processing options, then trying again.	`None`
`debug_info`	`DebugInfo \| None`	Optional diagnostic context, sanitized before storage.	`None`

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

Bases: MediaOperationError, TimeoutError

Report media processing that exceeded its configured time limit.

Use this when an operation starts successfully but runs past its deadline.

Example

A frame extraction job reaches its processing timeout.

from gllm_multimodal.exceptions import MediaOperationTimeoutError

error = MediaOperationTimeoutError()
print(error.message)

Output:

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

`MediaResultOperationError(*, task=None, next_step=None, debug_info=None)`

Bases: MediaOperationError, ValueError

Report a missing or invalid result from an otherwise completed operation.

Use this when a backend reports success but omits data that the caller needs.

Example

A segmentation operation returns no segment metadata.

from gllm_multimodal.exceptions import MediaResultOperationError

error = MediaResultOperationError(
    task="segmentation",
    next_step="Check that the backend returns segment metadata.",
)
print(error.message)

Output:

The segmentation result is missing or has an unexpected format. Check that the backend returns segment metadata.

Initialize an invalid result error with optional task guidance.

Parameters:

Name	Type	Description	Default
`task`	`str \| None`	Operation name included in the message. Defaults to `"media operation"`.	`None`
`next_step`	`str \| None`	Suggested recovery action. Defaults to checking the selected service or backend output, then trying again.	`None`
`debug_info`	`DebugInfo \| None`	Optional diagnostic context, sanitized before storage.	`None`