quantalogic 0.61.2__py3-none-any.whl → 0.80__py3-none-any.whl

quantalogic/codeact/history_manager.py

@@ -0,0 +1,94 @@
+"""History management module for storing and formatting agent steps."""
+
+from typing import Dict, List
+
+from loguru import logger
+from lxml import etree
+
+from .xml_utils import XMLResultHandler
+
+
+class HistoryManager:
+    """Manages the storage and formatting of agent step history with persistent context."""
+    
+    def __init__(self, max_tokens: int = 64*1024, system_prompt: str = "", task_description: str = ""):
+        """
+        Initialize the HistoryManager with a token limit and persistent context.
+
+        Args:
+            max_tokens (int): Maximum number of tokens for history formatting (default: 16000).
+            system_prompt (str): Persistent system-level instructions for the agent (default: "").
+            task_description (str): Persistent description of the current task (default: "").
+        """
+        self.max_tokens: int = max_tokens
+        self.system_prompt: str = system_prompt
+        self.task_description: str = task_description
+        self.store: List[Dict] = []
+        logger.debug(f"Initialized HistoryManager with system_prompt: '{system_prompt}', task_description: '{task_description}'")
+
+    def add_step(self, step_data: Dict) -> None:
+        """
+        Add a step to the history store.
+
+        Args:
+            step_data (Dict): Dictionary containing step details (step_number, thought, action, result).
+        """
+        self.store.append(step_data)
+        logger.debug(f"Added step {step_data['step_number']} to history")
+
+    def format_history(self, max_iterations: int) -> str:
+        """
+        Format the history with available variables, truncating to fit within max_tokens.
+
+        Args:
+            max_iterations (int): Maximum allowed iterations for context.
+
+        Returns:
+            str: Formatted string of previous steps, or "No previous steps" if empty.
+        """
+        included_steps: List[str] = []
+        total_tokens: int = 0
+        for step in reversed(self.store):
+            try:
+                root = etree.fromstring(step['result'])
+                vars_elem = root.find("Variables")
+                available_vars = (
+                    [var.get('name') for var in vars_elem.findall("Variable")]
+                    if vars_elem is not None else []
+                )
+            except etree.XMLSyntaxError:
+                available_vars = []
+
+            step_str: str = (
+                f"===== Step {step['step_number']} of {max_iterations} max =====\n"
+                f"Thought:\n{step['thought']}\n\n"
+                f"Action:\n{step['action']}\n\n"
+                f"Result:\n{XMLResultHandler.format_result_summary(step['result']) if step.get('result') else 'No result available'}\n"
+                f"Available variables: {', '.join(available_vars) or 'None'}"
+            )
+            step_tokens: int = len(step_str.split())
+            if total_tokens + step_tokens > self.max_tokens:
+                break
+            included_steps.append(step_str)
+            total_tokens += step_tokens
+        return "\n".join(reversed(included_steps)) or "No previous steps"
+
+    def get_full_context(self, max_iterations: int) -> str:
+        """
+        Return the full context including system prompt, task description, and formatted history.
+
+        Args:
+            max_iterations (int): Maximum allowed iterations for history formatting.
+
+        Returns:
+            str: Combined string of system prompt, task description, and history.
+        """
+        context_parts = []
+        if self.system_prompt:
+            context_parts.append(f"System Prompt:\n{self.system_prompt}")
+        if self.task_description:
+            context_parts.append(f"Task Description:\n{self.task_description}")
+        history_str = self.format_history(max_iterations)
+        if history_str != "No previous steps":
+            context_parts.append(f"History:\n{history_str}")
+        return "\n\n".join(context_parts)

quantalogic/codeact/llm_util.py

@@ -13,27 +13,8 @@ async def litellm_completion(
     notify_event: Optional[Callable] = None,
     **kwargs
 ) -> str:
-    """
-    A wrapper for litellm.acompletion that supports streaming and non-streaming modes.
-    
-    Args:
-        model (str): The model to use (e.g., "gemini/gemini-2.0-flash").
-        messages (List[dict]): The conversation history as a list of message dictionaries.
-        max_tokens (int): Maximum number of tokens to generate.
-        temperature (float): Sampling temperature for the model.
-        stream (bool): If True, stream tokens; if False, return the full response.
-        step (Optional[int]): Step number for event tracking (used in streaming mode).
-        notify_event (Optional[Callable]): Callback to trigger events during streaming.
-        **kwargs: Additional arguments to pass to litellm.acompletion.
-
-    Returns:
-        str: The generated response (full text in both modes).
-
-    Raises:
-        ValueError: If notify_event is missing when stream=True.
-        Exception: If the completion request fails.
-    """
-    from .events import StreamTokenEvent  # Local import to avoid circular dependency
+    """A wrapper for litellm.acompletion that supports streaming and non-streaming modes."""
+    from .events import StreamTokenEvent
 
     if stream:
         if notify_event is None:
@@ -73,4 +54,4 @@ async def litellm_completion(
             )
             return response.choices[0].message.content
         except Exception as e:
-            raise Exception(f"Completion failed: {e}")
+            raise Exception(f"Completion failed: {e}")

quantalogic/codeact/plugin_manager.py

@@ -0,0 +1,92 @@
+"""Plugin management module for dynamically loading components."""
+
+from importlib.metadata import entry_points
+from typing import List
+
+from loguru import logger
+
+from quantalogic.tools import Tool
+
+from .executor import Executor
+from .reasoner import Reasoner
+from .tools_manager import ToolRegistry
+
+
+class PluginManager:
+    """Manages dynamic loading of plugins for tools, reasoners, executors, and CLI commands."""
+    _instance = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super(PluginManager, cls).__new__(cls)
+            cls._instance.tools = ToolRegistry()
+            cls._instance.reasoners = {"default": Reasoner}
+            cls._instance.executors = {"default": Executor}
+            cls._instance.cli_commands = {}
+            cls._instance._plugins_loaded = False
+        return cls._instance
+
+    def load_plugins(self, force: bool = False) -> None:
+        """Load all plugins from registered entry points, handling duplicates gracefully.
+        
+        Args:
+            force: If True, reload plugins even if they were already loaded
+        """
+        if self._plugins_loaded and not force:
+            logger.debug("Plugins already loaded, skipping entire load process")
+            return
+        
+        # Clear existing plugins only if forcing reload
+        if force:
+            logger.info("Forcing plugin reload, clearing existing registrations")
+            self.tools = ToolRegistry()
+            self.reasoners = {"default": Reasoner}
+            self.executors = {"default": Executor}
+            self.cli_commands = {}
+            self._plugins_loaded = False
+
+        logger.debug("Loading plugins")
+        for group, store in [
+            ("quantalogic.tools", self.tools.load_toolboxes),
+            ("quantalogic.reasoners", self.reasoners),
+            ("quantalogic.executors", self.executors),
+            ("quantalogic.cli", self.cli_commands),
+        ]:
+            try:
+                eps = entry_points(group=group)
+                logger.debug(f"Found {len(eps)} entry points for group {group}")
+                for ep in eps:
+                    try:
+                        loaded = ep.load()
+                        if group == "quantalogic.tools":
+                            # Load static tools first
+                            store()
+                            # Then initialize dynamic MCP tools if applicable
+                            if ep.name == "quantalogic_toolbox_mcp":
+                                import asyncio
+
+                                from quantalogic_toolbox_mcp.tools import initialize_toolbox
+                                asyncio.run(initialize_toolbox(self.tools))
+                        else:
+                            store[ep.name] = loaded
+                            logger.info(f"Loaded plugin {ep.name} for {group}")
+                    except Exception as e:
+                        logger.warning(f"Skipping plugin {ep.name} for {group} due to error: {e}")
+            except Exception as e:
+                logger.error(f"Failed to retrieve entry points for {group}: {e}")
+        self._plugins_loaded = True
+        logger.info("Plugin loading completed")
+
+    def get_tools(self, force_reload: bool = False) -> List[Tool]:
+        """Return all registered tools.
+        
+        Args:
+            force_reload: If True, reload plugins before getting tools
+        """
+        if force_reload:
+            self.load_plugins(force=True)
+        else:
+            # Ensure plugins are loaded at least once, but don’t reload
+            if not self._plugins_loaded:
+                self.load_plugins()
+        return self.tools.get_tools()

quantalogic/codeact/prompts/generate_action.j2

@@ -1,26 +1,77 @@
-Solve the following task: '{{ task }}'
+Before generating the code, follow these steps:
+
+1. **Review the History**: Examine the <History> section below to understand previous thoughts, actions, and results.
+2. **Identify Available Variables**: Check the 'Currently available variables' list and 'Available variables' in the history. These are stored in the `context_vars` dictionary and can be accessed using `context_vars.get('variable_name', default_value)`.
+3. **Understand Variable Types**: Variables in `context_vars` are objects returned by tools, not just their string representations. Refer to tool documentation (e.g., `create_project_plan` returns `PlanResult` with `task_id`, `task_description`, `subtasks`) to access attributes directly (e.g., `plan.task_id`) rather than parsing strings.
+4. **Use Previous Results**: Incorporate relevant variables from prior steps to avoid redundant calculations and ensure continuity. For example, if `step1_plan` is a `PlanResult`, retrieve it with `plan = context_vars.get('step1_plan')` and use `plan.task_id`.
+5. **Plan Your Approach**: Based on the history and variables, determine the next logical step toward solving the task.
+
+Currently available variables from previous steps: {{ available_vars | join(', ') }}
+
+Solve the following task: 
+
+<Task>
+{{ task }}
+</Task>
+
 This is step {{ current_step }} out of {{ max_iterations }} allowed steps.
+
 Previous steps:
+
+<History>
 {{ history_str }}
+</History>
+
+Task:
 
 Generate a Python program with an async main() function that uses the available tools to take the next step toward solving the task.
 
 Essential Requirements:
-- Check context_vars for previous results: context_vars.get("variable_name")
-- Build upon previous steps when applicable, using variables listed in 'Available variables' from the history
-- Return "Task completed: [final answer]" if solved
-- Return intermediate results otherwise
-- Handle potential errors in tool arguments
-- Maintain proper async/await patterns
-- Important: When defining variables in the code, prefix them with 'step{{ current_step }}_' to ensure uniqueness across steps. For example, use 'step{{ current_step }}_intermediate_value'.
+
+- **Always check the 'Available variables' from the history** before proceeding. These are listed in the <History> section and stored in the `context_vars` dictionary as objects. Access them using `context_vars.get("variable_name", default_value)` to retrieve results from previous steps.
+- **Handle Variable Types Correctly**: Variables in `context_vars` are the actual objects returned by tools (e.g., `PlanResult` from `create_project_plan`). Use attribute access (e.g., `plan.task_id`) instead of string methods like `split()` unless the variable is explicitly a string. Check tool documentation for return types.
+- **Build upon previous steps** by using these variables when they are relevant. This avoids redundant work and ensures continuity. For example, if a previous step stored a `PlanResult` as `step1_plan`, retrieve it with `plan = context_vars.get('step1_plan')` and use `plan.task_id`.
+- When defining new variables, **prefix them with 'step{{ current_step }}_'** to ensure uniqueness (e.g., `step{{ current_step }}_result`). This prevents overwriting variables from earlier steps.
+- Return `"Task completed: [final answer]"` if the task is fully solved in this step.
+- Otherwise, return intermediate results as a string to be stored for future steps.
+- Handle potential errors in tool arguments gracefully, using try/except blocks if needed.
+- Use proper async/await syntax for all asynchronous operations.
+
+Variable Naming Convention:
+- Prefix all new variables with 'step{{ current_step }}_' (e.g., `step{{ current_step }}_result = ...`).
+- This ensures variables are unique across steps and traceable to their origin.
+
+Example of using variables from previous steps:
+
+Task: "Retrieve the plan from the previous step"
+History: 
+"===== Step 1 of 5 max =====
+Thought: Create a project plan
+Action: <code>import asyncio\nasync def main():\n    step1_plan = await quantalogic_planning_toolbox.create_project_plan(task_description='Write an article')\n    return f'{step1_plan}'</code>
+Result: task_id='abc123' task_description='Write an article' subtasks=[...]
+Available variables: step1_plan"
+
+Code:
+import asyncio
+
+async def main():
+    # Retrieve previous plan as an object, not a string
+    step1_plan = context_vars.get('step1_plan')
+    if step1_plan:
+        step2_task_id: str = step1_plan.task_id  # Access attribute directly
+        step2_retrieved_plan = await quantalogic_planning_toolbox.retrieve_project_plan(task_id=step2_task_id)
+        return f"Retrieved plan: {step2_retrieved_plan}"
+    return "Error: No plan found from previous step"
+
+Error Reflection:
+- If there were errors in previous steps, review the error messages in the <History> section and adjust your code to avoid similar issues.
+- For example, if a variable was missing, check `context_vars` with a default value.
+- If a tool call failed, verify the arguments and ensure they match the tool's requirements.
+- If an error like "'PlanResult' object has no attribute 'split'" occurred, it means you tried to treat an object as a string. Use attribute access instead (e.g., `.task_id`).
 
 The program must:
+
 1. Use only the provided async tools
 2. Follow a subset of Python 3.10+ syntax, doesn't allow unsafe operations such as eval() or exec()
 3. Include type annotations for variables, give very explicit names to variables
-4. Output progress information
-
-Example Context Usage:
-previous_value = context_vars.get('step1_intermediate_result')
-if previous_value:
-    next_step = await process_tool(input=previous_value)
+4. Output progress information

quantalogic/codeact/prompts/generate_program.j2

@@ -2,38 +2,51 @@ You are a Python code generator. Your task is to create a Python program that so
 
 "{{ task_description }}"
 
-You have access to the following pre-defined async tool functions, as defined with their signatures and descriptions:
+You have access to the following pre-defined async tool functions, grouped by toolbox:
 
-{{ tool_docstrings }}
+{% for toolbox_name, docstrings in tools_by_toolbox.items() %}
+### {{ toolbox_name }}
+{% for docstring in docstrings %}
+{{ docstring }}
 
-If applicable use tools to assess the situation and generate a Python program that solves the task step by step.
+{% endfor %}
+{% endfor %}
 
-If applicable use tools to verify the task is completed.
+If applicable, use tools to assess the situation and generate a Python program that solves the task step by step.
+
+If applicable, use tools to verify the task is completed.
 
 Instructions:
-1. Generate a simple vanilla Python program, avoid complex logic, return the program as a single string.
+1. Generate a very simple Python program, avoid complex logic, return the program as a single string. No more than 3 functions called.
 2. Include only the import for asyncio (import asyncio).
 3. Define an async function named main() that solves the task.
-4. Use the pre-defined tool functions directly by calling them with await and the appropriate arguments as specified in their descriptions.
-5. Do not redefine the tool functions within the program; assume they are already available in the namespace.
+4. Use the pre-defined tool functions by calling them with await and prefixing them with their toolbox name (e.g., `await {{ toolbox_name }}.tool_name(arg1, arg2)`). For core tools, use `default.tool_name` (e.g., `await default.agent_tool(...)`).
+5. Do not redefine the tool functions within the program; assume they are already available in the namespace under their toolbox names (e.g., `default.agent_tool` for core tools).
 6. Return the program as a plain string (no markdown or extra text).
 7. Strictly exclude asyncio.run(main()) or any code outside the main() function definition, including any 'if __name__ == "__main__":' block, as the runtime will handle execution of main().
-8. Express all string variables as multiline strings string, always start a string at the beginning of a line.
+8. Express all string variables as multiline strings, always start a string at the beginning of a line.
 9. Always return a string from main(); use "Task completed: [result]" if the task is solved, otherwise return intermediate results.
-10. Access variables from previous steps using the 'context_vars' dictionary (e.g., previous_value = context_vars.get("var_name", default_value))
+10. Access variables from previous steps using the `context_vars` dictionary:
+    - Use `context_vars.get("variable_name", default_value)` to safely retrieve variables (e.g., `previous_sum = context_vars.get("step1_sum", 0)`).
+    - Always specify a default value to handle cases where the variable might not exist.
+    - Check the history for 'Available variables' to identify relevant previous results.
+    - Use these variables to build on prior work rather than starting from scratch.
 11. Be careful to avoid programs that cannot terminate.
+12. When defining new variables, prefix them with 'step<current_step>_' (e.g., `step1_result`) to ensure uniqueness across steps.
+13. Never use dangerous functions like eval, or any other unsafe operations.
+14. If a return result is tool complex use an intermediate result to store it.
+15. VERY IMPORTANT: If the return type of a function is Any or not specified don't call another function after this just return the result, the result will be handled by the runtime.
 
-
-Example task: "Calculate running total by adding 5 to previous sum stored in context"
+Example task: "Translate the poem 'The sun rises' into Spanish using the agent_tool"
 Example output:
 import asyncio
 
 async def main():
-    # Retrieve previous total or default to 0
-    current_total = int(context_vars.get('running_total', 0))
-    
-    # Execute tool operation
-    new_total = await add_tool(a=current_total, b=5)
-    
-    # Return formatted result
-    return f"Task completed: {new_total}"
+    step1_poem: str = "The sun rises"
+    step1_system_prompt: str = "You are a translation expert."
+    step1_translation: str = await default.agent_tool(
+        system_prompt=step1_system_prompt,
+        prompt=f"Translate '{step1_poem}' into Spanish",
+        temperature=0.7
+    )
+    return f"Task completed: {step1_translation}"