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

mojentic/llm/message_composers_spec.py

@@ -176,39 +176,57 @@ class DescribeMessageBuilder:
             assert image_path2 in message_builder.image_paths
             assert result is message_builder  # Returns self for method chaining
 
-        def should_add_all_jpg_images_from_directory(self, message_builder, mocker):
-            dir_path = Path("/path/to/images")
-            jpg_files = [Path("/path/to/images/image1.jpg"), Path("/path/to/images/image2.jpg")]
-
-            # Mock is_dir, glob, and exists methods
-            mocker.patch.object(Path, 'is_dir', return_value=True)
-            mocker.patch.object(Path, 'glob', return_value=jpg_files)
-            mocker.patch.object(Path, 'exists', return_value=True)
-
+        def should_add_all_jpg_images_from_directory(self, message_builder, mocker, tmp_path):
+            # Create a temporary directory with test image files
+            dir_path = tmp_path / "images"
+            dir_path.mkdir()
+
+            # Create empty test image files
+            image1_path = dir_path / "image1.jpg"
+            image2_path = dir_path / "image2.jpg"
+            image1_path.touch()
+            image2_path.touch()
+
+            # Create a text file that should be ignored
+            text_file_path = dir_path / "text.txt"
+            text_file_path.touch()
+
+            # Use the real directory for the test
             message_builder.add_images(dir_path)
 
-            assert jpg_files[0] in message_builder.image_paths
-            assert jpg_files[1] in message_builder.image_paths
+            # Convert to strings for easier comparison
+            image_paths_str = [str(p) for p in message_builder.image_paths]
 
-        def should_add_images_matching_glob_pattern(self, message_builder, mocker):
-            pattern_path = Path("/path/to/*.jpg")
-            matching_files = [Path("/path/to/image1.jpg"), Path("/path/to/image2.jpg")]
+            # Verify only jpg files were added
+            assert str(image1_path) in image_paths_str
+            assert str(image2_path) in image_paths_str
+            assert str(text_file_path) not in image_paths_str
 
-            # Mock methods
-            mocker.patch.object(Path, 'is_dir', return_value=False)
-            mocker.patch.object(Path, 'glob', return_value=matching_files)
-            mocker.patch.object(Path, 'is_file', return_value=True)
-            mocker.patch.object(Path, 'exists', return_value=True)
+        def should_add_images_matching_glob_pattern(self, message_builder, tmp_path):
+            # Create a temporary directory with test image files
+            dir_path = tmp_path / "glob_test"
+            dir_path.mkdir()
 
-            # Mock the parent property and its glob method
-            parent_mock = mocker.MagicMock()
-            parent_mock.glob.return_value = matching_files
-            mocker.patch.object(Path, 'parent', parent_mock)
+            # Create test image files
+            image1_path = dir_path / "image1.jpg"
+            image2_path = dir_path / "image2.jpg"
+            image3_path = dir_path / "other.png"  # Should not match
+            image1_path.touch()
+            image2_path.touch()
+            image3_path.touch()
+
+            # Use a real glob pattern
+            pattern_path = dir_path / "*.jpg"
 
             message_builder.add_images(pattern_path)
 
-            assert matching_files[0] in message_builder.image_paths
-            assert matching_files[1] in message_builder.image_paths
+            # Convert to strings for easier comparison
+            image_paths_str = [str(p) for p in message_builder.image_paths]
+
+            # Verify only jpg files matching the pattern were added
+            assert str(image1_path) in image_paths_str
+            assert str(image2_path) in image_paths_str
+            assert str(image3_path) not in image_paths_str
 
     class DescribeLoadContentMethod:
         """

mojentic/llm/tools/llm_tool.py

@@ -1,14 +1,41 @@
 import json
+from typing import Any, Dict, Optional
 
+from mojentic.tracer.tracer_system import TracerSystem
 from mojentic.llm.gateways.models import TextContent
 
 
 class LLMTool:
+    def __init__(self, tracer: Optional[TracerSystem] = None):
+        """
+        Initialize an LLM tool with optional tracer system.
+
+        Parameters
+        ----------
+        tracer : TracerSystem, optional
+            The tracer system to use for recording tool usage.
+        """
+        # Use null_tracer if no tracer is provided
+        from mojentic.tracer import null_tracer
+        self.tracer = tracer or null_tracer
+
     def run(self, **kwargs):
         raise NotImplementedError
 
-    def call_tool(self, **kwargs):
+    def call_tool(self, correlation_id: str = None, **kwargs):
+        # Execute the tool and capture the result
         result = self.run(**kwargs)
+
+        # Record the tool call in the tracer system (always safe to call with null_tracer)
+        self.tracer.record_tool_call(
+            tool_name=self.name,
+            arguments=kwargs,
+            result=result,
+            source=type(self),
+            correlation_id=correlation_id
+        )
+
+        # Format the result
         if isinstance(result, dict):
             result = json.dumps(result)
         return {

mojentic/llm/tools/llm_tool_spec.py

@@ -10,7 +10,8 @@ from mojentic.llm.tools.llm_tool import LLMTool
 class MockLLMTool(LLMTool):
     """A mock implementation of LLMTool for testing purposes."""
 
-    def __init__(self, run_result=None):
+    def __init__(self, run_result=None, tracer=None):
+        super().__init__(tracer=tracer)
         self._run_result = run_result
         self._descriptor = {
             "function": {

mojentic/tracer/__init__.py

@@ -0,0 +1,16 @@
+
+"""
+Mojentic tracer module for tracking system operations.
+"""
+from mojentic.tracer.tracer_events import (
+    TracerEvent,
+    LLMCallTracerEvent,
+    LLMResponseTracerEvent,
+    ToolCallTracerEvent,
+    AgentInteractionTracerEvent
+)
+from mojentic.tracer.tracer_system import TracerSystem
+from mojentic.tracer.null_tracer import NullTracer
+
+# Create a singleton NullTracer instance for use throughout the application
+null_tracer = NullTracer()

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,203 @@
+"""
+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,
+                      correlation_id: str = 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.
+        correlation_id : str, optional
+            UUID string that is copied from cause-to-affect for tracing events.
+        """
+        # 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,
+                         correlation_id: str = 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.
+        correlation_id : str, optional
+            UUID string that is copied from cause-to-affect for tracing events.
+        """
+        # Do nothing
+        pass
+
+    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:
+        """
+        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.
+        correlation_id : str, optional
+            UUID string that is copied from cause-to-affect for tracing events.
+        """
+        # 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,
+                               correlation_id: str = 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.
+        correlation_id : str, optional
+            UUID string that is copied from cause-to-affect for tracing events.
+        """
+        # 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