mojentic 0.8.4__py3-none-any.whl → 1.0.0__py3-none-any.whl

_examples/react/models/base.py

@@ -1,29 +1,78 @@
+"""Base data models for the ReAct pattern.
+
+This module defines the core data structures used throughout the ReAct
+implementation, including actions, plans, observations, and context.
+"""
 from enum import Enum
 from typing import List
 
-from pydantic import Field, BaseModel
+from pydantic import BaseModel, Field
 
 
 class NextAction(str, Enum):
+    """Enumeration of possible next actions in the ReAct loop."""
+
     PLAN = "PLAN"
     ACT = "ACT"
     FINISH = "FINISH"
 
 
 class ThoughtActionObservation(BaseModel):
-    thought: str = Field(..., description="The thought process behind the action taken in the current context.")
-    action: str = Field(..., description="The action taken in the current context.")
-    observation: str = Field(..., description="The observation made after the action taken in the current context.")
+    """A single step in the ReAct loop capturing thought, action, and observation.
+
+    This model represents one iteration of the ReAct pattern where the agent:
+    1. Thinks about what to do
+    2. Takes an action
+    3. Observes the result
+    """
+
+    thought: str = Field(
+        ...,
+        description="The thought process behind the action taken in the current context."
+    )
+    action: str = Field(
+        ...,
+        description="The action taken in the current context."
+    )
+    observation: str = Field(
+        ...,
+        description="The observation made after the action taken in the current context."
+    )
 
 
 class Plan(BaseModel):
-    steps: List[str] = Field([],
-                            description="How to answer the query, step by step, each step outlining an action to take.")
+    """A structured plan for solving a user query.
+
+    Contains a list of steps that outline how to approach answering the query.
+    """
+
+    steps: List[str] = Field(
+        [],
+        description="How to answer the query, step by step, each step outlining an action to take."
+    )
 
 
 class CurrentContext(BaseModel):
-    user_query: str = Field(..., description="The user query to which we are responding.")
-    plan: Plan = Field(Plan(steps=[]), description="The current plan of action for the current context.")
-    history: List[ThoughtActionObservation] = Field([],
-                                                   description="The history of actions taken and observations made in the current context.")
-    iteration: int = Field(0, description="The number of iterations taken in the current context.")
+    """The complete context for a ReAct session.
+
+    This model tracks everything needed to maintain state throughout the
+    reasoning and acting loop, including the user's query, the plan,
+    the history of actions, and the iteration count.
+    """
+
+    user_query: str = Field(
+        ...,
+        description="The user query to which we are responding."
+    )
+    plan: Plan = Field(
+        Plan(steps=[]),
+        description="The current plan of action for the current context."
+    )
+    history: List[ThoughtActionObservation] = Field(
+        [],
+        description="The history of actions taken and observations made in the current context."
+    )
+    iteration: int = Field(
+        0,
+        description="The number of iterations taken in the current context."
+    )

_examples/react/models/events.py

@@ -1,28 +1,96 @@
+"""Event definitions for the ReAct pattern.
+
+This module defines all event types used to coordinate the ReAct loop,
+including thinking, decisioning, tool calls, completion, and failure events.
+"""
 from pydantic import Field
 
 from mojentic import Event
+
 from .base import CurrentContext, NextAction
 
 
 class InvokeThinking(Event):
-    context: CurrentContext = Field(..., description="The current context as we work through our response.")
+    """Event to trigger the thinking/planning phase.
+
+    This event initiates the planning process where the agent creates
+    or refines a plan for answering the user's query.
+    """
+
+    context: CurrentContext = Field(
+        ...,
+        description="The current context as we work through our response."
+    )
 
 
 class InvokeDecisioning(Event):
-    context: CurrentContext = Field(..., description="The current context as we work through our response.")
+    """Event to trigger the decision-making phase.
+
+    This event initiates the decision process where the agent evaluates
+    the current plan and history to decide on the next action.
+    """
+
+    context: CurrentContext = Field(
+        ...,
+        description="The current context as we work through our response."
+    )
 
 
 class InvokeToolCall(Event):
-    context: CurrentContext = Field(..., description="The current context as we work through our response.")
-    thought: str = Field(..., description="The reasoning behind the decision.")
+    """Event to trigger a tool invocation.
+
+    This event carries the information needed to execute a specific tool
+    with given arguments, along with the reasoning behind the decision.
+    """
+
+    context: CurrentContext = Field(
+        ...,
+        description="The current context as we work through our response."
+    )
+    thought: str = Field(
+        ...,
+        description="The reasoning behind the decision."
+    )
     action: NextAction
+    tool: object = Field(
+        ...,
+        description="The tool instance to invoke."
+    )
+    tool_arguments: dict = Field(
+        default_factory=dict,
+        description="Arguments to pass to the tool."
+    )
 
 
 class FinishAndSummarize(Event):
-    context: CurrentContext = Field(..., description="The current context as we work through our response.")
-    thought: str = Field(..., description="The reasoning behind the decision.")
+    """Event to trigger the completion and summarization phase.
+
+    This event indicates that the agent has gathered sufficient information
+    to answer the user's query and should generate a final response.
+    """
+
+    context: CurrentContext = Field(
+        ...,
+        description="The current context as we work through our response."
+    )
+    thought: str = Field(
+        ...,
+        description="The reasoning behind the decision."
+    )
 
 
 class FailureOccurred(Event):
-    context: CurrentContext = Field(..., description="The current context as we work through our response.")
-    reason: str = Field(..., description="The reason for the failure.")
+    """Event to signal a failure in the ReAct loop.
+
+    This event captures errors or unrecoverable situations that prevent
+    the agent from continuing to process the user's query.
+    """
+
+    context: CurrentContext = Field(
+        ...,
+        description="The current context as we work through our response."
+    )
+    reason: str = Field(
+        ...,
+        description="The reason for the failure."
+    )

_examples/react.py

@@ -1,32 +1,82 @@
+"""ReAct Pattern Example.
+
+This example demonstrates a Reasoning and Acting (ReAct) loop where agents
+iteratively plan, decide, act, and summarize to answer user queries.
+
+The ReAct pattern consists of:
+1. Thinking Agent - Creates plans
+2. Decisioning Agent - Decides next actions
+3. Tool Call Agent - Executes tools
+4. Summarization Agent - Generates final answers
+"""
 from _examples.react.agents.decisioning_agent import DecisioningAgent
+from _examples.react.agents.summarization_agent import SummarizationAgent
 from _examples.react.agents.thinking_agent import ThinkingAgent
+from _examples.react.agents.tool_call_agent import ToolCallAgent
 from _examples.react.models.base import CurrentContext
-from _examples.react.models.events import InvokeThinking, InvokeDecisioning
-from mojentic import Router, Dispatcher
-from mojentic.agents import OutputAgent
+from _examples.react.models.events import (
+    FailureOccurred,
+    FinishAndSummarize,
+    InvokeDecisioning,
+    InvokeThinking,
+    InvokeToolCall,
+)
+from mojentic import Dispatcher, Router
+from mojentic.agents.output_agent import OutputAgent
 from mojentic.llm import LLMBroker
 
-# llm = LLMBroker("llama3.3-70b-32k")
-llm = LLMBroker("deepseek-r1:70b")
-thinking_agent = ThinkingAgent(llm)
-decisioning_agent = DecisioningAgent(llm)
 
-output_agent = OutputAgent()
+def main():
+    """Run the ReAct pattern example."""
+    # Initialize LLM broker - using qwen3:32b as it's widely available
+    llm = LLMBroker("qwen3:32b")
+    # Alternative models (uncomment if available):
+    # llm = LLMBroker("deepseek-r1:70b")
+    # llm = LLMBroker("qwen3:8b")
 
-router = Router({
-    InvokeThinking: [thinking_agent, output_agent],
-    InvokeDecisioning: [decisioning_agent, output_agent],
-})
+    # Create agents
+    thinking_agent = ThinkingAgent(llm)
+    decisioning_agent = DecisioningAgent(llm)
+    tool_call_agent = ToolCallAgent()
+    summarization_agent = SummarizationAgent(llm)
+    output_agent = OutputAgent()
 
-dispatcher = Dispatcher(router)
+    # Configure router - maps event types to agent handlers
+    router = Router({
+        InvokeThinking: [thinking_agent, output_agent],
+        InvokeDecisioning: [decisioning_agent, output_agent],
+        InvokeToolCall: [tool_call_agent, output_agent],
+        FinishAndSummarize: [summarization_agent, output_agent],
+        FailureOccurred: [output_agent],
+    })
 
-event = thinking_agent.receive_event(
-    InvokeThinking(
-        source=str,
-        context=CurrentContext(
-            user_query="What is the date next Friday?"
-        )
+    # Create dispatcher
+    dispatcher = Dispatcher(router)
+
+    # Create initial context
+    initial_context = CurrentContext(
+        user_query="What is the date next Friday?"
     )
-)
 
-dispatcher.dispatch(event)
+    # Start the ReAct loop
+    print("\n" + "=" * 80)
+    print("Starting ReAct Pattern Example")
+    print("=" * 80)
+    print(f"User Query: {initial_context.user_query}")
+    print("=" * 80 + "\n")
+
+    # Create and dispatch initial thinking event
+    initial_event = InvokeThinking(
+        source=type(main),
+        context=initial_context
+    )
+
+    dispatcher.dispatch(initial_event)
+
+    print("\n" + "=" * 80)
+    print("ReAct Pattern Example Complete")
+    print("=" * 80 + "\n")
+
+
+if __name__ == "__main__":
+    main()

_examples/recursive_agent.py

@@ -21,7 +21,7 @@ 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="qwen3:32b")
     llm = LLMBroker(model="qwen3:30b-a3b-q4_K_M")
 
     # Create the agent with a maximum of 3 iterations
@@ -78,7 +78,7 @@ async def demonstrate_async():
 
     # Create tasks for all problems and run them concurrently
     tasks = [solve_and_print(problem) for problem in problems]
-    solutions = await asyncio.gather(*tasks)
+    await asyncio.gather(*tasks)
 
     print("\nAll concurrent problems have been solved!")
 

_examples/simple_llm.py

@@ -25,9 +25,9 @@ class RequestAgent(BaseLLMAgent):
 
 
 # llm = LLMBroker("deepseek-r1:70b")
-# llm = LLMBroker("llama3.1-instruct-8b-32k")
-llm = LLMBroker("qwen2.5:0.5b")
-# llm = LLMBroker("llama3.1:8b", gateway=OllamaGateway(host="http://odin.local:11434"))
+# llm = LLMBroker("qwen3:14b")
+llm = LLMBroker("qwen3:0.5b")
+# llm = LLMBroker("qwen3:7b", gateway=OllamaGateway(host="http://odin.local:11434"))
 request_agent = RequestAgent(llm)
 output_agent = OutputAgent()
 

_examples/simple_llm_repl.py

@@ -27,7 +27,7 @@ class ChatOutputAgent(BaseAgent):
         return []
 
 
-llm = LLMBroker("llama3.1-instruct-8b-32k")
+llm = LLMBroker("qwen3:14b")
 request_agent = ChatAgent(llm)
 output_agent = ChatOutputAgent()
 

_examples/simple_structured.py

@@ -32,7 +32,7 @@ class RequestAgent(BaseLLMAgent):
         return [ResponseEvent(source=type(self), correlation_id=event.correlation_id, capitol=response)]
 
 
-llm = LLMBroker("llama3.1-instruct-8b-32k")
+llm = LLMBroker("qwen3:14b")
 request_agent = RequestAgent(llm)
 output_agent = OutputAgent()
 

_examples/simple_tool.py

@@ -33,8 +33,8 @@ class RequestAgent(BaseLLMAgent):
 
 
 # llm = LLMBroker("deepseek-r1:70b")
-# llm = LLMBroker("llama3.3-70b-32k")
-llm = LLMBroker("qwen2.5:7b")
+# llm = LLMBroker("qwen3:32b")
+llm = LLMBroker("qwen3:7b")
 request_agent = RequestAgent(llm)
 output_agent = OutputAgent()
 

_examples/solver_chat_session.py

@@ -4,11 +4,10 @@ from typing import List
 from mojentic.agents import IterativeProblemSolver
 from mojentic.llm.tools.date_resolver import ResolveDateTool
 from mojentic.llm.tools.llm_tool import LLMTool
+from mojentic.llm import LLMBroker, ChatSession
 
 logging.basicConfig(level=logging.WARN)
 
-from mojentic.llm import LLMBroker, ChatSession
-
 
 class IterativeProblemSolverTool(LLMTool):
     def __init__(self, llm: LLMBroker, tools: List[LLMTool]):
@@ -43,17 +42,12 @@ class IterativeProblemSolverTool(LLMTool):
 
 def main():
     # llm = LLMBroker(model="MFDoom/deepseek-r1-tool-calling:14b")
-    # llm = LLMBroker(model="qwen2.5:14b")
-    # llm = LLMBroker(model="qwen2.5:14b")
-    # llm = LLMBroker(model="qwen2.5:7b")
+    # llm = LLMBroker(model="qwen3:14b")
+    # llm = LLMBroker(model="qwen3:14b")
+    # llm = LLMBroker(model="qwen3:7b")
     llm = LLMBroker(model="qwq")
     # llm = LLMBroker(model="qwq:32b-fp16")
-    # llm = LLMBroker(model="llama3.3-70b-32k")
-
-    tools = [
-        ResolveDateTool(),
-        IterativeProblemSolverTool(llm=llm, tools=[ResolveDateTool()])
-    ]
+    # llm = LLMBroker(model="qwen3:32b")
 
     chat_session = ChatSession(llm, tools=[IterativeProblemSolverTool(llm=llm, tools=[ResolveDateTool()])])
 

_examples/streaming.py

@@ -1,34 +1,52 @@
+from mojentic.llm.llm_broker import LLMBroker
 from mojentic.llm.gateways.models import LLMMessage
 from mojentic.llm.gateways.ollama import OllamaGateway
 from mojentic.llm.tools.date_resolver import ResolveDateTool
 
-#
-# This is here 2025-02-21 to demonstrate a deficiency in Ollama/llama tool calling
-# using the Stream option. We can't get chunk by chunk responses from the LLM
-# when using tools. This limits our ability to explore streaming capabilities
-# in the mojentic API, so I'm pausing this work for now until this is resolved.
-# https://github.com/ollama/ollama/issues/7886
-#
-
 
 def main():
-    ollama = OllamaGateway()
+    """
+    Demonstrates streaming text generation with tool calling support.
+
+    This example shows how generate_stream() handles tool calls seamlessly:
+    1. Streams content as it arrives
+    2. Detects tool calls in the stream
+    3. Executes tools
+    4. Recursively streams the LLM's response after tool execution
+    """
+    gateway = OllamaGateway()
+    # gateway = OpenAIGateway(api_key=os.getenv("OPENAI_API_KEY"))
+    broker = LLMBroker(
+        model="qwen3:32b",
+        # model="gpt-5",
+        gateway=gateway
+    )
+
     date_tool = ResolveDateTool()
-    
-    stream = ollama.complete_stream(
-        model="qwen2.5:7b",
+
+    print("Streaming response with tool calling enabled...\n")
+
+    stream = broker.generate_stream(
         messages=[
-            LLMMessage(content="Tell me a story about a dragon. In your story, reference several dates relative to today, "
-                              "like 'three days from now' or 'last week'.")
+            LLMMessage(
+                content=(
+                    "Tell me a short story about a dragon. "
+                    "In your story, reference several dates relative to today, "
+                    "like 'three days from now' or 'last week'."
+                )
+            )
         ],
         tools=[date_tool],
-        temperature=0.5,
+        temperature=0.7,
         num_ctx=32768,
         num_predict=-1
     )
-    
+
     for chunk in stream:
-        print(chunk.content, end='', flush=True)
+        print(chunk, end='', flush=True)
+
+    print("\n\nDone!")
+
 
 if __name__ == "__main__":
-    main()
+    main()

_examples/tell_user_example.py

@@ -7,17 +7,17 @@ to display messages to the user without expecting a response.
 
 import logging
 
-logging.basicConfig(level=logging.WARN)
-
 from mojentic.agents.iterative_problem_solver import IterativeProblemSolver
 from mojentic.llm.tools.tell_user_tool import TellUserTool
 from mojentic.llm import LLMBroker
 
+logging.basicConfig(level=logging.WARN)
+
 
 def main():
     # Initialize the LLM broker with your preferred model
     # Uncomment one of the following lines or modify as needed:
-    # llm = LLMBroker(model="llama3.3-70b-32k")  # Ollama model
+    # llm = LLMBroker(model="qwen3:32b")  # Ollama model
     # llm = LLMBroker(model="gpt-4o")  # OpenAI model
     llm = LLMBroker(model="qwq")  # Default model for example
 
@@ -40,4 +40,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    main()

_examples/tracer_demo.py

@@ -1,31 +1,29 @@
 """
 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, 
+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
 
 
 def print_tracer_events(events):
     """Print tracer events using their printable_summary method."""
-    print(f"\n{'-'*80}")
+    print("\n{'-'*80}")
     print("Tracer Events:")
-    print(f"{'-'*80}")
+    print("{'-'*80}")
 
     for i, event in enumerate(events, 1):
-        print(f"{i}. {event.printable_summary()}")
+        print("{i}. {event.printable_summary()}")
         print()
 
 
@@ -35,7 +33,7 @@ def main():
     tracer = TracerSystem()
 
     # Create an LLM broker with the tracer
-    llm_broker = LLMBroker(model="llama3.3-70b-32k", tracer=tracer)
+    llm_broker = LLMBroker(model="gpt-oss:20b", tracer=tracer)
 
     # Create a date resolver tool that will also use the tracer
     date_tool = ResolveDateTool(llm_broker=llm_broker, tracer=tracer)
@@ -69,7 +67,7 @@ def main():
             turn_counter += 1
             conversation_correlation_ids[turn_counter] = correlation_id
 
-            print(f"[Turn {turn_counter}, correlation_id: {correlation_id[:8]}...]")
+            print("[Turn {turn_counter}, correlation_id: {correlation_id[:8]}...]")
             print("Assistant: ", end="")
 
             # For demonstration purposes, we'll use the chat_session normally
@@ -85,30 +83,30 @@ def main():
     # 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!")
+    print("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("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)}")
+    print("LLM Call Events: {len(llm_calls)}")
     if llm_calls:
-        print(f"Example: {llm_calls[0].printable_summary()}")
+        print("Example: {llm_calls[0].printable_summary()}")
 
     llm_responses = tracer.get_events(event_type=LLMResponseTracerEvent)
-    print(f"LLM Response Events: {len(llm_responses)}")
+    print("LLM Response Events: {len(llm_responses)}")
     if llm_responses:
-        print(f"Example: {llm_responses[0].printable_summary()}")
+        print("Example: {llm_responses[0].printable_summary()}")
 
     tool_calls = tracer.get_events(event_type=ToolCallTracerEvent)
-    print(f"Tool Call Events: {len(tool_calls)}")
+    print("Tool Call Events: {len(tool_calls)}")
     if tool_calls:
-        print(f"Example: {tool_calls[0].printable_summary()}")
+        print("Example: {tool_calls[0].printable_summary()}")
 
     # Show the last few events
     print("\nThe last few events:")
@@ -130,7 +128,7 @@ def main():
         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]}...):")
+            print("\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):
@@ -140,7 +138,7 @@ def main():
             related_events = tracer.get_events(filter_func=filter_by_correlation_id)
 
             if related_events:
-                print(f"Found {len(related_events)} related events")
+                print("Found {len(related_events)} related events")
                 print_tracer_events(related_events)
 
                 # Show how this helps trace the flow of a request
@@ -163,7 +161,7 @@ def main():
 
         print("Tool usage frequency:")
         for tool_name, count in tool_names.items():
-            print(f"  - {tool_name}: {count} calls")
+            print("  - {tool_name}: {count} calls")
 
 
 if __name__ == "__main__":