event.go

Overview

The event.go file defines the core data models and conversion functions related to events within a session. An event represents a discrete interaction or state change in a session, encapsulating metadata, content generated by large language models (LLMs), and associated actions affecting session state or artifacts. This file primarily facilitates mapping between the internal Event representation and the external session.Event type used throughout the system, enabling seamless integration between session management and LLM response handling.

Data Structures

EventActions

EventActions models the delta changes occurring in a session as a result of an event. It captures:

• StateDelta (map[string]any): A map representing incremental updates to session state variables.

• ArtifactDelta (map[string]int64): A map containing changes to artifacts, keyed by artifact IDs with integer values representing version or count changes.

This struct corresponds directly to session.EventActions in the session package and is embedded inside the main Event struct.

Event

Event represents a single event occurrence within a session, aggregating metadata, LLM-generated content, and action deltas. It contains the following fields:

Functions

ToSessionEvent

func ToSessionEvent(event Event) *session.Event

Purpose: Converts an Event instance to a pointer to a session.Event instance.

Parameters:

• event (Event): The Event struct instance to be converted.

Returns:

• *session.Event: A pointer to a newly created session.Event populated with the corresponding data.

Description:

This function maps all fields from the local Event struct to the session.Event struct, transforming the Unix timestamp integer into a time.Time instance. It also converts embedded content and grounding metadata, and maps the internal EventActions to session.EventActions. This enables interoperability between the data model used internally and the session handling subsystem described in [Session Management](80559).

Usage Example:

e := Event{/* initialized fields */}
sessionEvent := ToSessionEvent(e)
// sessionEvent can now be used where session.Event is required

FromSessionEvent

func FromSessionEvent(event session.Event) Event

Purpose: Converts a session.Event instance back into an Event struct.

Parameters:

• event (session.Event): The session.Event to convert.

Returns:

• Event: A newly created Event struct populated from the session.Event.

Description:

This function performs the inverse of ToSessionEvent, mapping from the session package's event type back to the local Event representation. It converts the time.Time timestamp to Unix seconds, and extracts embedded LLM response data and action deltas. This supports scenarios where events are received or stored as session.Event and require conversion to the local data model for further processing or persistence.

Usage Example:

sessionEvent := session.Event{/* initialized fields */}
e := FromSessionEvent(sessionEvent)
// e can now be manipulated using Event methods and fields

Important Implementation Details

• The timestamp conversion uses time.Unix(event.Time, 0) to convert Unix epoch seconds into Go's time.Time type, which is necessary for compatibility with the session package.

• The Event struct tightly couples session event metadata with LLM-generated content (genai.Content) and grounding metadata (genai.GroundingMetadata), reflecting the integration of AI-generated data into session events as outlined in LLM Integration and Agents.

• EventActions encapsulates changes that likely affect session state and artifacts, potentially triggering updates in other components managing state persistence or artifact storage (see Artifact Management and Session Management).

• The two conversion functions ensure decoupling between internal data representations and external session APIs, facilitating modularity and clear separation of concerns.

Interaction with Other System Components

• The Event type acts as a bridge between the AI content generation layer (genai package) and session lifecycle management (session package).

• Events created or processed here are fundamental to session state tracking and event history, which influence agent behavior and workflow orchestration covered in Agent Workflow Management and Agent Execution Runner.

• The content and grounding metadata fields integrate with LLM response handling mechanisms, as part of the broader LLM Integration and Agents topic.

• State and artifact deltas represented in EventActions interact with artifact management services, including in-memory or cloud storage solutions described in Artifact Management and In-Memory Artifact Service.

• The conversions enable events to be passed seamlessly into session services (such as In-Memory Session Service or Database Session Service), which manage persistence and querying of event histories.

Diagram: Class Structure and Conversion Functions

classDiagram
class Event {
+string ID
+int64 Time
+string InvocationID
+string Branch
+string Author
+bool Partial
+[]string LongRunningToolIDs
+*Content Content
+*GroundingMetadata GroundingMetadata
+bool TurnComplete
+bool Interrupted
+string ErrorCode
+string ErrorMessage
+EventActions Actions
}
class EventActions {
+map[string]any StateDelta
+map[string]int64 ArtifactDelta
}
class session.Event {
+string ID
+time.Time Timestamp
+string InvocationID
+string Branch
+string Author
+[]string LongRunningToolIDs
+LLMResponse LLMResponse
+EventActions Actions
}
class LLMResponse {
+*Content Content
+*GroundingMetadata GroundingMetadata
+bool Partial
+bool TurnComplete
+bool Interrupted
+string ErrorCode
+string ErrorMessage
}
Event --> EventActions : contains
session.Event --> LLMResponse : contains
session.Event --> EventActions : contains
Event ..> session.Event : ToSessionEvent()
session.Event ..> Event : FromSessionEvent()

This diagram illustrates the primary data models defined in this file and their relationships, including the conversion pathways between the local Event struct and the external session.Event type used elsewhere in the system. The LLMResponse struct represents the embedded LLM content and metadata within a session.Event.

This file is a foundational component for event representation and conversion within the session lifecycle, enabling integration with LLM content and managing state and artifact changes central to the system's operation.