refactor: reorganize session management into dedicated components

[teocns]

Overview

This PR refactors the session management code to improve maintainability, testability, and separation of concerns, historically proposed in #486. The main changes include:

1. Breaking down the monolithic Session class into smaller, focused components
2. Introducing proper dependency management and initialization
3. Improving error handling and type safety
4. Maintaining backward compatibility while modernizing the codebase

Key Changes

1. New Module Structure

Created a dedicated session package with clear component separation:

• session.py - Core session data container and public API
• manager.py - Session lifecycle and state management
• api.py - API communication layer
• telemetry.py - OpenTelemetry integration
• registry.py - Active sessions tracking

2. Improved Error Event Handling

• Made ErrorEvent properly inherit from Event base class (booyah! @areibman)
• Added proper timestamp handling and inheritance
• Improved error data serialization

3. Client Simplification

• Streamlined session creation logic
• Improved tag handling
• Better type hints and return values
• Cleaner initialization flow

Implementation Details

Session Components

Each component has a single responsibility:

• Session: Data container with minimal public API
• SessionManager: Coordinates between components and manages lifecycle
• SessionAPI: Handles all HTTP communication
• SessionTelemetry: Manages OpenTelemetry integration
• Registry: Tracks active sessions

sequenceDiagram
    participant C as Client
    participant S as Session
    participant M as SessionManager
    participant A as SessionApi
    participant T as SessionTelemetry
    participant E as SessionExporter

    C->>S: start_session()
    S->>M: create()
    M->>A: create_session()
    A-->>M: jwt
    M->>T: setup()
    T->>E: init()

    C->>S: record(event)
    S->>M: record_event()
    M->>T: record_event()
    T->>E: export()
    E->>A: create_events()

Loading

[codecov]

Codecov Report

Attention: Patch coverage is 72.16495% with 108 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
agentops/session/manager.py	68.59%	20 Missing and 18 partials ⚠️
agentops/session/api.py	72.46%	14 Missing and 5 partials ⚠️
agentops/session/session.py	75.75%	7 Missing and 9 partials ⚠️
agentops/telemetry/exporters/session.py	75.00%	11 Missing and 3 partials ⚠️
agentops/session/telemetry.py	73.17%	6 Missing and 5 partials ⚠️
agentops/client.py	63.63%	3 Missing and 1 partial ⚠️
agentops/session/registry.py	66.66%	1 Missing and 3 partials ⚠️
agentops/event.py	75.00%	1 Missing and 1 partial ⚠️

Flag	Coverage Δ
unittests	38.63% <72.16%> (+1.21%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
agentops/session/__init__.py	100.00% <100.00%> (ø)
agentops/event.py	89.28% <75.00%> (-2.88%)	⬇️
agentops/client.py	66.50% <63.63%> (-0.50%)	⬇️
agentops/session/registry.py	66.66% <66.66%> (ø)
agentops/session/telemetry.py	73.17% <73.17%> (ø)
agentops/telemetry/exporters/session.py	75.00% <75.00%> (ø)
agentops/session/session.py	75.75% <75.75%> (ø)
agentops/session/api.py	72.46% <72.46%> (ø)
agentops/session/manager.py	68.59% <68.59%> (ø)

... and 2 files with indirect coverage changes

[teocns]

@the-praxs can you please review and run manual (integration) tests? 🙏
make sure this is prod-ready

[the-praxs]

@the-praxs can you please review and run manual (integration) tests? 🙏 make sure this is prod-ready

#632 is failing for both main and this PR so will have to take a look after a while.

#633 is failing for this PR which means we need to have the edge test cases for such issues.

[the-praxs]

Left comments on the failing tests for CrewAI and Autogen.

We need to fix the issue with CrewAI failing in this PR. Then we have to fix Autogen in a new PR since it's occurring on main too.

After these I think the PR is ready to be tested and merged, should the tests pass!