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

mojentic/tracer/tracer_events_spec.py

@@ -0,0 +1,116 @@
+import time
+from typing import Dict, List
+
+from mojentic.tracer.tracer_events import (
+    TracerEvent,
+    LLMCallTracerEvent,
+    LLMResponseTracerEvent,
+    ToolCallTracerEvent,
+    AgentInteractionTracerEvent
+)
+
+
+class DescribeTracerEvents:
+    """
+    Test the tracer event classes to ensure they can be instantiated and have the required properties.
+    """
+
+    def should_create_base_tracer_event(self):
+        """
+        Test creating a base tracer event.
+        """
+        # Given / When
+        event = TracerEvent(
+            source=DescribeTracerEvents,
+            timestamp=time.time()
+        )
+        
+        # Then
+        assert isinstance(event, TracerEvent)
+        assert isinstance(event.timestamp, float)
+        assert event.source == DescribeTracerEvents
+
+    def should_create_llm_call_tracer_event(self):
+        """
+        Test creating an LLM call tracer event.
+        """
+        # Given / When
+        messages = [{"role": "system", "content": "You are a helpful assistant"}]
+        event = LLMCallTracerEvent(
+            source=DescribeTracerEvents,
+            timestamp=time.time(),
+            model="test-model",
+            messages=messages,
+            temperature=0.7,
+            tools=None
+        )
+        
+        # Then
+        assert isinstance(event, LLMCallTracerEvent)
+        assert event.model == "test-model"
+        assert event.messages == messages
+        assert event.temperature == 0.7
+        assert event.tools is None
+
+    def should_create_llm_response_tracer_event(self):
+        """
+        Test creating an LLM response tracer event.
+        """
+        # Given / When
+        event = LLMResponseTracerEvent(
+            source=DescribeTracerEvents,
+            timestamp=time.time(),
+            model="test-model",
+            content="This is a test response",
+            call_duration_ms=150.5
+        )
+        
+        # Then
+        assert isinstance(event, LLMResponseTracerEvent)
+        assert event.model == "test-model"
+        assert event.content == "This is a test response"
+        assert event.call_duration_ms == 150.5
+        assert event.tool_calls is None
+
+    def should_create_tool_call_tracer_event(self):
+        """
+        Test creating a tool call tracer event.
+        """
+        # Given / When
+        arguments = {"query": "test query"}
+        event = ToolCallTracerEvent(
+            source=DescribeTracerEvents,
+            timestamp=time.time(),
+            tool_name="test-tool",
+            arguments=arguments,
+            result="test result",
+            caller="TestAgent"
+        )
+        
+        # Then
+        assert isinstance(event, ToolCallTracerEvent)
+        assert event.tool_name == "test-tool"
+        assert event.arguments == arguments
+        assert event.result == "test result"
+        assert event.caller == "TestAgent"
+
+    def should_create_agent_interaction_tracer_event(self):
+        """
+        Test creating an agent interaction tracer event.
+        """
+        # Given / When
+        event = AgentInteractionTracerEvent(
+            source=DescribeTracerEvents,
+            timestamp=time.time(),
+            from_agent="AgentA",
+            to_agent="AgentB",
+            event_type="RequestEvent",
+            event_id="12345"
+        )
+        
+        # Then
+        assert isinstance(event, AgentInteractionTracerEvent)
+        assert event.from_agent == "AgentA"
+        assert event.to_agent == "AgentB"
+        assert event.event_type == "RequestEvent"
+        assert event.event_id == "12345"

mojentic/tracer/tracer_system.py

@@ -0,0 +1,285 @@
+"""
+TracerSystem module for coordinating tracer events.
+
+This provides a central system for recording, filtering, and querying tracer events.
+"""
+import time
+from typing import Any, Callable, Dict, List, Optional, Type, Union
+
+import structlog
+
+from mojentic.tracer.tracer_events import (
+    TracerEvent, 
+    LLMCallTracerEvent,
+    LLMResponseTracerEvent,
+    ToolCallTracerEvent,
+    AgentInteractionTracerEvent
+)
+from mojentic.tracer.event_store import EventStore
+from mojentic.event import Event
+
+logger = structlog.get_logger()
+
+
+class TracerSystem:
+    """
+    Central system for capturing and querying tracer events.
+    
+    The TracerSystem is responsible for recording events related to LLM calls,
+    tool usage, and agent interactions, providing a way to trace through the
+    major events of the system.
+    """
+    
+    def __init__(self, event_store: Optional[EventStore] = None, enabled: bool = True):
+        """
+        Initialize the tracer system.
+        
+        Parameters
+        ----------
+        event_store : EventStore, optional
+            The event store to use for storing events. If None, a new EventStore will be created.
+        enabled : bool, default=True
+            Whether the tracer system is enabled. If False, no events will be recorded.
+        """
+        self.event_store = event_store or EventStore()
+        self.enabled = enabled
+        
+    def record_event(self, event: TracerEvent) -> None:
+        """
+        Record a tracer event in the event store.
+        
+        Parameters
+        ----------
+        event : TracerEvent
+            The tracer event to record.
+        """
+        if not self.enabled:
+            return
+            
+        self.event_store.store(event)
+        
+    def record_llm_call(self, 
+                      model: str, 
+                      messages: List[Dict], 
+                      temperature: float = 1.0,
+                      tools: Optional[List[Dict]] = None,
+                      source: Any = None) -> None:
+        """
+        Record an LLM call event.
+        
+        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. If None, the TracerSystem class will be used.
+        """
+        if not self.enabled:
+            return
+            
+        event = LLMCallTracerEvent(
+            source=source or type(self),
+            timestamp=time.time(),
+            model=model,
+            messages=messages,
+            temperature=temperature,
+            tools=tools
+        )
+        self.event_store.store(event)
+        
+    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:
+        """
+        Record an LLM response event.
+        
+        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. If None, the TracerSystem class will be used.
+        """
+        if not self.enabled:
+            return
+            
+        event = LLMResponseTracerEvent(
+            source=source or type(self),
+            timestamp=time.time(),
+            model=model,
+            content=content,
+            tool_calls=tool_calls,
+            call_duration_ms=call_duration_ms
+        )
+        self.event_store.store(event)
+        
+    def record_tool_call(self,
+                       tool_name: str,
+                       arguments: Dict[str, Any],
+                       result: Any,
+                       caller: Optional[str] = None,
+                       source: Any = None) -> None:
+        """
+        Record a tool call event.
+        
+        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. If None, the TracerSystem class will be used.
+        """
+        if not self.enabled:
+            return
+            
+        event = ToolCallTracerEvent(
+            source=source or type(self),
+            timestamp=time.time(),
+            tool_name=tool_name,
+            arguments=arguments,
+            result=result,
+            caller=caller
+        )
+        self.event_store.store(event)
+        
+    def record_agent_interaction(self,
+                               from_agent: str,
+                               to_agent: str,
+                               event_type: str,
+                               event_id: Optional[str] = None,
+                               source: Any = None) -> None:
+        """
+        Record an agent interaction event.
+        
+        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. If None, the TracerSystem class will be used.
+        """
+        if not self.enabled:
+            return
+            
+        event = AgentInteractionTracerEvent(
+            source=source or type(self),
+            timestamp=time.time(),
+            from_agent=from_agent,
+            to_agent=to_agent,
+            event_type=event_type,
+            event_id=event_id
+        )
+        self.event_store.store(event)
+        
+    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]:
+        """
+        Get tracer events from the store, optionally filtered.
+        
+        This is a convenience wrapper around the EventStore's get_events method,
+        specifically for tracer events.
+        
+        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]
+            Events that match the filter criteria.
+        """
+        # First filter to only TracerEvents
+        events = self.event_store.get_events(event_type=TracerEvent)
+        
+        # Then apply additional filters
+        if event_type is not None:
+            events = [e for e in events if isinstance(e, event_type)]
+            
+        if start_time is not None:
+            events = [e for e in events if e.timestamp >= start_time]
+            
+        if end_time is not None:
+            events = [e for e in events if e.timestamp <= end_time]
+            
+        if filter_func is not None:
+            events = [e for e in events if filter_func(e)]
+            
+        return events
+    
+    def get_last_n_tracer_events(self, n: int, event_type: Optional[Type[TracerEvent]] = None) -> List[TracerEvent]:
+        """
+        Get the last N tracer events, optionally filtered by type.
+        
+        Parameters
+        ----------
+        n : int
+            Number of events to return.
+        event_type : Type[TracerEvent], optional
+            Filter events by this specific tracer event type.
+            
+        Returns
+        -------
+        List[TracerEvent]
+            The last N tracer events that match the filter criteria.
+        """
+        base_type = event_type or TracerEvent
+        return self.event_store.get_last_n_events(n, event_type=base_type)
+    
+    def clear(self) -> None:
+        """
+        Clear all events from the event store.
+        """
+        self.event_store.clear()
+    
+    def enable(self) -> None:
+        """
+        Enable the tracer system.
+        """
+        self.enabled = True
+        
+    def disable(self) -> None:
+        """
+        Disable the tracer system.
+        """
+        self.enabled = False
+
+
+# Import and use the null tracer directly in client code via:
+# from mojentic.tracer import null_tracer

mojentic/tracer/tracer_system_spec.py

@@ -0,0 +1,255 @@
+import time
+from typing import Dict, List, Optional, Type, Union
+
+import pytest
+
+from mojentic.tracer.tracer_events import (
+    TracerEvent,
+    LLMCallTracerEvent,
+    LLMResponseTracerEvent,
+    ToolCallTracerEvent,
+    AgentInteractionTracerEvent
+)
+from mojentic.tracer.tracer_system import TracerSystem
+from mojentic.tracer.event_store import EventStore
+
+
+class DescribeTracerSystem:
+    """
+    Tests for the TracerSystem class.
+    """
+    
+    def should_initialize_with_default_event_store(self):
+        """
+        Given no event store
+        When initializing a tracer system
+        Then it should create a default event store
+        """
+        # Given / When
+        tracer_system = TracerSystem()
+        
+        # Then
+        assert tracer_system.event_store is not None
+        assert isinstance(tracer_system.event_store, EventStore)
+        assert tracer_system.enabled is True
+    
+    def should_initialize_with_provided_event_store(self):
+        """
+        Given an event store
+        When initializing a tracer system with it
+        Then it should use the provided event store
+        """
+        # Given
+        event_store = EventStore()
+        
+        # When
+        tracer_system = TracerSystem(event_store=event_store)
+        
+        # Then
+        assert tracer_system.event_store is event_store
+    
+    def should_record_llm_call(self):
+        """
+        Given an enabled tracer system
+        When recording an LLM call
+        Then it should store an LLMCallTracerEvent
+        """
+        # Given
+        tracer_system = TracerSystem()
+        
+        # When
+        messages = [{"role": "system", "content": "You are a helpful assistant."}]
+        tracer_system.record_llm_call("test-model", messages, 0.7)
+        
+        # Then
+        events = tracer_system.get_events(event_type=LLMCallTracerEvent)
+        assert len(events) == 1
+        event = events[0]
+        assert event.model == "test-model"
+        assert event.messages == messages
+        assert event.temperature == 0.7
+        
+    def should_record_llm_response(self):
+        """
+        Given an enabled tracer system
+        When recording an LLM response
+        Then it should store an LLMResponseTracerEvent
+        """
+        # Given
+        tracer_system = TracerSystem()
+        
+        # When
+        tracer_system.record_llm_response(
+            "test-model",
+            "This is a test response",
+            call_duration_ms=150.5
+        )
+        
+        # Then
+        events = tracer_system.get_events(event_type=LLMResponseTracerEvent)
+        assert len(events) == 1
+        event = events[0]
+        assert event.model == "test-model"
+        assert event.content == "This is a test response"
+        assert event.call_duration_ms == 150.5
+        
+    def should_record_tool_call(self):
+        """
+        Given an enabled tracer system
+        When recording a tool call
+        Then it should store a ToolCallTracerEvent
+        """
+        # Given
+        tracer_system = TracerSystem()
+        
+        # When
+        arguments = {"query": "test query"}
+        tracer_system.record_tool_call(
+            "test-tool",
+            arguments,
+            "test result",
+            "TestAgent"
+        )
+        
+        # Then
+        events = tracer_system.get_events(event_type=ToolCallTracerEvent)
+        assert len(events) == 1
+        event = events[0]
+        assert event.tool_name == "test-tool"
+        assert event.arguments == arguments
+        assert event.result == "test result"
+        assert event.caller == "TestAgent"
+        
+    def should_record_agent_interaction(self):
+        """
+        Given an enabled tracer system
+        When recording an agent interaction
+        Then it should store an AgentInteractionTracerEvent
+        """
+        # Given
+        tracer_system = TracerSystem()
+        
+        # When
+        tracer_system.record_agent_interaction(
+            "AgentA",
+            "AgentB",
+            "RequestEvent",
+            "12345"
+        )
+        
+        # Then
+        events = tracer_system.get_events(event_type=AgentInteractionTracerEvent)
+        assert len(events) == 1
+        event = events[0]
+        assert event.from_agent == "AgentA"
+        assert event.to_agent == "AgentB"
+        assert event.event_type == "RequestEvent"
+        assert event.event_id == "12345"
+        
+    def should_not_record_when_disabled(self):
+        """
+        Given a disabled tracer system
+        When recording events
+        Then no events should be stored
+        """
+        # Given
+        tracer_system = TracerSystem(enabled=False)
+        
+        # When
+        tracer_system.record_llm_call("test-model", [])
+        tracer_system.record_llm_response("test-model", "response")
+        tracer_system.record_tool_call("test-tool", {}, "result")
+        tracer_system.record_agent_interaction("AgentA", "AgentB", "Event")
+        
+        # Then
+        assert len(tracer_system.get_events()) == 0
+        
+    def should_filter_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
+        tracer_system = TracerSystem()
+        
+        # Create events with specific timestamps
+        now = time.time()
+        tracer_system.event_store.store(
+            LLMCallTracerEvent(source=DescribeTracerSystem, timestamp=now - 100, model="model1", messages=[])
+        )
+        tracer_system.event_store.store(
+            LLMCallTracerEvent(source=DescribeTracerSystem, timestamp=now - 50, model="model2", messages=[])
+        )
+        tracer_system.event_store.store(
+            LLMCallTracerEvent(source=DescribeTracerSystem, timestamp=now, model="model3", messages=[])
+        )
+        
+        # When
+        result = tracer_system.get_events(start_time=now - 75, end_time=now - 25)
+        
+        # Then
+        assert len(result) == 1
+        assert result[0].model == "model2"
+        
+    def should_get_last_n_tracer_events(self):
+        """
+        Given several tracer events of different types
+        When requesting the last N tracer events of a specific type
+        Then only the most recent N events of that type should be returned
+        """
+        # Given
+        tracer_system = TracerSystem()
+        
+        tracer_system.record_llm_call("model1", [])
+        tracer_system.record_tool_call("tool1", {}, "result1")
+        tracer_system.record_llm_call("model2", [])
+        tracer_system.record_llm_call("model3", [])
+        
+        # When
+        result = tracer_system.get_last_n_tracer_events(2, event_type=LLMCallTracerEvent)
+        
+        # Then
+        assert len(result) == 2
+        assert result[0].model == "model2"
+        assert result[1].model == "model3"
+        
+    def should_enable_and_disable(self):
+        """
+        Given a tracer system
+        When enabling and disabling it
+        Then its enabled state should change accordingly
+        """
+        # Given
+        tracer_system = TracerSystem(enabled=False)
+        assert not tracer_system.enabled
+        
+        # When
+        tracer_system.enable()
+        
+        # Then
+        assert tracer_system.enabled
+        
+        # When
+        tracer_system.disable()
+        
+        # Then
+        assert not tracer_system.enabled
+        
+    def should_clear_events(self):
+        """
+        Given a tracer system with events
+        When clearing events
+        Then all events should be removed
+        """
+        # Given
+        tracer_system = TracerSystem()
+        tracer_system.record_llm_call("model1", [])
+        tracer_system.record_tool_call("tool1", {}, "result1")
+        assert len(tracer_system.get_events()) == 2
+        
+        # When
+        tracer_system.clear()
+        
+        # Then
+        assert len(tracer_system.get_events()) == 0