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

_examples/recursive_agent.py

@@ -21,7 +21,8 @@ async def demonstrate_async():
     3. Running multiple problem-solving tasks concurrently
     """
     # Initialize the LLM broker with your preferred model
-    llm = LLMBroker(model="llama3.3-70b-32k")
+    # llm = LLMBroker(model="llama3.3-70b-32k")
+    llm = LLMBroker(model="qwen3:30b-a3b-q4_K_M")
 
     # Create the agent with a maximum of 3 iterations
     agent = SimpleRecursiveAgent(llm=llm, max_iterations=3)

_examples/tracer_demo.py

@@ -0,0 +1,109 @@
+"""
+Example script demonstrating the tracer system with ChatSession and tools.
+
+This example shows how to use the tracer system to monitor an interactive 
+chat session with LLMBroker and tools. When the user exits the session, 
+the script displays a summary of all traced events.
+"""
+from datetime import datetime
+
+from mojentic.tracer import TracerSystem
+from mojentic.tracer.tracer_events import LLMCallTracerEvent, LLMResponseTracerEvent, ToolCallTracerEvent
+from mojentic.llm import ChatSession, LLMBroker
+from mojentic.llm.tools.date_resolver import ResolveDateTool
+
+
+def print_tracer_events(events):
+    """Print tracer events using their printable_summary method."""
+    print(f"\n{'-'*80}")
+    print("Tracer Events:")
+    print(f"{'-'*80}")
+    
+    for i, event in enumerate(events, 1):
+        print(f"{i}. {event.printable_summary()}")
+        print()
+
+
+def main():
+    """Run a chat session with tracer system to monitor interactions."""
+    # Create a tracer system to monitor all interactions
+    tracer = TracerSystem()
+    
+    # Create an LLM broker with the tracer
+    llm_broker = LLMBroker(model="llama3.3-70b-32k", tracer=tracer)
+    
+    # Create a date resolver tool that will also use the tracer
+    date_tool = ResolveDateTool(llm_broker=llm_broker, tracer=tracer)
+    
+    # Create a chat session with the broker and tool
+    chat_session = ChatSession(llm_broker, tools=[date_tool])
+    
+    print("Welcome to the chat session with tracer demonstration!")
+    print("Ask questions about dates (e.g., 'What day is next Friday?') or anything else.")
+    print("Behind the scenes, the tracer system is recording all interactions.")
+    print("Press Enter with no input to exit and see the trace summary.")
+    print("-" * 80)
+    
+    # Interactive chat session
+    while True:
+        query = input("You: ")
+        if not query:
+            print("Exiting chat session...")
+            break
+        else:
+            print("Assistant: ", end="")
+            response = chat_session.send(query)
+            print(response)
+    
+    # After the user exits, display tracer event summary
+    print("\nTracer System Summary")
+    print("=" * 80)
+    print(f"You just had a conversation with an LLM, and the tracer recorded everything!")
+    
+    # Get all events
+    all_events = tracer.get_events()
+    print(f"Total events recorded: {len(all_events)}")
+    print_tracer_events(all_events)
+    
+    # Show how to filter events by type
+    print("\nYou can filter events by type:")
+    
+    llm_calls = tracer.get_events(event_type=LLMCallTracerEvent)
+    print(f"LLM Call Events: {len(llm_calls)}")
+    if llm_calls:
+        print(f"Example: {llm_calls[0].printable_summary()}")
+    
+    llm_responses = tracer.get_events(event_type=LLMResponseTracerEvent)
+    print(f"LLM Response Events: {len(llm_responses)}")
+    if llm_responses:
+        print(f"Example: {llm_responses[0].printable_summary()}")
+    
+    tool_calls = tracer.get_events(event_type=ToolCallTracerEvent)
+    print(f"Tool Call Events: {len(tool_calls)}")
+    if tool_calls:
+        print(f"Example: {tool_calls[0].printable_summary()}")
+    
+    # Show the last few events
+    print("\nThe last few events:")
+    last_events = tracer.get_last_n_tracer_events(3)
+    print_tracer_events(last_events)
+    
+    # Show how to use time-based filtering
+    print("\nYou can also filter events by time range:")
+    print("Example: tracer.get_events(start_time=start_timestamp, end_time=end_timestamp)")
+    
+    # Show how to extract specific information from events
+    if tool_calls:
+        print("\nDetailed analysis example - Tool usage stats:")
+        tool_names = {}
+        for event in tool_calls:
+            tool_name = event.tool_name
+            tool_names[tool_name] = tool_names.get(tool_name, 0) + 1
+        
+        print("Tool usage frequency:")
+        for tool_name, count in tool_names.items():
+            print(f"  - {tool_name}: {count} calls")
+
+
+if __name__ == "__main__":
+    main()

mojentic/dispatcher.py

@@ -1,6 +1,7 @@
 import logging
 import threading
 from time import sleep
+from typing import Optional, Type
 from uuid import uuid4
 
 import structlog
@@ -11,12 +12,16 @@ logger = structlog.get_logger()
 
 
 class Dispatcher:
-    def __init__(self, router, shared_working_memory=None, batch_size=5):
+    def __init__(self, router, shared_working_memory=None, batch_size=5, tracer=None):
         self.router = router
         self.batch_size = batch_size
         self.event_queue = []
         self._stop_event = threading.Event()
         self._thread = threading.Thread(target=self._dispatch_events)
+        
+        # Use null_tracer if no tracer is provided
+        from mojentic.tracer import null_tracer
+        self.tracer = tracer or null_tracer
 
         logger.debug("Starting event dispatch thread")
         self._thread.start()
@@ -44,6 +49,17 @@ class Dispatcher:
                     events = []
                     for agent in agents:
                         logger.debug(f"Sending event to agent {agent}")
+                        
+                        # Record agent interaction in tracer system
+                        self.tracer.record_agent_interaction(
+                            from_agent=str(event.source),
+                            to_agent=str(type(agent)),
+                                event_type=str(type(event).__name__),
+                                event_id=event.correlation_id,
+                                source=type(self)
+                            )
+                        
+                        # Process the event through the agent
                         received_events = agent.receive_event(event)
                         logger.debug(f"Agent {agent} returned {len(events)} events")
                         events.extend(received_events)

mojentic/llm/gateways/openai_message_adapter_spec.py

@@ -92,13 +92,13 @@ class DescribeOpenAIMessagesAdapter:
             When adapting to OpenAI format
             Then it should convert to the correct format with structured content array
             """
-            # Mock the open function to avoid reading actual files
-            mock_file = mocker.mock_open(read_data=b'fake_image_data')
-            mocker.patch('builtins.open', mock_file)
-
-            # Mock base64 encoding to return a predictable value
-            mock_b64encode = mocker.patch('base64.b64encode')
-            mock_b64encode.return_value = b'ZmFrZV9pbWFnZV9kYXRhX2VuY29kZWQ='  # 'fake_image_data_encoded' in base64
+            # Patch our own methods that encapsulate external library calls
+            mocker.patch('mojentic.llm.gateways.openai_messages_adapter.read_file_as_binary', 
+                         return_value=b'fake_image_data')
+            mocker.patch('mojentic.llm.gateways.openai_messages_adapter.encode_base64', 
+                         return_value='ZmFrZV9pbWFnZV9kYXRhX2VuY29kZWQ=')
+            mocker.patch('mojentic.llm.gateways.openai_messages_adapter.get_image_type', 
+                         side_effect=lambda path: 'jpg' if path.endswith('.jpg') else 'png')
 
             image_paths = ["/path/to/image1.jpg", "/path/to/image2.png"]
             messages = [LLMMessage(role=MessageRole.User, content="What's in these images?", image_paths=image_paths)]

mojentic/llm/gateways/openai_messages_adapter.py

@@ -10,6 +10,53 @@ from mojentic.llm.gateways.models import LLMMessage, MessageRole
 logger = structlog.get_logger()
 
 
+def read_file_as_binary(file_path: str) -> bytes:
+    """Read a file as binary data.
+
+    This function encapsulates the external library call to open() so it can be mocked in tests.
+
+    Args:
+        file_path: Path to the file to read
+
+    Returns:
+        Binary content of the file
+    """
+    with open(file_path, "rb") as file:
+        return file.read()
+
+
+def encode_base64(data: bytes) -> str:
+    """Encode binary data as base64 string.
+
+    This function encapsulates the external library call to base64.b64encode() so it can be mocked in tests.
+
+    Args:
+        data: Binary data to encode
+
+    Returns:
+        Base64-encoded string
+    """
+    return base64.b64encode(data).decode('utf-8')
+
+
+def get_image_type(file_path: str) -> str:
+    """Determine image type from file extension.
+
+    This function encapsulates the external library call to os.path.splitext() so it can be mocked in tests.
+
+    Args:
+        file_path: Path to the image file
+
+    Returns:
+        Image type (e.g., 'jpg', 'png')
+    """
+    _, ext = os.path.splitext(file_path)
+    image_type = ext.lstrip('.').lower()
+    if image_type not in ['jpeg', 'jpg', 'png', 'gif', 'webp']:
+        image_type = 'jpeg'  # Default to jpeg if unknown extension
+    return image_type
+
+
 def adapt_messages_to_openai(messages: List[LLMMessage]):
     new_messages: List[dict[str, Any]] = []
     for m in messages:
@@ -25,21 +72,17 @@ def adapt_messages_to_openai(messages: List[LLMMessage]):
                 # Add each image as a base64-encoded URL
                 for image_path in m.image_paths:
                     try:
-                        with open(image_path, "rb") as image_file:
-                            base64_image = base64.b64encode(image_file.read()).decode('utf-8')
-
-                            # Determine image type from file extension
-                            _, ext = os.path.splitext(image_path)
-                            image_type = ext.lstrip('.').lower()
-                            if image_type not in ['jpeg', 'jpg', 'png', 'gif', 'webp']:
-                                image_type = 'jpeg'  # Default to jpeg if unknown extension
-
-                            content.append({
-                                "type": "image_url",
-                                "image_url": {
-                                    "url": f"data:image/{image_type};base64,{base64_image}"
-                                }
-                            })
+                        # Use our encapsulated methods instead of direct library calls
+                        binary_data = read_file_as_binary(image_path)
+                        base64_image = encode_base64(binary_data)
+                        image_type = get_image_type(image_path)
+
+                        content.append({
+                            "type": "image_url",
+                            "image_url": {
+                                "url": f"data:image/{image_type};base64,{base64_image}"
+                            }
+                        })
                     except Exception as e:
                         logger.error("Failed to encode image", error=str(e), image_path=image_path)
 

mojentic/llm/llm_broker.py

@@ -1,9 +1,11 @@
 import json
+import time
 from typing import List, Optional, Type
 
 import structlog
 from pydantic import BaseModel
 
+from mojentic.tracer.tracer_system import TracerSystem
 from mojentic.llm.gateways.llm_gateway import LLMGateway
 from mojentic.llm.gateways.models import MessageRole, LLMMessage, LLMGatewayResponse
 from mojentic.llm.gateways.ollama import OllamaGateway
@@ -21,8 +23,10 @@ class LLMBroker():
     adapter: LLMGateway
     tokenizer: TokenizerGateway
     model: str
+    tracer: Optional[TracerSystem]
 
-    def __init__(self, model: str, gateway: Optional[LLMGateway] = None, tokenizer: Optional[TokenizerGateway] = None):
+    def __init__(self, model: str, gateway: Optional[LLMGateway] = None, tokenizer: Optional[TokenizerGateway] = None,
+                 tracer: Optional[TracerSystem] = None):
         """
         Create an instance of the LLMBroker.
 
@@ -36,8 +40,15 @@ class LLMBroker():
         tokenizer
             The gateway to use for tokenization. This is used to log approximate token counts for the LLM calls. If
             None, `mxbai-embed-large` is used on a local Ollama server.
+        tracer
+            Optional tracer system to record LLM calls and responses.
         """
         self.model = model
+        
+        # Use null_tracer if no tracer is provided
+        from mojentic.tracer import null_tracer
+        self.tracer = tracer or null_tracer
+        
         if tokenizer is None:
             self.tokenizer = TokenizerGateway()
         else:
@@ -72,7 +83,23 @@ class LLMBroker():
         """
         approximate_tokens = len(self.tokenizer.encode(self._content_to_count(messages)))
         logger.info(f"Requesting llm response with approx {approximate_tokens} tokens")
-
+        
+        # Convert messages to serializable dict for audit
+        messages_for_tracer = [m.dict() for m in messages]
+        
+        # Record LLM call in tracer
+        tools_for_tracer = [{"name": t.name, "description": t.description} for t in tools] if tools else None
+        self.tracer.record_llm_call(
+            self.model, 
+            messages_for_tracer, 
+            temperature,
+            tools=tools_for_tracer,
+            source=type(self)
+        )
+        
+        # Measure call duration for audit
+        start_time = time.time()
+        
         result: LLMGatewayResponse = self.adapter.complete(
             model=self.model,
             messages=messages,
@@ -80,6 +107,18 @@ class LLMBroker():
             temperature=temperature,
             num_ctx=num_ctx,
             num_predict=num_predict)
+        
+        call_duration_ms = (time.time() - start_time) * 1000
+        
+        # Record LLM response in tracer
+        tool_calls_for_tracer = [tc.dict() for tc in result.tool_calls] if result.tool_calls else None
+        self.tracer.record_llm_response(
+            self.model,
+            result.content,
+            tool_calls=tool_calls_for_tracer,
+            call_duration_ms=call_duration_ms,
+            source=type(self)
+        )
 
         if result.tool_calls and tools is not None:
             logger.info("Tool call requested")
@@ -89,7 +128,22 @@ class LLMBroker():
                                 None):
                     logger.info('Calling function', function=tool_call.name)
                     logger.info('Arguments:', arguments=tool_call.arguments)
+                    
+                    # Get the arguments before calling the tool
+                    tool_arguments = tool_call.arguments
+                    
+                    # Call the tool
                     output = tool.run(**tool_call.arguments)
+                    
+                    # Record tool call in tracer
+                    self.tracer.record_tool_call(
+                        tool_call.name,
+                        tool_arguments,
+                        output,
+                        caller="LLMBroker",
+                        source=type(self)
+                    )
+                    
                     logger.info('Function output', output=output)
                     messages.append(LLMMessage(role=MessageRole.Assistant, tool_calls=[tool_call]))
                     messages.append(
@@ -135,6 +189,35 @@ class LLMBroker():
         """
         approximate_tokens = len(self.tokenizer.encode(self._content_to_count(messages)))
         logger.info(f"Requesting llm response with approx {approximate_tokens} tokens")
+        
+        # Convert messages to serializable dict for audit
+        messages_for_tracer = [m.dict() for m in messages]
+        
+        # Record LLM call in tracer
+        self.tracer.record_llm_call(
+            self.model, 
+            messages_for_tracer, 
+            temperature,
+            tools=None,
+            source=type(self)
+        )
+        
+        # Measure call duration for audit
+        start_time = time.time()
+        
         result = self.adapter.complete(model=self.model, messages=messages, object_model=object_model,
                                        temperature=temperature, num_ctx=num_ctx, num_predict=num_predict)
+        
+        call_duration_ms = (time.time() - start_time) * 1000
+        
+        # Record LLM response in tracer with object representation
+        # Convert object to string for tracer
+        object_str = str(result.object.dict()) if hasattr(result.object, "dict") else str(result.object)
+        self.tracer.record_llm_response(
+            self.model,
+            f"Structured response: {object_str}",
+            call_duration_ms=call_duration_ms,
+            source=type(self)
+        )
+        
         return result.object

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,40 @@
 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):
+        # 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)
+        )
+        
+        # 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()