mojentic 0.5.7__py3-none-any.whl → 0.6.0__py3-none-any.whl

mojentic/tracer/event_store.py

@@ -0,0 +1,111 @@
+from typing import Any, Callable, Dict, List, Optional, Type, Union
+import time
+from datetime import datetime
+
+from mojentic.event import Event
+from mojentic.tracer.tracer_events import TracerEvent
+
+
+class EventStore:
+    """
+    Store for capturing and querying events, particularly useful for tracer events.
+    """
+    def __init__(self, on_store_callback: Optional[Callable[[Event], None]] = None):
+        """
+        Initialize an EventStore.
+
+        Parameters
+        ----------
+        on_store_callback : Callable[[Event], None], optional
+            A callback function that will be called whenever an event is stored.
+            The callback receives the stored event as its argument.
+        """
+        self.events = []
+        self.on_store_callback = on_store_callback
+
+    def store(self, event: Event) -> None:
+        """
+        Store an event in the event store.
+
+        Parameters
+        ----------
+        event : Event
+            The event to store.
+        """
+        self.events.append(event)
+
+        # Call the callback if it exists
+        if self.on_store_callback is not None:
+            self.on_store_callback(event)
+
+    def get_events(self, 
+                  event_type: Optional[Type[Event]] = None, 
+                  start_time: Optional[float] = None,
+                  end_time: Optional[float] = None,
+                  filter_func: Optional[Callable[[Event], bool]] = None) -> List[Event]:
+        """
+        Get events from the store, optionally filtered by type, time range, and custom filter function.
+
+        Parameters
+        ----------
+        event_type : Type[Event], optional
+            Filter events by this specific event type.
+        start_time : float, optional
+            Include events with timestamp >= start_time (only applies to TracerEvent types).
+        end_time : float, optional
+            Include events with timestamp <= end_time (only applies to TracerEvent types).
+        filter_func : Callable[[Event], bool], optional
+            Custom filter function to apply to events.
+
+        Returns
+        -------
+        List[Event]
+            Events that match the filter criteria.
+        """
+        result = self.events
+
+        # Filter by event type if specified
+        if event_type is not None:
+            result = [e for e in result if isinstance(e, event_type)]
+
+        # Filter by time range if dealing with TracerEvents
+        if start_time is not None:
+            result = [e for e in result if isinstance(e, TracerEvent) and e.timestamp >= start_time]
+
+        if end_time is not None:
+            result = [e for e in result if isinstance(e, TracerEvent) and e.timestamp <= end_time]
+
+        # Apply custom filter function if provided
+        if filter_func is not None:
+            result = [e for e in result if filter_func(e)]
+
+        return result
+
+    def clear(self) -> None:
+        """
+        Clear all events from the store.
+        """
+        self.events = []
+
+    def get_last_n_events(self, n: int, event_type: Optional[Type[Event]] = None) -> List[Event]:
+        """
+        Get the last N events, optionally filtered by type.
+
+        Parameters
+        ----------
+        n : int
+            Number of events to return.
+        event_type : Type[Event], optional
+            Filter events by this specific event type.
+
+        Returns
+        -------
+        List[Event]
+            The last N events that match the filter criteria.
+        """
+        if event_type is not None:
+            filtered = [e for e in self.events if isinstance(e, event_type)]
+        else:
+            filtered = self.events
+
+        return filtered[-n:] if n < len(filtered) else filtered

mojentic/tracer/event_store_spec.py

@@ -0,0 +1,210 @@
+import time
+from typing import List
+
+from mojentic import Event
+from mojentic.tracer.tracer_events import TracerEvent, LLMCallTracerEvent, AgentInteractionTracerEvent
+from mojentic.tracer.event_store import EventStore
+
+
+class TestEvent(Event):
+    """A simple event for testing."""
+    value: int
+
+
+class TestTracerEvent(TracerEvent):
+    """A simple tracer event for testing."""
+    value: int
+
+
+class DescribeEventStore:
+    """
+    The immutable event store is key to the traceability of agent interactions.
+    """
+
+    def should_store_an_event(self):
+        """
+        Given an event
+        When asked to store the event
+        Then the event should be stored
+        """
+        # Given
+        event = Event(
+            source=DescribeEventStore,
+        )
+        event_store = EventStore()
+
+        # When
+        event_store.store(event)
+
+        # Then
+        assert event in event_store.events
+
+    def should_filter_events_by_type(self):
+        """
+        Given several events of different types
+        When filtered by a specific type
+        Then only events of that type should be returned
+        """
+        # Given
+        event_store = EventStore()
+        event1 = Event(source=DescribeEventStore)
+        event2 = TestEvent(source=DescribeEventStore, value=42)
+        event3 = TestEvent(source=DescribeEventStore, value=43)
+        event_store.store(event1)
+        event_store.store(event2)
+        event_store.store(event3)
+
+        # When
+        result = event_store.get_events(event_type=TestEvent)
+
+        # Then
+        assert len(result) == 2
+        assert event1 not in result
+        assert event2 in result
+        assert event3 in result
+
+    def should_filter_tracer_events_by_time_range(self):
+        """
+        Given several tracer events with different timestamps
+        When filtered by time range
+        Then only events within that time range should be returned
+        """
+        # Given
+        event_store = EventStore()
+        now = time.time()
+        event1 = TestTracerEvent(source=DescribeEventStore, timestamp=now - 100, value=1)
+        event2 = TestTracerEvent(source=DescribeEventStore, timestamp=now - 50, value=2)
+        event3 = TestTracerEvent(source=DescribeEventStore, timestamp=now, value=3)
+        event_store.store(event1)
+        event_store.store(event2)
+        event_store.store(event3)
+
+        # When
+        result = event_store.get_events(start_time=now - 75, end_time=now - 25)
+
+        # Then
+        assert len(result) == 1
+        assert event1 not in result
+        assert event2 in result
+        assert event3 not in result
+
+    def should_apply_custom_filter_function(self):
+        """
+        Given several events
+        When filtered with a custom filter function
+        Then only events matching the filter should be returned
+        """
+        # Given
+        event_store = EventStore()
+        event1 = TestEvent(source=DescribeEventStore, value=10)
+        event2 = TestEvent(source=DescribeEventStore, value=20)
+        event3 = TestEvent(source=DescribeEventStore, value=30)
+        event_store.store(event1)
+        event_store.store(event2)
+        event_store.store(event3)
+
+        # When
+        result = event_store.get_events(filter_func=lambda e: isinstance(e, TestEvent) and e.value > 15)
+
+        # Then
+        assert len(result) == 2
+        assert event1 not in result
+        assert event2 in result
+        assert event3 in result
+
+    def should_clear_events(self):
+        """
+        Given several stored events
+        When the event store is cleared
+        Then all events should be removed
+        """
+        # Given
+        event_store = EventStore()
+        event_store.store(Event(source=DescribeEventStore))
+        event_store.store(Event(source=DescribeEventStore))
+        assert len(event_store.events) == 2
+
+        # When
+        event_store.clear()
+
+        # Then
+        assert len(event_store.events) == 0
+
+    def should_get_last_n_events(self):
+        """
+        Given several events
+        When requesting the last N events
+        Then only the most recent N events should be returned
+        """
+        # Given
+        event_store = EventStore()
+        event1 = TestEvent(source=DescribeEventStore, value=1)
+        event2 = TestEvent(source=DescribeEventStore, value=2)
+        event3 = TestEvent(source=DescribeEventStore, value=3)
+        event4 = Event(source=DescribeEventStore)
+        event_store.store(event1)
+        event_store.store(event2)
+        event_store.store(event3)
+        event_store.store(event4)
+
+        # When
+        result = event_store.get_last_n_events(2)
+
+        # Then
+        assert len(result) == 2
+        assert event1 not in result
+        assert event2 not in result
+        assert event3 in result
+        assert event4 in result
+
+    def should_get_last_n_events_by_type(self):
+        """
+        Given several events of different types
+        When requesting the last N events of a specific type
+        Then only the most recent N events of that type should be returned
+        """
+        # Given
+        event_store = EventStore()
+        event1 = TestEvent(source=DescribeEventStore, value=1)
+        event2 = Event(source=DescribeEventStore)
+        event3 = TestEvent(source=DescribeEventStore, value=2)
+        event4 = TestEvent(source=DescribeEventStore, value=3)
+        event_store.store(event1)
+        event_store.store(event2)
+        event_store.store(event3)
+        event_store.store(event4)
+
+        # When
+        result = event_store.get_last_n_events(2, event_type=TestEvent)
+
+        # Then
+        assert len(result) == 2
+        assert event1 not in result
+        assert event2 not in result
+        assert event3 in result
+        assert event4 in result
+
+    def should_call_callback_when_storing_event(self):
+        """
+        Given an event store with a callback
+        When an event is stored
+        Then the callback should be called with the event
+        """
+        # Given
+        called_events = []
+
+        def callback(event):
+            called_events.append(event)
+
+        event_store = EventStore(on_store_callback=callback)
+        event1 = TestEvent(source=DescribeEventStore, value=1)
+        event2 = TestEvent(source=DescribeEventStore, value=2)
+
+        # When
+        event_store.store(event1)
+        event_store.store(event2)
+
+        # Then
+        assert len(called_events) == 2
+        assert called_events[0] == event1
+        assert called_events[1] == event2

mojentic/tracer/null_tracer.py

@@ -0,0 +1,191 @@
+"""
+NullTracer implementation to eliminate conditional checks in the code.
+
+This module provides a NullTracer that implements the same interface as TracerSystem
+but performs no operations, following the Null Object Pattern.
+"""
+from typing import Any, Callable, Dict, List, Optional, Type
+
+from mojentic.tracer.tracer_events import TracerEvent
+
+
+class NullTracer:
+    """
+    A no-op implementation of TracerSystem that silently discards all tracing operations.
+    
+    This class follows the Null Object Pattern to eliminate conditional checks in client code.
+    All record methods are overridden to do nothing, and all query methods return empty results.
+    """
+    
+    def __init__(self):
+        """Initialize the NullTracer with disabled state."""
+        self.enabled = False
+        self.event_store = None
+        
+    def record_event(self, event: TracerEvent) -> None:
+        """
+        Do nothing implementation of record_event.
+        
+        Parameters
+        ----------
+        event : TracerEvent
+            The tracer event to record (will be ignored).
+        """
+        # Do nothing
+        pass
+        
+    def record_llm_call(self, 
+                      model: str, 
+                      messages: List[Dict], 
+                      temperature: float = 1.0,
+                      tools: Optional[List[Dict]] = None,
+                      source: Any = None) -> None:
+        """
+        Do nothing implementation of record_llm_call.
+        
+        Parameters
+        ----------
+        model : str
+            The name of the LLM model being called.
+        messages : List[Dict]
+            The messages sent to the LLM.
+        temperature : float, default=1.0
+            The temperature setting for the LLM call.
+        tools : List[Dict], optional
+            The tools available to the LLM, if any.
+        source : Any, optional
+            The source of the event.
+        """
+        # Do nothing
+        pass
+        
+    def record_llm_response(self, 
+                         model: str,
+                         content: str,
+                         tool_calls: Optional[List[Dict]] = None,
+                         call_duration_ms: Optional[float] = None,
+                         source: Any = None) -> None:
+        """
+        Do nothing implementation of record_llm_response.
+        
+        Parameters
+        ----------
+        model : str
+            The name of the LLM model that responded.
+        content : str
+            The content of the LLM response.
+        tool_calls : List[Dict], optional
+            Any tool calls made by the LLM in its response.
+        call_duration_ms : float, optional
+            The duration of the LLM call in milliseconds.
+        source : Any, optional
+            The source of the event.
+        """
+        # Do nothing
+        pass
+        
+    def record_tool_call(self,
+                       tool_name: str,
+                       arguments: Dict[str, Any],
+                       result: Any,
+                       caller: Optional[str] = None,
+                       source: Any = None) -> None:
+        """
+        Do nothing implementation of record_tool_call.
+        
+        Parameters
+        ----------
+        tool_name : str
+            The name of the tool being called.
+        arguments : Dict[str, Any]
+            The arguments provided to the tool.
+        result : Any
+            The result returned by the tool.
+        caller : str, optional
+            The name of the agent or component calling the tool.
+        source : Any, optional
+            The source of the event.
+        """
+        # Do nothing
+        pass
+        
+    def record_agent_interaction(self,
+                               from_agent: str,
+                               to_agent: str,
+                               event_type: str,
+                               event_id: Optional[str] = None,
+                               source: Any = None) -> None:
+        """
+        Do nothing implementation of record_agent_interaction.
+        
+        Parameters
+        ----------
+        from_agent : str
+            The name of the agent sending the event.
+        to_agent : str
+            The name of the agent receiving the event.
+        event_type : str
+            The type of event being processed.
+        event_id : str, optional
+            A unique identifier for the event.
+        source : Any, optional
+            The source of the event.
+        """
+        # Do nothing
+        pass
+        
+    def get_events(self, 
+                  event_type: Optional[Type[TracerEvent]] = None, 
+                  start_time: Optional[float] = None,
+                  end_time: Optional[float] = None,
+                  filter_func: Optional[Callable[[TracerEvent], bool]] = None) -> List[TracerEvent]:
+        """
+        Return an empty list for any get_events request.
+        
+        Parameters
+        ----------
+        event_type : Type[TracerEvent], optional
+            Filter events by this specific tracer event type.
+        start_time : float, optional
+            Include events with timestamp >= start_time.
+        end_time : float, optional
+            Include events with timestamp <= end_time.
+        filter_func : Callable[[TracerEvent], bool], optional
+            Custom filter function to apply to events.
+            
+        Returns
+        -------
+        List[TracerEvent]
+            An empty list.
+        """
+        return []
+    
+    def get_last_n_tracer_events(self, n: int, event_type: Optional[Type[TracerEvent]] = None) -> List[TracerEvent]:
+        """
+        Return an empty list for any get_last_n_tracer_events request.
+        
+        Parameters
+        ----------
+        n : int
+            Number of events to return.
+        event_type : Type[TracerEvent], optional
+            Filter events by this specific tracer event type.
+            
+        Returns
+        -------
+        List[TracerEvent]
+            An empty list.
+        """
+        return []
+    
+    def clear(self) -> None:
+        """Do nothing implementation of clear method."""
+        pass
+    
+    def enable(self) -> None:
+        """No-op method for interface compatibility."""
+        pass
+        
+    def disable(self) -> None:
+        """No-op method for interface compatibility."""
+        pass

mojentic/tracer/tracer_events.py

@@ -0,0 +1,136 @@
+"""
+Defines tracer event types for tracking system interactions.
+"""
+from typing import Any, Dict, List, Optional, Type
+from datetime import datetime
+
+from pydantic import Field
+
+from mojentic.event import Event
+
+
+class TracerEvent(Event):
+    """
+    Base class for all tracer-specific events.
+    
+    Tracer events are used to track system interactions for observability purposes.
+    They are distinct from regular events which are used for agent communication.
+    """
+    timestamp: float = Field(..., description="Timestamp when the event occurred")
+    
+    def printable_summary(self) -> str:
+        """
+        Return a formatted string summary of the event.
+        
+        Returns
+        -------
+        str
+            A formatted string with the event information.
+        """
+        event_time = datetime.fromtimestamp(self.timestamp).strftime("%H:%M:%S.%f")[:-3]
+        return f"[{event_time}] {type(self).__name__}"
+    
+
+class LLMCallTracerEvent(TracerEvent):
+    """
+    Records when an LLM is called with specific messages.
+    """
+    model: str = Field(..., description="The LLM model that was used")
+    messages: List[dict] = Field(..., description="The messages sent to the LLM")
+    temperature: float = Field(1.0, description="The temperature setting used for the call")
+    tools: Optional[List[Dict]] = Field(None, description="The tools available to the LLM, if any")
+    
+    def printable_summary(self) -> str:
+        """Return a formatted summary of the LLM call event."""
+        base_summary = super().printable_summary()
+        summary = f"{base_summary}\n   Model: {self.model}"
+        
+        if self.messages:
+            msg_count = len(self.messages)
+            summary += f"\n   Messages: {msg_count} message{'s' if msg_count != 1 else ''}"
+            
+        if self.temperature != 1.0:
+            summary += f"\n   Temperature: {self.temperature}"
+            
+        if self.tools:
+            tool_names = [tool.get('name', 'unknown') for tool in self.tools]
+            summary += f"\n   Available Tools: {', '.join(tool_names)}"
+            
+        return summary
+    
+
+class LLMResponseTracerEvent(TracerEvent):
+    """
+    Records when an LLM responds to a call.
+    """
+    model: str = Field(..., description="The LLM model that was used")
+    content: str = Field(..., description="The content of the LLM response")
+    tool_calls: Optional[List[Dict]] = Field(None, description="Any tool calls made by the LLM")
+    call_duration_ms: Optional[float] = Field(None, description="Duration of the LLM call in milliseconds")
+    
+    def printable_summary(self) -> str:
+        """Return a formatted summary of the LLM response event."""
+        base_summary = super().printable_summary()
+        summary = f"{base_summary}\n   Model: {self.model}"
+        
+        if self.content:
+            content_preview = self.content[:100] + "..." if len(self.content) > 100 else self.content
+            summary += f"\n   Content: {content_preview}"
+            
+        if self.tool_calls:
+            tool_count = len(self.tool_calls)
+            summary += f"\n   Tool Calls: {tool_count} call{'s' if tool_count != 1 else ''}"
+            
+        if self.call_duration_ms is not None:
+            summary += f"\n   Duration: {self.call_duration_ms:.2f}ms"
+            
+        return summary
+
+
+class ToolCallTracerEvent(TracerEvent):
+    """
+    Records when a tool is called during agent execution.
+    """
+    tool_name: str = Field(..., description="Name of the tool that was called")
+    arguments: Dict[str, Any] = Field(..., description="Arguments provided to the tool")
+    result: Any = Field(..., description="Result returned by the tool")
+    caller: Optional[str] = Field(None, description="Name of the agent or component that called the tool")
+    
+    def printable_summary(self) -> str:
+        """Return a formatted summary of the tool call event."""
+        base_summary = super().printable_summary()
+        summary = f"{base_summary}\n   Tool: {self.tool_name}"
+        
+        if self.arguments:
+            summary += f"\n   Arguments: {self.arguments}"
+        
+        if self.result is not None:
+            result_str = str(self.result)
+            result_preview = result_str[:100] + "..." if len(result_str) > 100 else result_str
+            summary += f"\n   Result: {result_preview}"
+            
+        if self.caller:
+            summary += f"\n   Caller: {self.caller}"
+            
+        return summary
+
+
+class AgentInteractionTracerEvent(TracerEvent):
+    """
+    Records interactions between agents.
+    """
+    from_agent: str = Field(..., description="Name of the agent sending the event")
+    to_agent: str = Field(..., description="Name of the agent receiving the event")
+    event_type: str = Field(..., description="Type of event being processed")
+    event_id: Optional[str] = Field(None, description="Unique identifier for the event")
+    
+    def printable_summary(self) -> str:
+        """Return a formatted summary of the agent interaction event."""
+        base_summary = super().printable_summary()
+        summary = f"{base_summary}\n   From: {self.from_agent} → To: {self.to_agent}"
+        summary += f"\n   Event Type: {self.event_type}"
+        
+        if self.event_id:
+            summary += f"\n   Event ID: {self.event_id}"
+            
+        return summary