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

_examples/recursive_agent.py

@@ -42,7 +42,7 @@ async def demonstrate_async():
     print(f"\nProblem (With Event Handling): {problem2}")
 
     # Set up event handlers for monitoring the solution process
-    from mojentic.agents.simple_recursive_agent import ProblemSolvedEvent, IterationCompletedEvent
+    from mojentic.agents.simple_recursive_agent import GoalAchievedEvent, IterationCompletedEvent
 
     # Define event handlers
     def on_iteration_completed(event):
@@ -53,7 +53,7 @@ async def demonstrate_async():
 
     # Subscribe to events
     unsubscribe_iteration = agent.emitter.subscribe(IterationCompletedEvent, on_iteration_completed)
-    unsubscribe_solved = agent.emitter.subscribe(ProblemSolvedEvent, on_problem_solved)
+    unsubscribe_solved = agent.emitter.subscribe(GoalAchievedEvent, on_problem_solved)
 
     # Solve the problem
     solution2 = await agent.solve(problem2)

_examples/tracer_demo.py

@@ -4,12 +4,17 @@ 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.
+
+It also demonstrates how correlation_id is used to trace related events
+across the system, allowing you to track the flow of a request from start to finish.
 """
+import uuid
 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.gateways.models import LLMMessage, MessageRole
 from mojentic.llm.tools.date_resolver import ResolveDateTool
 
 
@@ -18,7 +23,7 @@ def print_tracer_events(events):
     print(f"\n{'-'*80}")
     print("Tracer Events:")
     print(f"{'-'*80}")
-    
+
     for i, event in enumerate(events, 1):
         print(f"{i}. {event.printable_summary()}")
         print()
@@ -28,70 +33,126 @@ 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])
-    
+
+    # Dictionary to store correlation_ids for each conversation turn
+    # This allows us to track related events across the system
+    conversation_correlation_ids = {}
+
     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("Each interaction is assigned a unique correlation_id to trace related events.")
     print("Press Enter with no input to exit and see the trace summary.")
     print("-" * 80)
-    
+
     # Interactive chat session
+    turn_counter = 0
     while True:
         query = input("You: ")
         if not query:
             print("Exiting chat session...")
             break
         else:
+            # Generate a unique correlation_id for this conversation turn
+            # In a real system, this would be passed from the initiating event
+            # to all downstream events to maintain the causal chain
+            correlation_id = str(uuid.uuid4())
+            turn_counter += 1
+            conversation_correlation_ids[turn_counter] = correlation_id
+
+            print(f"[Turn {turn_counter}, correlation_id: {correlation_id[:8]}...]")
             print("Assistant: ", end="")
+
+            # For demonstration purposes, we'll use the chat_session normally
+            # In a production system, you would modify ChatSession to accept and use correlation_id
             response = chat_session.send(query)
+
+            # Alternatively, you could use the LLMBroker directly with correlation_id:
+            # messages = [LLMMessage(role=MessageRole.User, content=query)]
+            # response = llm_broker.generate(messages, tools=[date_tool], correlation_id=correlation_id)
+
             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)")
-    
+
+    # Demonstrate filtering events by correlation_id
+    print("\nFiltering events by correlation_id:")
+    print("This is a powerful feature that allows you to trace all events related to a specific request")
+
+    # If we have any conversation turns, show events for the first turn
+    if conversation_correlation_ids:
+        # Get the correlation_id for the first turn
+        first_turn_id = 1
+        first_correlation_id = conversation_correlation_ids.get(first_turn_id)
+
+        if first_correlation_id:
+            print(f"\nEvents for conversation turn {first_turn_id} (correlation_id: {first_correlation_id[:8]}...):")
+
+            # Define a filter function that checks the correlation_id
+            def filter_by_correlation_id(event):
+                return event.correlation_id == first_correlation_id
+
+            # Get all events with this correlation_id
+            related_events = tracer.get_events(filter_func=filter_by_correlation_id)
+
+            if related_events:
+                print(f"Found {len(related_events)} related events")
+                print_tracer_events(related_events)
+
+                # Show how this helps trace the flow of a request
+                print("\nThe correlation_id allows you to trace the complete flow of a request:")
+                print("1. From the initial LLM call")
+                print("2. To the LLM response")
+                print("3. To any tool calls triggered by the LLM")
+                print("4. And any subsequent LLM calls with the tool results")
+                print("\nThis creates a complete audit trail for debugging and observability.")
+            else:
+                print("No events found with this correlation_id. This is unexpected and may indicate an issue.")
+
     # Show how to extract specific information from events
     if tool_calls:
         print("\nDetailed analysis example - Tool usage stats:")
@@ -99,11 +160,11 @@ def main():
         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()
+    main()

mojentic/agents/simple_recursive_agent.py

@@ -8,17 +8,16 @@ from typing import List, Optional
 
 from pydantic import BaseModel
 
-from mojentic.llm.gateways.models import LLMMessage
+from mojentic.llm.chat_session import ChatSession
 from mojentic.llm.llm_broker import LLMBroker
 from mojentic.llm.tools.llm_tool import LLMTool
-from mojentic.llm.chat_session import ChatSession
 
 
-class ProblemState(BaseModel):
+class GoalState(BaseModel):
     """
     Represents the state of a problem-solving process.
     """
-    problem: str
+    goal: str
     iteration: int = 0
     max_iterations: int = 5
     solution: Optional[str] = None
@@ -29,10 +28,10 @@ class SolverEvent(BaseModel):
     """
     Base class for solver events.
     """
-    state: ProblemState
+    state: GoalState
 
 
-class ProblemSubmittedEvent(SolverEvent):
+class GoalSubmittedEvent(SolverEvent):
     """
     Event triggered when a problem is submitted for solving.
     """
@@ -46,14 +45,14 @@ class IterationCompletedEvent(SolverEvent):
     response: str
 
 
-class ProblemSolvedEvent(SolverEvent):
+class GoalAchievedEvent(SolverEvent):
     """
     Event triggered when a problem is solved.
     """
     pass
 
 
-class ProblemFailedEvent(SolverEvent):
+class GoalFailedEvent(SolverEvent):
     """
     Event triggered when a problem cannot be solved.
     """
@@ -168,7 +167,7 @@ class SimpleRecursiveAgent:
         )
 
         # Set up event handlers
-        self.emitter.subscribe(ProblemSubmittedEvent, self._handle_problem_submitted)
+        self.emitter.subscribe(GoalSubmittedEvent, self._handle_problem_submitted)
         self.emitter.subscribe(IterationCompletedEvent, self._handle_iteration_completed)
 
     async def solve(self, problem: str) -> str:
@@ -189,7 +188,7 @@ class SimpleRecursiveAgent:
         solution_future = asyncio.Future()
 
         # Create the initial problem state
-        state = ProblemState(problem=problem, max_iterations=self.max_iterations)
+        state = GoalState(goal=problem, max_iterations=self.max_iterations)
 
         # Define handlers for completion events
         async def handle_solution_event(event):
@@ -197,12 +196,12 @@ class SimpleRecursiveAgent:
                 solution_future.set_result(event.state.solution)
 
         # Subscribe to completion events
-        self.emitter.subscribe(ProblemSolvedEvent, handle_solution_event)
-        self.emitter.subscribe(ProblemFailedEvent, handle_solution_event)
+        self.emitter.subscribe(GoalAchievedEvent, handle_solution_event)
+        self.emitter.subscribe(GoalFailedEvent, handle_solution_event)
         self.emitter.subscribe(TimeoutEvent, handle_solution_event)
 
         # Start the solving process
-        self.emitter.emit(ProblemSubmittedEvent(state=state))
+        self.emitter.emit(GoalSubmittedEvent(state=state))
 
         # Wait for the solution or timeout
         try:
@@ -215,13 +214,13 @@ class SimpleRecursiveAgent:
                 self.emitter.emit(TimeoutEvent(state=state))
             return timeout_message
 
-    async def _handle_problem_submitted(self, event: ProblemSubmittedEvent):
+    async def _handle_problem_submitted(self, event: GoalSubmittedEvent):
         """
         Handle a problem submitted event.
 
         Parameters
         ----------
-        event : ProblemSubmittedEvent
+        event : GoalSubmittedEvent
             The problem submitted event to handle
         """
         # Start the first iteration
@@ -243,31 +242,31 @@ class SimpleRecursiveAgent:
         if "FAIL".lower() in response.lower():
             state.solution = f"Failed to solve after {state.iteration} iterations:\n{response}"
             state.is_complete = True
-            self.emitter.emit(ProblemFailedEvent(state=state))
+            self.emitter.emit(GoalFailedEvent(state=state))
             return
         elif "DONE".lower() in response.lower():
             state.solution = response
             state.is_complete = True
-            self.emitter.emit(ProblemSolvedEvent(state=state))
+            self.emitter.emit(GoalAchievedEvent(state=state))
             return
 
         # Check if we've reached the maximum number of iterations
         if state.iteration >= state.max_iterations:
             state.solution = f"Best solution after {state.max_iterations} iterations:\n{response}"
             state.is_complete = True
-            self.emitter.emit(ProblemSolvedEvent(state=state))
+            self.emitter.emit(GoalAchievedEvent(state=state))
             return
 
         # If the problem is not solved and we haven't reached max_iterations, continue with next iteration
         await self._process_iteration(state)
 
-    async def _process_iteration(self, state: ProblemState):
+    async def _process_iteration(self, state: GoalState):
         """
         Process a single iteration of the problem-solving process.
 
         Parameters
         ----------
-        state : ProblemState
+        state : GoalState
             The current state of the problem-solving process
         """
         # Increment the iteration counter
@@ -276,7 +275,7 @@ class SimpleRecursiveAgent:
         # Create a prompt for the LLM
         prompt = f"""
 Given the user request:
-{state.problem}
+{state.goal}
 
 Use the tools at your disposal to act on their request. You may wish to create a step-by-step plan for more complicated requests.
 

mojentic/llm/llm_broker.py

@@ -44,11 +44,11 @@ class LLMBroker():
             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:
@@ -58,7 +58,8 @@ class LLMBroker():
         else:
             self.adapter = gateway
 
-    def generate(self, messages: List[LLMMessage], tools=None, temperature=1.0, num_ctx=32768, num_predict=-1) -> str:
+    def generate(self, messages: List[LLMMessage], tools=None, temperature=1.0, num_ctx=32768, num_predict=-1, 
+              correlation_id: str = None) -> str:
         """
         Generate a text response from the LLM.
 
@@ -75,6 +76,8 @@ class LLMBroker():
             The number of context tokens to use. Defaults to 32768.
         num_predict : int
             The number of tokens to predict. Defaults to no limit.
+        correlation_id : str
+            UUID string that is copied from cause-to-affect for tracing events.
 
         Returns
         -------
@@ -83,10 +86,10 @@ 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(
@@ -94,12 +97,13 @@ class LLMBroker():
             messages_for_tracer, 
             temperature,
             tools=tools_for_tracer,
-            source=type(self)
+            source=type(self),
+            correlation_id=correlation_id
         )
-        
+
         # Measure call duration for audit
         start_time = time.time()
-        
+
         result: LLMGatewayResponse = self.adapter.complete(
             model=self.model,
             messages=messages,
@@ -107,9 +111,9 @@ 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(
@@ -117,7 +121,8 @@ class LLMBroker():
             result.content,
             tool_calls=tool_calls_for_tracer,
             call_duration_ms=call_duration_ms,
-            source=type(self)
+            source=type(self),
+            correlation_id=correlation_id
         )
 
         if result.tool_calls and tools is not None:
@@ -128,28 +133,29 @@ 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)
+                        source=type(self),
+                        correlation_id=correlation_id
                     )
-                    
+
                     logger.info('Function output', output=output)
                     messages.append(LLMMessage(role=MessageRole.Assistant, tool_calls=[tool_call]))
                     messages.append(
                         LLMMessage(role=MessageRole.Tool, content=json.dumps(output), tool_calls=[tool_call]))
                     # {'role': 'tool', 'content': str(output), 'name': tool_call.name, 'tool_call_id': tool_call.id})
-                    return self.generate(messages, tools, temperature, num_ctx, num_predict)
+                    return self.generate(messages, tools, temperature, num_ctx, num_predict, correlation_id=correlation_id)
                 else:
                     logger.warn('Function not found', function=tool_call.name)
                     logger.info('Expected usage of missing function', expected_usage=tool_call)
@@ -165,7 +171,7 @@ class LLMBroker():
         return content
 
     def generate_object(self, messages: List[LLMMessage], object_model: Type[BaseModel], temperature=1.0, num_ctx=32768,
-                        num_predict=-1) -> BaseModel:
+                        num_predict=-1, correlation_id: str = None) -> BaseModel:
         """
         Generate a structured response from the LLM and return it as an object.
 
@@ -181,6 +187,8 @@ class LLMBroker():
             The number of context tokens to use. Defaults to 32768.
         num_predict : int
             The number of tokens to predict. Defaults to no limit.
+        correlation_id : str
+            UUID string that is copied from cause-to-affect for tracing events.
 
         Returns
         -------
@@ -189,27 +197,28 @@ 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)
+            source=type(self),
+            correlation_id=correlation_id
         )
-        
+
         # 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)
@@ -217,7 +226,8 @@ class LLMBroker():
             self.model,
             f"Structured response: {object_str}",
             call_duration_ms=call_duration_ms,
-            source=type(self)
+            source=type(self),
+            correlation_id=correlation_id
         )
-        
+
         return result.object

mojentic/llm/tools/llm_tool.py

@@ -9,7 +9,7 @@ class LLMTool:
     def __init__(self, tracer: Optional[TracerSystem] = None):
         """
         Initialize an LLM tool with optional tracer system.
-        
+
         Parameters
         ----------
         tracer : TracerSystem, optional
@@ -18,22 +18,23 @@ class LLMTool:
         # 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)
+            source=type(self),
+            correlation_id=correlation_id
         )
-        
+
         # Format the result
         if isinstance(result, dict):
             result = json.dumps(result)