AgentSessionManager.Core.NormalizedEvent (AgentSessionManager v0.8.0)

Copy Markdown View Source

Represents a normalized event in the event stream.

NormalizedEvent is the canonical representation that all provider-specific events are transformed into. This ensures consistent handling across different AI providers (Anthropic, OpenAI, etc.) and provides strong ordering guarantees.

Required Fields

  • id - Unique event identifier (auto-generated if not provided)
  • type - Event type (must be a valid event type)
  • timestamp - When the event occurred
  • session_id - The session this event belongs to
  • run_id - The run this event belongs to

Ordering Fields

  • sequence_number - Monotonically increasing number for ordering
  • parent_event_id - Optional reference to a parent event (for causal ordering)

Source Tracking

  • provider - The source provider (:anthropic, :openai, :generic, etc.)
  • provider_event_id - Original event ID from the provider

Usage

# Create a normalized event
{:ok, event} = NormalizedEvent.new(%{
  type: :message_received,
  session_id: "ses_123",
  run_id: "run_456",
  data: %{content: "Hello!"},
  provider: :anthropic
})

# Serialize for storage/transmission
map = NormalizedEvent.to_map(event)

# Reconstruct from storage
{:ok, restored} = NormalizedEvent.from_map(map)

Summary

Types

t()

Functions

from_map(map)

Reconstructs a normalized event from a map.

new(attrs)

Creates a new normalized event with the given attributes.

same_context?(event1, event2)

Checks if two events belong to the same context (session and run).

to_map(event)

Converts a normalized event to a map suitable for JSON serialization.

valid?(event)

Checks if a normalized event is valid (has all required fields populated).

Types

t()

@type t() :: %AgentSessionManager.Core.NormalizedEvent{
  data: map(),
  id: String.t() | nil,
  metadata: map(),
  parent_event_id: String.t() | nil,
  provider: atom() | nil,
  provider_event_id: String.t() | nil,
  run_id: String.t() | nil,
  sequence_number: non_neg_integer() | nil,
  session_id: String.t() | nil,
  timestamp: DateTime.t() | nil,
  type: AgentSessionManager.Core.Event.event_type() | nil
}

Functions

from_map(map)

@spec from_map(map()) :: {:ok, t()} | {:error, AgentSessionManager.Core.Error.t()}

Reconstructs a normalized event from a map.

new(attrs)

@spec new(map()) :: {:ok, t()} | {:error, AgentSessionManager.Core.Error.t()}

Creates a new normalized event with the given attributes.

Required

  • :type - The event type (must be a valid event type)
  • :session_id - The session this event belongs to
  • :run_id - The run this event belongs to

Optional

  • :id - Custom ID (auto-generated if not provided)
  • :sequence_number - Sequence number for ordering
  • :parent_event_id - Parent event ID for causal ordering
  • :data - Event payload data
  • :metadata - Arbitrary metadata
  • :provider - Source provider atom
  • :provider_event_id - Original provider event ID

Examples

iex> NormalizedEvent.new(%{type: :message_received, session_id: "ses_123", run_id: "run_456"})
{:ok, %NormalizedEvent{type: :message_received, ...}}

iex> NormalizedEvent.new(%{type: :invalid_type, session_id: "ses_123", run_id: "run_456"})
{:error, %Error{code: :invalid_event_type}}

same_context?(event1, event2)

@spec same_context?(t(), t()) :: boolean()

Checks if two events belong to the same context (session and run).

to_map(event)

@spec to_map(t()) :: map()

Converts a normalized event to a map suitable for JSON serialization.

valid?(event)

@spec valid?(t()) :: boolean()

Checks if a normalized event is valid (has all required fields populated).