Media

When to use this

Use the media layer when your agent processes images, audio, video, or documents. Large inline data_base64 blobs inside messages are expensive to serialise, checkpoint, and send over the network. The media layer automatically offloads them to a dedicated store and replaces the blob with a lightweight URI reference.

Import path

from tenxgraph.storage.media import MediaOffloadPolicy, ensure_media_offloaded

MediaOffloadPolicy

An enum that controls when inline base64 data is offloaded to a BaseMediaStore.

from tenxgraph.storage.media import MediaOffloadPolicy

ensure_media_offloaded

message = await ensure_media_offloaded(
    message=my_message,
    store=media_store,
    policy=MediaOffloadPolicy.THRESHOLD,
    max_inline_bytes=50_000,
)

Inspects all ImageBlock, AudioBlock, VideoBlock, and DocumentBlock entries in a message. For any block whose media.kind == "data" and media.data_base64 is present, the function:

1. Decodes the base64 to bytes.
2. Uploads the bytes to store.
3. Replaces block.media with a new MediaRef(kind="url", url="graph://media/{key}").

The message is mutated in place and also returned. Blocks without inline data (URL or file_id references) are left unchanged.

Parameters:

BaseMediaStore

Abstract interface for media storage backends. Concrete stores implement store(), retrieve(), delete(), exists(), get_metadata(), get_direct_url(), and to_media_ref().

from tenxgraph.storage.media import BaseMediaStore

Implementations

All three are re-exported from tenxgraph.storage.media (and from tenxgraph.storage.media.storage).

Wiring media storage into the graph

from tenxgraph.storage.media import LocalFileMediaStore

media_store = LocalFileMediaStore(base_dir="./media_uploads")

app = graph.compile(
    checkpointer=my_checkpointer,
    media_store=media_store,
)

When a media_store is configured:

1. The framework calls ensure_media_offloaded() on incoming messages before they enter the graph.
2. Any blob that exceeds max_inline_bytes (default 50 KB) is uploaded and replaced with an graph://media/{key} reference URI.
3. The checkpointer stores only the lightweight URI, not the binary blob.
4. When the API serves the message back to a client, it resolves graph://media/{key} to a signed access URL.

Multimodal message construction

When sending a multimodal message to the graph, use MediaRef to reference the media:

from tenxgraph.core.state import ImageBlock, MediaRef, Message, TextBlock

# From a URL
msg = Message(
    role="user",
    content=[
        TextBlock(text="What's in this image?"),
        ImageBlock(
            media=MediaRef(kind="url", url="https://example.com/photo.jpg", mime_type="image/jpeg")
        ),
    ],
)

# From base64 (will be offloaded if media_store is configured and blob is large)
import base64
with open("chart.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

msg = Message(
    role="user",
    content=[
        TextBlock(text="Describe this chart"),
        ImageBlock(
            media=MediaRef(kind="data", data_base64=b64, mime_type="image/png")
        ),
    ],
)

MultimodalConfig

Per-agent configuration for how media is validated and delivered to the provider:

from tenxgraph.storage.media import DocumentHandling, ImageHandling, MultimodalConfig

agent = Agent(
    model="gpt-4o",
    multimodal_config=MultimodalConfig(
        image_handling=ImageHandling.BASE64,
        document_handling=DocumentHandling.EXTRACT_TEXT,
        max_image_dimension=2048,
    ),
)

Offload behaviour is not configured here. It is driven by MediaOffloadPolicy and the media_store passed to graph.compile().

MediaRefResolver

Resolves a MediaRef into the concrete content part a provider expects: it fetches graph://media/{key} references out of the media store, and can hand out signed direct URLs instead of re-uploading bytes on every turn.

from tenxgraph.storage.media import MediaRefResolver

resolver = MediaRefResolver(media_store=media_store)

# Optional: share signed URLs across processes through a cache backend
resolver = resolver.with_cache(
    cache_backend=my_redis_cache,
    expiration_seconds=3600,
    refresh_buffer_seconds=60,
)

OpenAI file helpers

For documents already uploaded through the OpenAI Files API, two helpers build the request fragments OpenAI expects:

from tenxgraph.storage.media import (
    create_openai_file_attachment,
    create_openai_file_search_tool,
)

tool = create_openai_file_search_tool(["file-abc123"])
# -> {"type": "file_search", "file_search": {...}}  — pass in the `tools` list

attachment = create_openai_file_attachment("file-abc123", tools=["file_search"])
# -> {"file_id": "file-abc123", "tools": [{"type": "file_search"}]}

create_openai_file_search_tool(file_ids) returns a tool dict for the tools parameter. create_openai_file_attachment(file_id, tools=None) returns a message attachment dict; tools defaults to ["file_search"].

Security note

ensure_media_offloaded uses base64.b64decode() with no URL-safe alphabet option. Ensure incoming data_base64 values are standard base64-encoded. The media store should validate MIME types before accepting uploads to prevent arbitrary file storage.

Common errors