MIME Bundle Conversion for Rich Event Serialization

[ashenfad]

Provide robust, standardized serialization of agex event objects into JSON-safe dictionaries, with special handling for rich Python objects in OutputEvents.

Problem:
agex's strength is working with rich Python objects (DataFrames, Figures, etc.), but this creates serialization challenges for:

• Web UI integration (streaming events to remote UIs)
• Production observability (logging to OpenTelemetry, Datadog, etc.)
• Event storage and replay

Solution:
Add agex.events.render(event: BaseEvent) -> dict function that converts events to JSON-serializable format.

Core Behavior:

• Standard Events: Simple events → equivalent to event.model_dump()
• Rich Events (OutputEvent): Convert event.parts objects to MIME bundles using IPython/Jupyter standard
• MIME Bundles: Dict with MIME types as keys (text/plain, text/html, image/png) and data as values
• Intelligent Conversion: Leverage existing _repr_mimebundle_, _repr_html_, _repr_png_ methods

Example:

Input (Python objects):

output_event = OutputEvent(
    agent_name="data_analyst", 
    parts=[
        "Here is the dataframe:", 
        pd.DataFrame({'A': [1, 2], 'B': [3, 4]})
    ]
)

Output of render(output_event):

{
  "event_type": "OutputEvent",
  "agent_name": "data_analyst",
  "parts": [
    {"text/plain": "'Here is the dataframe:'"},
    {
      "text/plain": "   A  B\n0  1  3\n1  2  4",
      "text/html": "<div>...html table...</div>",
      "application/json": {"schema": {...}, "data": [...]}
    }
  ]
}

Benefits:

• Production Ready: Enables observability and monitoring at scale
• Standard Format: MIME bundles compatible with Jupyter ecosystem
• Multi-Representation: Same data in multiple formats for different consumers
• Graceful Degradation: Fallback to repr() for unconvertible objects

Implementation:

• Function in agex/render/value.py or similar central module
• Single source of truth for event serialization
• Used by both web UI streaming and observability hooks

Strategic Value:
Foundational infrastructure that unlocks:

• Web-based agent playgrounds
• Production monitoring dashboards
• Event replay/debugging tools
• Integration with existing observability stacks