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

mojentic/tracer/tracer_events.py

@@ -0,0 +1,138 @@
+"""
+Defines tracer event types for tracking system interactions.
+"""
+from typing import Any, Dict, List, Optional, Type
+from datetime import datetime
+import uuid
+
+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")
+    correlation_id: str = Field(default_factory=lambda: str(uuid.uuid4()), description="UUID string that is copied from cause-to-affect for tracing events")
+
+    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__} (correlation_id: {self.correlation_id})"
+
+
+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

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,301 @@
+"""
+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,
+                      correlation_id: str = 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.
+        correlation_id : str, required
+            UUID string that is copied from cause-to-affect for tracing events.
+        """
+        if not self.enabled:
+            return
+
+        event = LLMCallTracerEvent(
+            source=source or type(self),
+            timestamp=time.time(),
+            model=model,
+            messages=messages,
+            temperature=temperature,
+            tools=tools,
+            correlation_id=correlation_id
+        )
+        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,
+                         correlation_id: str = 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.
+        correlation_id : str, required
+            UUID string that is copied from cause-to-affect for tracing events.
+        """
+        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,
+            correlation_id=correlation_id
+        )
+        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,
+                       correlation_id: str = 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.
+        correlation_id : str, required
+            UUID string that is copied from cause-to-affect for tracing events.
+        """
+        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,
+            correlation_id=correlation_id
+        )
+        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,
+                               correlation_id: str = 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.
+        correlation_id : str, required
+            UUID string that is copied from cause-to-affect for tracing events.
+        """
+        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,
+            correlation_id=correlation_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