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

_examples/openai_gateway_enhanced_demo.py

@@ -6,11 +6,11 @@ for reasoning models vs chat models, provides detailed logging, and offers bette
 error handling.
 """
 
-import os
 from mojentic.llm.gateways.openai import OpenAIGateway
 from mojentic.llm.gateways.openai_model_registry import get_model_registry
 from mojentic.llm.gateways.models import LLMMessage, MessageRole
 
+
 def demonstrate_model_registry():
     """Demonstrate the model registry capabilities."""
     print("=== Model Registry Demonstration ===")
@@ -38,6 +38,7 @@ def demonstrate_model_registry():
     token_param = capabilities.get_token_limit_param()
     print(f"   → Defaulted to: type={capabilities.model_type.value}, token_param={token_param}")
 
+
 def demonstrate_parameter_adaptation():
     """Demonstrate parameter adaptation for different model types."""
     print("\n=== Parameter Adaptation Demonstration ===")
@@ -54,8 +55,14 @@ def demonstrate_parameter_adaptation():
     }
 
     adapted_args = gateway._adapt_parameters_for_model('o1-mini', original_args)
-    print(f"   Original: max_tokens={original_args.get('max_tokens')}, has_tools={'tools' in original_args}")
-    print(f"   Adapted: max_completion_tokens={adapted_args.get('max_completion_tokens')}, has_tools={'tools' in adapted_args}")
+    print(
+        f"   Original: max_tokens={original_args.get('max_tokens')}, "
+        f"has_tools={'tools' in original_args}"
+    )
+    print(
+        f"   Adapted: max_completion_tokens={adapted_args.get('max_completion_tokens')}, "
+        f"has_tools={'tools' in adapted_args}"
+    )
 
     print("\n2. Chat model parameter adaptation (gpt-4o):")
     original_args = {
@@ -69,6 +76,7 @@ def demonstrate_parameter_adaptation():
     print(f"   Original: max_tokens={original_args.get('max_tokens')}, has_tools={'tools' in original_args}")
     print(f"   Adapted: max_tokens={adapted_args.get('max_tokens')}, has_tools={'tools' in adapted_args}")
 
+
 def demonstrate_model_validation():
     """Demonstrate model parameter validation."""
     print("\n=== Model Validation Demonstration ===")
@@ -89,6 +97,7 @@ def demonstrate_model_validation():
     except Exception as e:
         print(f"   Validation error: {e}")
 
+
 def demonstrate_registry_extensibility():
     """Demonstrate how to extend the registry with new models."""
     print("\n=== Registry Extensibility Demonstration ===")
@@ -106,7 +115,7 @@ def demonstrate_registry_extensibility():
     )
 
     registry.register_model("o5-preview", new_capabilities)
-    print(f"   Registered o5-preview as reasoning model")
+    print("   Registered o5-preview as reasoning model")
 
     # Test the new model
     capabilities = registry.get_model_capabilities("o5-preview")
@@ -120,6 +129,7 @@ def demonstrate_registry_extensibility():
     capabilities = registry.get_model_capabilities("claude-3-opus")
     print(f"   claude-3-opus (inferred): type={capabilities.model_type.value}")
 
+
 if __name__ == "__main__":
     print("OpenAI Gateway Enhanced Infrastructure Demo")
     print("=" * 50)
@@ -137,4 +147,4 @@ if __name__ == "__main__":
     print("✓ Enhanced logging for debugging")
     print("✓ Parameter validation with helpful warnings")
     print("✓ Pattern matching for unknown models")
-    print("✓ Comprehensive test coverage")
+    print("✓ Comprehensive test coverage")

_examples/raw.py

@@ -18,4 +18,4 @@ anthropic_args = {
 
 response = client.messages.create(**anthropic_args)
 
-print(response.content[0].text)
+print(response.content[0].text)

_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