mojentic 0.9.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

_examples/react/agents/decisioning_agent.py

@@ -1,32 +1,190 @@
-from mojentic.utils import format_block
-from ..formatters import format_current_context, format_available_tools
-from ..models.events import InvokeDecisioning, InvokeToolCall
+"""Decision-making agent for the ReAct pattern.
+
+This agent evaluates the current context and decides on the next action to take.
+"""
+from typing import List
+
+from pydantic import BaseModel, Field
+
 from mojentic.agents.base_llm_agent import BaseLLMAgent
+from mojentic.event import Event
 from mojentic.llm import LLMBroker
+from mojentic.llm.gateways.models import LLMMessage
 from mojentic.llm.tools.date_resolver import ResolveDateTool
+from mojentic.utils import format_block
+
+from ..formatters import format_available_tools, format_current_context
+from ..models.base import NextAction
+from ..models.events import (
+    FailureOccurred,
+    FinishAndSummarize,
+    InvokeDecisioning,
+    InvokeThinking,
+    InvokeToolCall,
+)
+
+
+class DecisionResponse(BaseModel):
+    """Structured response from the decisioning agent."""
+
+    thought: str = Field(
+        ...,
+        description="The reasoning behind the decision"
+    )
+    next_action: NextAction = Field(
+        ...,
+        description="What should happen next: PLAN, ACT, or FINISH"
+    )
+    tool_name: str | None = Field(
+        None,
+        description="Name of tool to use if next_action is ACT"
+    )
+    tool_arguments: dict = Field(
+        default_factory=dict,
+        description=("Arguments for the tool if next_action is ACT. "
+                     "IMPORTANT: Use the exact parameter names from the tool's descriptor. "
+                     "For resolve_date, use 'relative_date_found' not 'date_text'.")
+    )
 
 
 class DecisioningAgent(BaseLLMAgent):
+    """Agent responsible for deciding the next action in the ReAct loop.
+
+    This agent evaluates the current context, plan, and history to determine
+    whether to continue planning, take an action, or finish and summarize.
+    """
+
+    MAX_ITERATIONS = 10
+
     def __init__(self, llm: LLMBroker):
-        super().__init__(llm,
-                         "You are a careful decision maker, weighing the situation and making the best choice based on the information available.")
+        """Initialize the decisioning agent.
+
+        Args:
+            llm: The LLM broker to use for generating decisions.
+        """
+        super().__init__(
+            llm,
+            ("You are a careful decision maker, "
+             "weighing the situation and making the best choice "
+             "based on the information available.")
+        )
         self.tools = [ResolveDateTool()]
 
-        def receive_event(self, event: InvokeDecisioning):
-            prompt = self.prompt(event)
-            print(format_block(prompt))
-            tool_to_call = self.tools[0]
-            return [InvokeToolCall(source=type(self), context=event.context, tool=tool_to_call)]
+    def receive_event(self, event: Event) -> List[Event]:
+        """Process a decisioning event and determine the next action.
+
+        Args:
+            event: The decisioning event containing current context.
+
+        Returns:
+            List containing one of: InvokeToolCall, FinishAndSummarize,
+            InvokeThinking, or FailureOccurred event.
+        """
+        if not isinstance(event, InvokeDecisioning):
+            return []
 
-        def prompt(self, event: InvokeDecisioning):
-            prompt = f"""
+        # Check iteration limit
+        if event.context.iteration >= self.MAX_ITERATIONS:
+            return [FailureOccurred(
+                source=type(self),
+                context=event.context,
+                reason=f"Maximum iterations ({self.MAX_ITERATIONS}) exceeded",
+                correlation_id=event.correlation_id
+            )]
+
+        # Increment iteration counter
+        event.context.iteration += 1
+
+        prompt = self.prompt(event)
+        print(format_block(prompt))
+
+        try:
+            decision = self.llm.generate_object(
+                [LLMMessage(content=prompt)],
+                object_model=DecisionResponse
+            )
+            print(format_block(f"Decision: {decision}"))
+
+            # Route based on decision
+            if decision.next_action == NextAction.FINISH:
+                return [FinishAndSummarize(
+                    source=type(self),
+                    context=event.context,
+                    thought=decision.thought,
+                    correlation_id=event.correlation_id
+                )]
+
+            if decision.next_action == NextAction.ACT:
+                if not decision.tool_name:
+                    return [FailureOccurred(
+                        source=type(self),
+                        context=event.context,
+                        reason="ACT decision made but no tool specified",
+                        correlation_id=event.correlation_id
+                    )]
+
+                # Find the requested tool
+                tool = next(
+                    (t for t in self.tools
+                     if t.descriptor["function"]["name"] == decision.tool_name),
+                    None
+                )
+
+                if not tool:
+                    return [FailureOccurred(
+                        source=type(self),
+                        context=event.context,
+                        reason=f"Tool '{decision.tool_name}' not found",
+                        correlation_id=event.correlation_id
+                    )]
+
+                return [InvokeToolCall(
+                    source=type(self),
+                    context=event.context,
+                    thought=decision.thought,
+                    action=NextAction.ACT,
+                    tool=tool,
+                    tool_arguments=decision.tool_arguments,
+                    correlation_id=event.correlation_id
+                )]
+
+            # PLAN action - go back to thinking
+            return [InvokeThinking(
+                source=type(self),
+                context=event.context,
+                correlation_id=event.correlation_id
+            )]
+
+        except Exception as e:
+            return [FailureOccurred(
+                source=type(self),
+                context=event.context,
+                reason=f"Error during decision making: {str(e)}",
+                correlation_id=event.correlation_id
+            )]
+
+    def prompt(self, event: InvokeDecisioning):
+        """Generate the prompt for the decision-making LLM.
+
+        Args:
+            event: The decisioning event containing current context.
+
+        Returns:
+            The formatted prompt string.
+        """
+        return f"""
 You are to solve a problem by reasoning and acting on the information you have. Here is the current context:
 
 {format_current_context(event.context)}
 {format_available_tools(self.tools)}
 
 Your Instructions:
-Given our context and what we've done so far, and the tools available, create a step-by-step plan to answer the query. 
-            """.strip()
+Review the current plan and history. Decide what to do next:
+
+1. PLAN - If the plan is incomplete or needs refinement
+2. ACT - If you should take an action using one of the available tools
+3. FINISH - If you have enough information to answer the user's query
 
-            return prompt
+If you choose ACT, specify which tool to use and what arguments to pass.
+Think carefully about whether each step in the plan has been completed.
+        """.strip()

_examples/react/agents/summarization_agent.py

@@ -0,0 +1,89 @@
+"""Summarization agent for the ReAct pattern.
+
+This agent generates the final answer based on accumulated context.
+"""
+from typing import List
+
+from mojentic.agents.base_llm_agent import BaseLLMAgent
+from mojentic.event import Event
+from mojentic.llm import LLMBroker
+from mojentic.llm.gateways.models import LLMMessage
+from mojentic.utils import format_block
+
+from ..formatters import format_current_context
+from ..models.events import FailureOccurred, FinishAndSummarize
+
+
+class SummarizationAgent(BaseLLMAgent):
+    """Agent responsible for generating the final answer.
+
+    This agent reviews the context, plan, and history to synthesize
+    a complete answer to the user's original query.
+    """
+
+    def __init__(self, llm: LLMBroker):
+        """Initialize the summarization agent.
+
+        Args:
+            llm: The LLM broker to use for generating summaries.
+        """
+        super().__init__(
+            llm,
+            ("You are a helpful assistant who provides clear, "
+             "accurate answers based on the information gathered.")
+        )
+
+    def receive_event(self, event: Event) -> List[Event]:
+        """Generate a final answer based on the context.
+
+        Args:
+            event: The finish event containing the complete context.
+
+        Returns:
+            Empty list (terminal event) or list with FailureOccurred on error.
+        """
+        if not isinstance(event, FinishAndSummarize):
+            return []
+
+        try:
+            prompt = self.prompt(event)
+            print(format_block(prompt))
+
+            response = self.llm.generate([LLMMessage(content=prompt)])
+
+            print("\n" + "=" * 80)
+            print("FINAL ANSWER:")
+            print("=" * 80)
+            print(response)
+            print("=" * 80 + "\n")
+
+            # This is a terminal event - return empty list to stop the loop
+            return []
+
+        except Exception as e:
+            return [FailureOccurred(
+                source=type(self),
+                context=event.context,
+                reason=f"Error during summarization: {str(e)}",
+                correlation_id=event.correlation_id
+            )]
+
+    def prompt(self, event: FinishAndSummarize):
+        """Generate the prompt for the summarization LLM.
+
+        Args:
+            event: The finish event containing the complete context.
+
+        Returns:
+            The formatted prompt string.
+        """
+        return f"""
+Based on the following context, provide a clear and concise answer to the user's query.
+
+{format_current_context(event.context)}
+
+Your task:
+Review what we've learned and provide a direct answer to: "{event.context.user_query}"
+
+Be specific and use the information gathered during our process.
+        """.strip()

_examples/react/agents/thinking_agent.py

@@ -1,31 +1,100 @@
+"""Planning agent for the ReAct pattern.
+
+This agent creates structured plans for solving user queries.
+"""
+from typing import List
+
 from mojentic.agents.base_llm_agent import BaseLLMAgent
+from mojentic.event import Event
 from mojentic.llm import LLMBroker
 from mojentic.llm.gateways.models import LLMMessage
 from mojentic.llm.tools.date_resolver import ResolveDateTool
 from mojentic.utils import format_block
-from ..formatters import format_current_context, format_available_tools
 
+from ..formatters import format_available_tools, format_current_context
 from ..models.base import Plan, ThoughtActionObservation
-from ..models.events import InvokeThinking, InvokeDecisioning
+from ..models.events import FailureOccurred, InvokeDecisioning, InvokeThinking
 
 
 class ThinkingAgent(BaseLLMAgent):
+    """Agent responsible for creating plans in the ReAct loop.
+
+    This agent analyzes the user query and available tools to create
+    a step-by-step plan for answering the query.
+    """
+
     def __init__(self, llm: LLMBroker):
-        super().__init__(llm,
-                         "You are a task coordinator, who breaks down tasks into component steps to be performed by others.")
+        """Initialize the thinking agent.
+
+        Args:
+            llm: The LLM broker to use for generating plans.
+        """
+        super().__init__(
+            llm,
+            ("You are a task coordinator, "
+             "who breaks down tasks into component steps "
+             "to be performed by others.")
+        )
         self.tools = [ResolveDateTool()]
 
-    def receive_event(self, event: InvokeThinking):
-        prompt = self.prompt(event)
-        print(format_block(prompt))
-        plan: Plan = self.llm.generate_object([LLMMessage(content=prompt)], object_model=Plan)
-        print(format_block(str(plan)))
-        event.context.plan = plan
-        event.context.history.append(ThoughtActionObservation(thought="I have no plan yet.", action="Create a plan.",
-                                                              observation="Ready for next step."))
-        return InvokeDecisioning(source=type(self), context=event.context)
+    def receive_event(self, event: Event) -> List[Event]:
+        """Process a thinking event and generate a plan.
+
+        Args:
+            event: The thinking event containing current context.
+
+        Returns:
+            List containing InvokeDecisioning event with updated plan,
+            or FailureOccurred on error.
+        """
+        if not isinstance(event, InvokeThinking):
+            return []
+
+        try:
+            prompt = self.prompt(event)
+            print(format_block(prompt))
+
+            plan: Plan = self.llm.generate_object(
+                [LLMMessage(content=prompt)],
+                object_model=Plan
+            )
+            print(format_block(str(plan)))
+
+            # Update context with new plan
+            event.context.plan = plan
+
+            # Add planning step to history
+            event.context.history.append(
+                ThoughtActionObservation(
+                    thought="I need to create a plan to solve this query.",
+                    action="Created a step-by-step plan.",
+                    observation=f"Plan has {len(plan.steps)} steps."
+                )
+            )
+
+            return [InvokeDecisioning(
+                source=type(self),
+                context=event.context,
+                correlation_id=event.correlation_id
+            )]
+
+        except Exception as e:
+            return [FailureOccurred(
+                source=type(self),
+                context=event.context,
+                reason=f"Error during planning: {str(e)}",
+                correlation_id=event.correlation_id
+            )]
 
     def prompt(self, event: InvokeThinking):
+        """Generate the prompt for the planning LLM.
+
+        Args:
+            event: The thinking event containing current context.
+
+        Returns:
+            The formatted prompt string.
+        """
         return f"""
 You are to solve a problem by reasoning and acting on the information you have. Here is the current context:
 
@@ -33,5 +102,6 @@ You are to solve a problem by reasoning and acting on the information you have.
 {format_available_tools(self.tools)}
 
 Your Instructions:
-Given our context and what we've done so far, and the tools available, create a step-by-step plan to answer the query. 
+Given our context and what we've done so far, and the tools available, create a step-by-step plan to answer the query.
+Each step should be concrete and actionable. Consider which tools you'll need to use.
         """.strip()

_examples/react/agents/tool_call_agent.py

@@ -0,0 +1,83 @@
+"""Tool execution agent for the ReAct pattern.
+
+This agent handles the actual execution of tools and captures the results.
+"""
+from typing import List
+
+from mojentic.agents.base_agent import BaseAgent
+from mojentic.event import Event
+
+from ..models.base import ThoughtActionObservation
+from ..models.events import FailureOccurred, InvokeDecisioning, InvokeToolCall
+
+
+class ToolCallAgent(BaseAgent):
+    """Agent responsible for executing tool calls.
+
+    This agent receives tool call events, executes the specified tool,
+    and updates the context with the results before continuing to the
+    decisioning phase.
+    """
+
+    def receive_event(self, event: Event) -> List[Event]:
+        """Execute a tool and update the context.
+
+        Args:
+            event: The tool call event containing the tool and arguments.
+
+        Returns:
+            List containing InvokeDecisioning event with updated context,
+            or FailureOccurred on error.
+        """
+        if not isinstance(event, InvokeToolCall):
+            return []
+
+        try:
+            tool = event.tool
+            tool_name = tool.name
+            arguments = event.tool_arguments
+
+            print(f"\nExecuting tool: {tool_name}")
+            print(f"Arguments: {arguments}")
+
+            # Execute the tool using call_tool method
+            result = tool.call_tool(
+                correlation_id=event.correlation_id,
+                **arguments
+            )
+
+            print(f"Result: {result}")
+
+            # Extract the text content from the result
+            result_text = result
+            if isinstance(result, dict) and "content" in result:
+                # Extract text from content array
+                content_items = result["content"]
+                if content_items and isinstance(content_items, list):
+                    result_text = content_items[0].get("text", str(result))
+
+            # Add to history
+            event.context.history.append(
+                ThoughtActionObservation(
+                    thought=event.thought,
+                    action=f"Called {tool_name} with {arguments}",
+                    observation=str(result_text)
+                )
+            )
+
+            # Continue to decisioning
+            return [InvokeDecisioning(
+                source=type(self),
+                context=event.context,
+                correlation_id=event.correlation_id
+            )]
+
+        except Exception as e:
+            import traceback
+            traceback.print_exc()
+            return [FailureOccurred(
+                source=type(self),
+                context=event.context,
+                reason=f"Tool execution failed: {str(e)}",
+                correlation_id=event.correlation_id
+            )]

_examples/react/formatters.py

@@ -1,7 +1,20 @@
+"""Formatting utilities for the ReAct pattern implementation.
+
+This module provides helper functions for formatting context and tool information
+into human-readable strings for LLM prompts.
+"""
 from .models.base import CurrentContext
 
 
-def format_current_context(context: CurrentContext):
+def format_current_context(context: CurrentContext) -> str:
+    """Format the current context into a readable string.
+
+    Args:
+        context: The current context containing query, plan, and history.
+
+    Returns:
+        A formatted multi-line string describing the current context.
+    """
     user_query = f"The user has asked us to answer the following query:\n> {context.user_query}\n"
 
     plan = "You have not yet made a plan.\n"
@@ -12,7 +25,7 @@ def format_current_context(context: CurrentContext):
 
     history = "No steps have yet been taken.\n"
     if context.history:
-        history = "What's been done so far':\n"
+        history = "What's been done so far:\n"
         history += "\n".join(
             f"{i + 1}.\n    Thought: {step.thought}\n    Action: {step.action}\n    Observation: {step.observation}"
             for i, step in enumerate(context.history))
@@ -20,11 +33,32 @@ def format_current_context(context: CurrentContext):
 
     return f"Current Context:\n{user_query}{plan}{history}\n"
 
-def format_available_tools(tools):
+
+def format_available_tools(tools) -> str:
+    """Format the available tools into a readable list.
+
+    Args:
+        tools: A list of tool objects with descriptor dictionaries.
+
+    Returns:
+        A formatted string listing available tools and their descriptions.
+    """
     output = ""
     if tools:
         output += "Tools available:\n"
         for tool in tools:
-            output += f"- {tool.descriptor["function"]["name"]}: {tool.descriptor["function"]["description"]}\n"
+            func_descriptor = tool.descriptor['function']
+            output += f"- {func_descriptor['name']}: {func_descriptor['description']}\n"
+
+            # Add parameter information
+            if 'parameters' in func_descriptor:
+                params = func_descriptor['parameters']
+                if 'properties' in params:
+                    output += "  Parameters:\n"
+                    for param_name, param_info in params['properties'].items():
+                        param_desc = param_info.get('description', '')
+                        is_required = param_name in params.get('required', [])
+                        req_str = " (required)" if is_required else " (optional)"
+                        output += f"    - {param_name}{req_str}: {param_desc}\n"
 
     return output

_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."
+    )