Media Utils
Utility functions for media-to-text operations in Gen AI applications.
This module provides utility functions for handling media data in various formats and sources. It includes functionality for: 1. Media validation and format checking 2. Media loading from various sources (file, URL, base64, S3, Google Drive) 3. Generic string-processing helpers used by captioning flows 4. Multimodal context resolution into Attachments or text for language model requests
combine_strings(texts)
Combine multiple strings into a single string with newline separators.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
texts
|
list[str]
|
A list of strings to combine. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
A single string containing all valid strings, where each string is on a new line. |
get_media_binary(media_source, allowed_mime_types=None)
async
Retrieve media binary data from various sources.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
media_source
|
Any
|
The source of the media. |
required |
allowed_mime_types
|
list[str] | None
|
List of allowed MIME types or prefixes
forwarded to |
None
|
Returns:
| Type | Description |
|---|---|
tuple[bytes | None, str | None]
|
tuple[bytes | None, str | None]: The media binary data and filename. Filename is None when the source is raw bytes or base64 and no filename is available. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the media source format is not supported or the MIME type is not allowed. |
get_media_from_base64(media_source, allowed_mime_types=None)
Decode and validate a base64 encoded media string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
media_source
|
str
|
The base64 encoded media string to decode. |
required |
allowed_mime_types
|
list[str] | None
|
List of allowed MIME types or
prefixes forwarded to |
None
|
Returns:
| Type | Description |
|---|---|
bytes | None
|
bytes | None: The decoded media binary data if successful and valid, otherwise None. |
get_unique_non_empty_strings(texts)
Get unique non-empty strings from a list of strings and remove whitespace.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
texts
|
list[str]
|
A list of strings to combine. |
required |
Returns:
| Type | Description |
|---|---|
list[str]
|
list[str]: A list of strings where each string is not empty or whitespace-only. |
is_valid_binary_data(media_binary_data, allowed_mime_types=None)
Validate if the provided binary data represents a valid file based on MIME type.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
media_binary_data
|
bytes
|
The binary data to validate. |
required |
allowed_mime_types
|
list[str] | None
|
List of allowed MIME types or prefixes.
Each entry is matched as a prefix or exact value. When None, the default allowlist
of |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if the binary data represents a valid file based on criteria, False otherwise. |
resolve_multimodal_context(multimodal_context, allowed_mime_types=None)
async
Resolve multimodal context items into Attachments or text that can be sent to a language model.
Items are resolved in order:
1. Attachments are kept as-is.
2. Bytes are converted into Attachments.
3. Other items are loaded with get_media_binary (file path, URL, S3 URI, Google Drive URL, or base64) and
converted into Attachments. Strings that cannot be loaded are kept as text context.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
multimodal_context
|
Any
|
The multimodal context, expected to be None or a list. |
required |
allowed_mime_types
|
list[str] | None
|
MIME types or prefixes accepted when loading media from
non-bytes items, forwarded to |
None
|
Returns:
| Type | Description |
|---|---|
list[Attachment | str]
|
list[Attachment | str]: The resolved context items, or an empty list if |
Raises:
| Type | Description |
|---|---|
TypeError
|
If |