Python SDK for AI agent monitoring, LLM cost tracking, benchmarking, and more. Integrates with most LLMs and agent frameworks including CrewAI, Agno, OpenAI Agents SDK, Langchain, Autogen, AG2, and CamelAI
Python agentagentopsagents-sdkaianthropicautogencost-estimationcrewaievalsevaluation-metricsgroqlangchainllmmistralollamaopenaiopenai-agents
from __future__ import annotations
from typing import Optional, Any, ClassVar, TypedDict, Type
from abc import ABC, abstractmethod
from enum import Enum
from datetime import datetime, UTC
_registry: dict[str, Type['BaseEvent']] = {}
class SerializedEvent(TypedDict):
"""Type definition for serialized event data."""
event_type: str
status: str
timestamp: str
message: str
payload: dict[str, Any] # The original payload dict from the event
kwargs: dict[str, Any] # Class attributes that were set on the event instance
class EventStatus(Enum):
STARTED = "started"
PROGRESS = "progress"
WAITING = "waiting"
COMPLETED = "completed"
ERROR = "error"
TIMEOUT = "timeout"
class BaseEvent(ABC):
"""Abstract base event class for all operations.
Provides consistent status and message handling across all operation types.
Subclasses must define an 'event_type' class variable and can add operation-specific fields.
The message field is used for all communication - both success and error states.
When status is ERROR, the message contains the error description.
The payload field can contain structured data relevant to the operation.
The exception field can contain an exception instance for error events.
The event_type class variable identifies the specific event type for easy string matching.
"""
event_type: ClassVar[str] # Must be defined in subclasses
status: EventStatus
timestamp: datetime
payload: dict[str, Any]
exception: Optional[Exception]
_message: Optional[str] # Pre-computed message
def __init__(self, status: EventStatus, /, **kwargs) -> None:
"""Initialize with status as positional argument and any additional fields.
Args:
status: The event status (positional-only)
**kwargs: Additional fields to set as attributes including optional 'message'
"""
self.status = status
if 'timestamp' in kwargs:
self.timestamp = datetime.fromisoformat(kwargs.pop('timestamp')).astimezone(UTC)
else:
self.timestamp = datetime.now(UTC)
self.payload = kwargs.pop('payload', {})
self.exception = kwargs.pop('exception', None)
self._message = kwargs.pop('message', None) # Store pre-computed message if provided
# Set any additional fields from kwargs
for key, value in kwargs.items():
setattr(self, key, value)
@abstractmethod
def format_message(self) -> str:
"""Generate a human-readable message based on the event's status and attributes.
This method must be implemented by all subclasses to provide context-specific
messages that are generated dynamically from the event's state.
"""
pass
@property
def message(self) -> str:
"""Get the event message, using stored message if available, otherwise format dynamically."""
if self._message is not None:
return self._message
return self.format_message()
def serialize(self) -> SerializedEvent:
"""Serialize the event to a dictionary for storage or transmission.
Returns:
SerializedEvent
"""
kwargs = {}
for key, value in self.__dict__.items():
if key not in ["status", "payload", "exception", "_message"] and not key.startswith('_'):
if isinstance(value, (str, int, float, bool, list, dict, type(None))):
kwargs[key] = value # type: ignore
elif hasattr(value, 'value'): # Handle enums
kwargs[key] = value.value # type: ignore
else:
kwargs[key] = str(value)
return SerializedEvent(
event_type=self.event_type,
status=self.status.value,
timestamp=self.timestamp.isoformat(),
message=self.message,
payload=self.payload,
kwargs=kwargs,
)
def register_event(event_class: Type['BaseEvent']) -> None:
"""Register an event class in the global event registry.
Args:
event_class: The event class to register
"""
global _registry
_registry[event_class.event_type] = event_class
def deserialize_event(serialized: SerializedEvent) -> Optional[BaseEvent]:
"""Deserialize a serialized event back to a BaseEvent object.
Args:
serialized: The serialized event data
Returns:
BaseEvent instance of the appropriate type, or None if unknown event type
"""
global _registry
event_type = serialized["event_type"]
event_class = _registry.get(event_type)
if not event_class:
# TODO we could be nicer
raise ValueError(f"Unknown event type: {event_type}")
# The `kwargs` contain the class attributes from event subclasses
# The `payload` contains the original payload dict
# Pass the pre-computed `message` to preserve exact error details
# TODO we do not re-instantiate the `exception` here and rely on the precomputed message
return event_class(
EventStatus(serialized["status"]),
message=serialized["message"],
payload=serialized["payload"],
**serialized["kwargs"],
)