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

mojentic/tracer/null_tracer.py

@@ -12,20 +12,20 @@ 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
@@ -33,16 +33,17 @@ class NullTracer:
         """
         # 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:
+                      source: Any = None,
+                      correlation_id: str = None) -> None:
         """
         Do nothing implementation of record_llm_call.
-        
+
         Parameters
         ----------
         model : str
@@ -55,19 +56,22 @@ class NullTracer:
             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) -> None:
+                         source: Any = None,
+                         correlation_id: str = None) -> None:
         """
         Do nothing implementation of record_llm_response.
-        
+
         Parameters
         ----------
         model : str
@@ -80,19 +84,22 @@ class NullTracer:
             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) -> None:
+                       source: Any = None,
+                       correlation_id: str = None) -> None:
         """
         Do nothing implementation of record_tool_call.
-        
+
         Parameters
         ----------
         tool_name : str
@@ -105,19 +112,22 @@ class NullTracer:
             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) -> None:
+                               source: Any = None,
+                               correlation_id: str = None) -> None:
         """
         Do nothing implementation of record_agent_interaction.
-        
+
         Parameters
         ----------
         from_agent : str
@@ -130,10 +140,12 @@ class NullTracer:
             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,
@@ -141,7 +153,7 @@ class NullTracer:
                   filter_func: Optional[Callable[[TracerEvent], bool]] = None) -> List[TracerEvent]:
         """
         Return an empty list for any get_events request.
-        
+
         Parameters
         ----------
         event_type : Type[TracerEvent], optional
@@ -152,40 +164,40 @@ class NullTracer:
             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
+        pass

mojentic/tracer/tracer_events.py

@@ -3,6 +3,7 @@ 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
 
@@ -12,24 +13,25 @@ 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__}"
-    
+        return f"[{event_time}] {type(self).__name__} (correlation_id: {self.correlation_id})"
+
 
 class LLMCallTracerEvent(TracerEvent):
     """
@@ -39,25 +41,25 @@ class LLMCallTracerEvent(TracerEvent):
     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):
     """
@@ -67,23 +69,23 @@ class LLMResponseTracerEvent(TracerEvent):
     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
 
 
@@ -95,23 +97,23 @@ class ToolCallTracerEvent(TracerEvent):
     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
 
 
@@ -123,14 +125,14 @@ class AgentInteractionTracerEvent(TracerEvent):
     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
+
+        return summary

mojentic/tracer/tracer_system.py

@@ -24,16 +24,16 @@ 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
@@ -43,11 +43,11 @@ class TracerSystem:
         """
         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
@@ -55,18 +55,19 @@ class TracerSystem:
         """
         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:
+                      source: Any = None,
+                      correlation_id: str = None) -> None:
         """
         Record an LLM call event.
-        
+
         Parameters
         ----------
         model : str
@@ -79,29 +80,33 @@ class TracerSystem:
             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
+            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) -> None:
+                         source: Any = None,
+                         correlation_id: str = None) -> None:
         """
         Record an LLM response event.
-        
+
         Parameters
         ----------
         model : str
@@ -114,29 +119,33 @@ class TracerSystem:
             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
+            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) -> None:
+                       source: Any = None,
+                       correlation_id: str = None) -> None:
         """
         Record a tool call event.
-        
+
         Parameters
         ----------
         tool_name : str
@@ -149,29 +158,33 @@ class TracerSystem:
             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
+            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) -> None:
+                               source: Any = None,
+                               correlation_id: str = None) -> None:
         """
         Record an agent interaction event.
-        
+
         Parameters
         ----------
         from_agent : str
@@ -184,20 +197,23 @@ class TracerSystem:
             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
+            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,
@@ -205,10 +221,10 @@ class TracerSystem:
                   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
@@ -219,7 +235,7 @@ class TracerSystem:
             Include events with timestamp <= end_time.
         filter_func : Callable[[TracerEvent], bool], optional
             Custom filter function to apply to events.
-            
+
         Returns
         -------
         List[TracerEvent]
@@ -227,33 +243,33 @@ class TracerSystem:
         """
         # 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]
@@ -261,19 +277,19 @@ class TracerSystem:
         """
         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.
@@ -282,4 +298,4 @@ class TracerSystem:
 
 
 # Import and use the null tracer directly in client code via:
-# from mojentic.tracer import null_tracer
+# from mojentic.tracer import null_tracer