Multimodal Debug Info

Schemas and sanitization rules for normalized multimodal error diagnostics.

The public models in this module group media facts by modality while keeping the core DebugInfo dictionary contract. MultimodalDebugInfo validates untrusted diagnostic input, removes unsupported or unsafe values, and serializes accepted values back to a plain dictionary. The Literal aliases below define the supported labels used by both the schema and its runtime allowlists.

AudioDebugInfo

Bases: _DiagnosticModel

Sanitized properties of an audio stream.

Attributes:

Name	Type	Description
duration_seconds	float | None	Audio duration in seconds.
sample_rate_hz	int | None	Audio sampling rate in hertz.
channels	int | None	Number of audio channels.
codec	str | None	Safe identifier for the audio codec.
anomalies	list[DiagnosticAnomaly] | None	Bounded records for numeric details omitted as invalid.

record_audio_anomalies(value) classmethod

Record invalid audio numbers before normalizing them away.

Parameters:

Name	Type	Description	Default
value	object	Untrusted audio details.	required

Returns:

Type	Description
object	Audio details augmented with bounded numeric anomaly records.

validate_channels(value) classmethod

Keep only positive channel counts within the limit.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
int | None	The channel count when valid, or None otherwise.

validate_codec(value) classmethod

Keep only a safe audio codec identifier.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
str | None	The safe codec identifier, or None otherwise.

validate_duration(value) classmethod

Keep only finite, positive audio durations within the limit.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
float | None	The duration when it is finite, positive, and within the limit; otherwise, None.

validate_sample_rate(value) classmethod

Keep only supported positive audio sample rates.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
int | None	The sample rate when supported, or None otherwise.

DiagnosticAnomaly

Bases: _DiagnosticModel

A bounded explanation for a modality detail omitted during validation.

Attributes:

Name	Type	Description
field	AnomalyField	Name of the modality detail that failed validation.
reason	AnomalyReason	Stable reason code describing the validation failure.
observed_value	int | float | bool | str | None	Safe primitive value when it is finite and bounded.

validate_field(value) classmethod

Keep only names of numeric modality details.

Parameters:

Name	Type	Description	Default
value	object	Untrusted anomaly field name.	required

Returns:

Type	Description
str	The allowed field name, or unknown when unsupported.

validate_observed_value(value) classmethod

Keep a safe, bounded primitive anomaly value.

Parameters:

Name	Type	Description	Default
value	object	Untrusted observed value.	required

Returns:

Type	Description
int | float | bool | str | None	The value when it is a bounded primitive, otherwise None.

validate_reason(value) classmethod

Keep a supported anomaly reason code.

Parameters:

Name	Type	Description	Default
value	object	Untrusted anomaly reason.	required

Returns:

Type	Description
str	The supported reason, or invalid_type when unsupported.

ImageDebugInfo

Bases: _DiagnosticModel

Sanitized visual properties of an image.

Attributes:

Name	Type	Description
width	int | None	Image width in pixels.
height	int | None	Image height in pixels.
anomalies	list[DiagnosticAnomaly] | None	Bounded records for dimensions omitted as invalid.

record_dimension_anomalies(value) classmethod

Record invalid dimensions before they are omitted from normalized details.

Parameters:

Name	Type	Description	Default
value	object	Untrusted image details.	required

Returns:

Type	Description
object	Image details augmented with bounded dimension anomaly records.

validate_dimension(value) classmethod

Keep only positive pixel dimensions within the configured limit.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
int | None	The pixel dimension when valid, or None otherwise.

MediaProfileDebugInfo

Bases: _DiagnosticModel

Shared and modality-specific sanitized facts for one batch item.

Attributes:

Name	Type	Description
item_index	int | None	Zero-based position of the item in the input batch.
mime_type	str | None	Normalized MIME type detected for the item.
mime_type_source	MimeTypeSource | None	Whether the MIME type was detected or declared.
modality	MediaModality | None	Item modality, or mixed when multiple modalities apply.
size_bytes	int | None	Number of bytes in the item.
container_format	str | None	Safe identifier for the media container.
image	ImageDebugInfo | None	Image dimensions, when available.
audio	AudioDebugInfo | None	Audio stream facts, when available.
video	VideoDebugInfo | None	Video stream facts, when available.
anomalies	list[DiagnosticAnomaly] | None	Bounded records for profile values omitted as invalid.

omit_orphan_mime_source(value) classmethod

Drop MIME provenance when its associated MIME value is invalid.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
object	The input mapping with orphan MIME provenance removed when needed.

record_profile_anomalies(value) classmethod

Record invalid profile indexes and sizes before they are omitted.

Parameters:

Name	Type	Description	Default
value	object	Untrusted batch profile details.	required

Returns:

Type	Description
object	Profile details augmented with bounded numeric anomaly records.

validate_container_format(value) classmethod

Keep a safe media container identifier.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
str | None	The safe container identifier, or None otherwise.

validate_item_index(value) classmethod

Keep only non-negative, bounded batch indexes.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
int | None	The batch index when valid, or None otherwise.

validate_mime_source(value) classmethod

Keep MIME provenance only when the MIME type is valid.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
str | None	The supported MIME provenance label, or None otherwise.

validate_mime_type(value) classmethod

Normalize and validate a MIME type.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
str | None	The normalized MIME type, or None when invalid.

validate_modality(value) classmethod

Keep supported media modality labels.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
MediaModality | None	The supported modality label, or None otherwise.

validate_size(value) classmethod

Keep non-negative byte counts within the core debug-info limit.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
int | None	The byte count when valid, or None otherwise.

MultimodalDebugInfo

Bases: _DiagnosticModel

Validated multimodal diagnostics built on core's dictionary contract.

This runtime model preserves the fields defined by core DebugInfo and adds multimodal context. Call the sanitize method for untrusted partial data; it returns a plain dictionary for assignment to BaseError.debug_info. Unsupported fields are ignored, malformed optional values are omitted or replaced with their safe fallback, and text fields are redacted and length-limited before serialization. Media-specific values are grouped into image, audio, and video models; batch items use the MediaProfileDebugInfo model.

Attributes:

Name	Type	Description
class_name	str	Normalized exception class name. Required by core.
error_type	str | None	Type name of the caught error, when available.
original_message	str | None	Sanitized message from the caught error.
traceback	str | None	Sanitized traceback from the caught error.
operation	str	Operation category or concrete class-qualified method.
stage	StageName	Processing stage where the error occurred.
modality	MediaModality	Media modality associated with the operation.
source_kind	SourceKind	Kind of input source supplied to the operation.
component	str | None	Safe label for the component involved.
parameter	str | None	Safe label for the parameter involved.
mime_type	str | None	Detected or declared MIME type.
mime_type_source	MimeTypeSource | None	Whether the MIME type was detected or declared.
size_bytes	int | None	Size of the media payload.
status_code	int | None	HTTP status code from a provider response.
backend	MediaBackend | None	Media backend used by the operation.
input_kind	InputKind | None	Input representation such as bytes, URL, or path.
container_format	str | None	Media container identifier.
image	ImageDebugInfo | None	Sanitized image-specific details.
audio	AudioDebugInfo | None	Sanitized audio-specific details.
video	VideoDebugInfo | None	Sanitized video-specific details. Each modality detail may include anomalies for bounded observations omitted during field validation.
media_profiles	list[MediaProfileDebugInfo] | None	Sanitized profiles for items in a batch.
media_profiles_truncated	bool | None	Whether profiles were omitted due to limits.

Notes

Operation may be a known category or a validated class-qualified method name. Stage, modality, and source kind use their corresponding schema aliases and fall back to unknown for unsupported values.

bound_media_profiles(value) classmethod

Cap profile lists and mark truncation during direct model validation.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
object	The input mapping with its profile list capped and truncation state updated.

omit_orphan_mime_source(value) classmethod

Drop MIME provenance unless a valid MIME type is available.

Parameters:

Name	Type	Description	Default
value	object	Untrusted multimodal diagnostics.	required

Returns:

Type	Description
object	The diagnostics with orphan MIME provenance removed.

sanitize(error_class_name, supplied, *, safe_message) classmethod

Validate untrusted diagnostic details and return core's dict format.

Parameters:

Name	Type	Description	Default
error_class_name	str	Class name of the normalized exception.	required
supplied	Mapping[str, object] | MultimodalDebugInfo | None	Partial core or multimodal diagnostic mapping or model.	required
safe_message	str	Safe public error message used as a fallback.	required

Returns:

Type	Description
DebugInfo	A plain dictionary containing validated core and multimodal fields.

validate_backend(value) classmethod

Keep supported backend labels.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
MediaBackend | None	The supported backend label, or None otherwise.

validate_container_format(value) classmethod

Keep safe media container identifiers.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
str | None	The safe container identifier, or None otherwise.

validate_error_type(value, info) classmethod

Keep error type labels bounded to identifier syntax.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required
info	ValidationInfo	Previously validated fields, including the normalized exception class name.	required

Returns:

Type	Description
str | None	The bounded error type identifier, or None when invalid.

validate_input_kind(value) classmethod

Keep supported input representation labels.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
str | None	The supported input kind, or None otherwise.

validate_label(value) classmethod

Keep short safe labels for component and parameter names.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
str | None	The safe component or parameter label, or None otherwise.

validate_mime_source(value) classmethod

Keep MIME provenance labels from the supported set.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
str | None	The supported MIME provenance label, or None otherwise.

validate_mime_type(value) classmethod

Normalize and validate MIME type syntax and length.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
str | None	The normalized MIME type, or None when invalid.

validate_operation(value) classmethod

Keep known operation categories and safe class-qualified methods.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
str	The supported operation label, or the unknown marker.

validate_original_message(value, info) classmethod

Redact and bound the original diagnostic message.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required
info	ValidationInfo	Validation context containing the safe fallback message and prior fields.	required

Returns:

Type	Description
str | None	The redacted and bounded message, or None when absent or invalid.

validate_root_modality(value) classmethod

Keep supported media modality labels.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
MediaModality	The supported modality label, or the unknown marker.

validate_size(value) classmethod

Keep non-negative bounded media sizes.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
int | None	The byte count when valid, or None otherwise.

validate_source_kind(value) classmethod

Keep supported source kind labels.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
str	The supported source kind, or the unknown marker.

validate_stage(value) classmethod

Keep supported processing stage labels.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
str	The supported stage label, or the unknown marker.

validate_status_code(value) classmethod

Keep valid non-boolean HTTP status codes.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
int | None	The HTTP status code when valid, or None otherwise.

validate_traceback(value) classmethod

Redact and bound an original traceback.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
str | None	The redacted and bounded traceback, or None when absent or invalid.

VideoDebugInfo

Bases: _DiagnosticModel

Sanitized properties of a video stream.

Attributes:

Name	Type	Description
duration_seconds	float | None	Video duration in seconds.
fps	float | None	Video frame rate.
width	int | None	Video frame width in pixels.
height	int | None	Video frame height in pixels.
codec	str | None	Safe identifier for the video codec.
anomalies	list[DiagnosticAnomaly] | None	Bounded records for numeric details omitted as invalid.

record_video_anomalies(value) classmethod

Record invalid video numbers before normalizing them away.

Parameters:

Name	Type	Description	Default
value	object	Untrusted video details.	required

Returns:

Type	Description
object	Video details augmented with bounded numeric anomaly records.

validate_codec(value) classmethod

Keep only a safe video codec identifier.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
str | None	The safe codec identifier, or None otherwise.

validate_dimension(value) classmethod

Keep only positive pixel dimensions within the configured limit.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
int | None	The pixel dimension when valid, or None otherwise.

validate_duration(value) classmethod

Keep only finite, positive video durations within the limit.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
float | None	The duration when it is finite, positive, and within the limit; otherwise, None.

validate_frame_rate(value) classmethod

Keep only finite, positive frame rates within the limit.

Parameters:

Name	Type	Description	Default
value	object	Untrusted value to validate or normalize.	required

Returns:

Type	Description
float | None	The frame rate when valid, or None otherwise.