refactor: reorganize session management into dedicated components

Split session logic into dedicated components for better separation of
concerns
and maintainability:

- Move session code to dedicated session/ module
- Split Session class into:
  - Session: Data container with minimal public API
  - SessionManager: Handles lifecycle and state management
  - SessionApi: Handles API communication
  - SessionTelemetry: Manages event recording and OTEL integration

Key fixes:
- Proper UUID and timestamp serialization in events
- Consistent API key header handling
- Correct token cost formatting in analytics
- Proper session ID inheritance
- Tags conversion and validation
- Event counts type handling

This refactor improves code organization while maintaining backward
compatibility
through the session/__init__.py module.

Signed-off-by: Teo <[email protected]>

Author: teocns

agentops/client.py

@@ -198,47 +198,31 @@ def start_session(
         self,
         tags: Optional[List[str]] = None,
         inherited_session_id: Optional[str] = None,
-    ) -> Union[Session, None]:
-        """
-        Start a new session for recording events.
-
-        Args:
-            tags (List[str], optional): Tags that can be used for grouping or sorting later.
-                e.g. ["test_run"].
-            config: (Configuration, optional): Client configuration object
-            inherited_session_id (optional, str): assign session id to match existing Session
-        """
+    ) -> Optional[Session]:
+        """Start a new session"""
         if not self.is_initialized:
-            return
-
-        if inherited_session_id is not None:
-            try:
-                session_id = UUID(inherited_session_id)
-            except ValueError:
-                return logger.warning(f"Invalid session id: {inherited_session_id}")
-        else:
-            session_id = uuid4()
+            return None
 
-        session_tags = self._config.default_tags.copy()
-        if tags is not None:
-            session_tags.update(tags)
+        try:
+            session_id = UUID(inherited_session_id) if inherited_session_id else uuid4()
+        except ValueError:
+            return logger.warning(f"Invalid session id: {inherited_session_id}")
 
+        default_tags = list(self._config.default_tags) if self._config.default_tags else []
         session = Session(
             session_id=session_id,
-            tags=list(session_tags),
-            host_env=self.host_env,
             config=self._config,
+            tags=tags or default_tags,
+            host_env=self.host_env,
         )
 
-        if not session.is_running:
-            return logger.error("Failed to start session")
-
-        if self._pre_init_queue["agents"] and len(self._pre_init_queue["agents"]) > 0:
-            for agent_args in self._pre_init_queue["agents"]:
-                session.create_agent(name=agent_args["name"], agent_id=agent_args["agent_id"])
-            self._pre_init_queue["agents"] = []
+        if session.is_running:
+            # Process any queued agents
+            if self._pre_init_queue["agents"]:
+                for agent_args in self._pre_init_queue["agents"]:
+                    session.create_agent(name=agent_args["name"], agent_id=agent_args["agent_id"])
+                self._pre_init_queue["agents"].clear()
 
-        self._sessions.append(session)
         return session
 
     def end_session(

agentops/event.py

@@ -25,6 +25,7 @@ class Event:
     end_timestamp(str): A timestamp indicating when the event ended. Defaults to the time when this Event was instantiated.
     agent_id(UUID, optional): The unique identifier of the agent that triggered the event.
     id(UUID): A unique identifier for the event. Defaults to a new UUID.
+    session_id(UUID, optional): The unique identifier of the session that the event belongs to.
 
     foo(x=1) {
         ...
@@ -43,6 +44,7 @@ class Event:
     end_timestamp: Optional[str] = None
     agent_id: Optional[UUID] = field(default_factory=check_call_stack_for_agent_id)
     id: UUID = field(default_factory=uuid4)
+    session_id: Optional[UUID] = None
 
 
 @dataclass
@@ -105,7 +107,7 @@ class ToolEvent(Event):
 
 
 @dataclass
-class ErrorEvent:
+class ErrorEvent(Event):
     """
     For recording any errors e.g. ones related to agent execution
 
@@ -115,21 +117,31 @@ class ErrorEvent:
     code(str, optional): A code that can be used to identify the error e.g. 501.
     details(str, optional): Detailed information about the error.
     logs(str, optional): For detailed information/logging related to the error.
-    timestamp(str): A timestamp indicating when the error occurred. Defaults to the time when this ErrorEvent was instantiated.
-
     """
 
+    # Inherit common Event fields
+    event_type: str = field(default=EventType.ERROR.value)
+
+    # Error-specific fields
     trigger_event: Optional[Event] = None
     exception: Optional[BaseException] = None
     error_type: Optional[str] = None
     code: Optional[str] = None
     details: Optional[Union[str, Dict[str, str]]] = None
     logs: Optional[str] = field(default_factory=traceback.format_exc)
-    timestamp: str = field(default_factory=get_ISO_time)
 
     def __post_init__(self):
-        self.event_type = EventType.ERROR.value
+        """Process exception if provided"""
         if self.exception:
             self.error_type = self.error_type or type(self.exception).__name__
             self.details = self.details or str(self.exception)
             self.exception = None  # removes exception from serialization
+
+        # Ensure end timestamp is set
+        if not self.end_timestamp:
+            self.end_timestamp = get_ISO_time()
+
+    @property
+    def timestamp(self) -> str:
+        """Maintain backward compatibility with old code expecting timestamp"""
+        return self.init_timestamp