Switching this back to a draft as it needs some reviewing

In true developer fashion, I might have dived a bit too deep. Yet, this all would be very beneficial to my current project.

The problem with my earlier proposed schema is that it lacks a fundamental feature, the ability to connect raw events to each other (user message to assistant message, tool calls to the invoking user message or resulting assistant message(s), usage, etc.), very similarly to tracing functionality.

To sum up the goal, its to make mimic tracing functionality in a structured and query-able manner.

• Added spans and linkage

  • agent_conversation_messages: added parent_raw_event_id, trace_id, span_id. User rows keep the agent span; assistant rows are now attributed to the model’s generation/response span.
  • agent_tool_calls: added trace_id, span_id.

• Introduced agent_usage to record per‑response usage: model, requests, token counts, details, and trace_id/span_id. Indexed by (trace_id, created_at) and response_id.

• Configuration

  • The opt‑in flag is now structured_metadata=True (formerly structured=True).
  • Existing non‑structured behavior is unchanged.

• Necessary tests, docs, and demo are included.

This keeps the feature opt‑in while making stored conversations, tool calls, and usage easy to analyze with SQL, and ensures accurate span attribution for observability.