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

quantalogic/codeact/react_agent.py

@@ -0,0 +1,318 @@
+"""Core implementation of the ReAct framework for reasoning and acting."""
+
+import asyncio
+import time
+from typing import Callable, Dict, List, Optional, Tuple
+
+from loguru import logger
+from lxml import etree
+
+from quantalogic.tools import Tool
+
+from .events import (
+    ActionExecutedEvent,
+    ActionGeneratedEvent,
+    ErrorOccurredEvent,
+    StepCompletedEvent,
+    StepStartedEvent,
+    TaskCompletedEvent,
+    TaskStartedEvent,
+    ThoughtGeneratedEvent,
+)
+from .executor import BaseExecutor, Executor
+from .history_manager import HistoryManager
+from .llm_util import litellm_completion
+from .reasoner import BaseReasoner, Reasoner
+from .tools_manager import ToolRegistry
+from .xml_utils import XMLResultHandler
+
+
+class ReActAgent:
+    """Implements the ReAct framework for reasoning and acting with enhanced memory management."""
+    
+    def __init__(
+        self,
+        model: str,
+        tools: List[Tool],
+        max_iterations: int = 5,
+        max_history_tokens: int = 2000,
+        system_prompt: str = "",  # New parameter for persistent context
+        task_description: str = "",  # New parameter for persistent context
+        reasoner: Optional[BaseReasoner] = None,
+        executor: Optional[BaseExecutor] = None,
+        tool_registry: Optional[ToolRegistry] = None,
+        history_manager: Optional[HistoryManager] = None,
+        error_handler: Optional[Callable[[Exception, int], bool]] = None
+    ) -> None:
+        """
+        Initialize the ReActAgent with tools, reasoning, execution, and memory components.
+
+        Args:
+            model (str): Language model identifier.
+            tools (List[Tool]): List of available tools.
+            max_iterations (int): Maximum reasoning steps (default: 5).
+            max_history_tokens (int): Max tokens for history (default: 2000).
+            system_prompt (str): Persistent system instructions (default: "").
+            task_description (str): Persistent task context (default: "").
+            reasoner (Optional[BaseReasoner]): Custom reasoner instance.
+            executor (Optional[BaseExecutor]): Custom executor instance.
+            tool_registry (Optional[ToolRegistry]): Custom tool registry.
+            history_manager (Optional[HistoryManager]): Custom history manager.
+            error_handler (Optional[Callable[[Exception, int], bool]]): Error handler callback.
+        """
+        self.tool_registry = tool_registry or ToolRegistry()
+        for tool in tools:
+            self.tool_registry.register(tool)
+        self.reasoner: BaseReasoner = reasoner or Reasoner(model, self.tool_registry.get_tools())
+        self.executor: BaseExecutor = executor or Executor(self.tool_registry.get_tools(), notify_event=self._notify_observers)
+        self.max_iterations: int = max_iterations
+        self.max_history_tokens: int = max_history_tokens
+        self.history_manager: HistoryManager = history_manager or HistoryManager(
+            max_tokens=max_history_tokens,
+            system_prompt=system_prompt,
+            task_description=task_description
+        )
+        self.context_vars: Dict = {}
+        self._observers: List[Tuple[Callable, List[str]]] = []
+        self.error_handler = error_handler or (lambda e, step: False)  # Default: no retry
+
+    def add_observer(self, observer: Callable, event_types: List[str]) -> 'ReActAgent':
+        """Add an observer for specific event types."""
+        self._observers.append((observer, event_types))
+        return self
+
+    async def _notify_observers(self, event: object) -> None:
+        """Notify all subscribed observers of an event."""
+        await asyncio.gather(
+            *(observer(event) for observer, types in self._observers if event.event_type in types),
+            return_exceptions=True
+        )
+
+    async def generate_action(
+        self,
+        task: str,
+        history: List[Dict],
+        step: int,
+        max_iterations: int,
+        system_prompt: Optional[str] = None,
+        streaming: bool = False
+    ) -> str:
+        """
+        Generate an action using the Reasoner, passing available variables.
+
+        Args:
+            task (str): The task to address.
+            history (List[Dict]): Stored step history.
+            step (int): Current step number.
+            max_iterations (int): Maximum allowed steps.
+            system_prompt (Optional[str]): Override system prompt (optional).
+            streaming (bool): Whether to stream the response.
+
+        Returns:
+            str: Generated action in XML format.
+        """
+        history_str: str = self.history_manager.format_history(max_iterations)
+        available_vars: List[str] = list(self.context_vars.keys())
+        start: float = time.perf_counter()
+        response: str = await self.reasoner.generate_action(
+            task, 
+            history_str, 
+            step, 
+            max_iterations, 
+            system_prompt or self.history_manager.system_prompt,
+            self._notify_observers, 
+            streaming=streaming, 
+            available_vars=available_vars
+        )
+        thought, code = XMLResultHandler.parse_action_response(response)
+        gen_time: float = time.perf_counter() - start
+        await self._notify_observers(ThoughtGeneratedEvent(
+            event_type="ThoughtGenerated", step_number=step, thought=thought, generation_time=gen_time
+        ))
+        await self._notify_observers(ActionGeneratedEvent(
+            event_type="ActionGenerated", step_number=step, action_code=code, generation_time=gen_time
+        ))
+        if not response.endswith("</Code>"):
+            logger.warning(f"Response might be truncated at step {step}")
+        return response
+
+    async def execute_action(self, code: str, step: int, timeout: int = 300) -> str:
+        """
+        Execute an action using the Executor.
+
+        Args:
+            code (str): Code to execute.
+            step (int): Current step number.
+            timeout (int): Execution timeout in seconds (default: 300).
+
+        Returns:
+            str: Execution result in XML format.
+        """
+        start: float = time.perf_counter()
+        result_xml: str = await self.executor.execute_action(code, self.context_vars, step, timeout)
+        execution_time: float = time.perf_counter() - start
+        await self._notify_observers(ActionExecutedEvent(
+            event_type="ActionExecuted", step_number=step, result_xml=result_xml, execution_time=execution_time
+        ))
+        return result_xml
+
+    async def is_task_complete(self, task: str, history: List[Dict], result: str, success_criteria: Optional[str]) -> Tuple[bool, str]:
+        """
+        Check if the task is complete based on the result.
+
+        Args:
+            task (str): The task being solved.
+            history (List[Dict]): Step history.
+            result (str): Result of the latest action.
+            success_criteria (Optional[str]): Optional success criteria.
+
+        Returns:
+            Tuple[bool, str]: (is_complete, final_answer).
+        """
+        try:
+            root = etree.fromstring(result)
+            if root.findtext("Completed") == "true":
+                final_answer: str = root.findtext("FinalAnswer") or ""
+                verification: str = await litellm_completion(
+                    model=self.reasoner.model,
+                    messages=[{
+                        "role": "user",
+                        "content": f"Does '{final_answer}' solve '{task}' given history:\n{self.history_manager.format_history(self.max_iterations)}?"
+                    }],
+                    max_tokens=100,
+                    temperature=0.1,
+                    stream=False
+                )
+                if verification and "yes" in verification.lower():
+                    return True, final_answer
+                return True, final_answer
+        except etree.XMLSyntaxError:
+            pass
+
+        if success_criteria and (result_value := XMLResultHandler.extract_result_value(result)) and success_criteria in result_value:
+            return True, result_value
+        return False, ""
+
+    async def _run_step(self, task: str, step: int, max_iters: int, 
+                       system_prompt: Optional[str], streaming: bool) -> Dict:
+        """
+        Execute a single step of the ReAct loop with retry logic.
+
+        Args:
+            task (str): The task to address.
+            step (int): Current step number.
+            max_iters (int): Maximum allowed steps.
+            system_prompt (Optional[str]): System prompt override.
+            streaming (bool): Whether to stream responses.
+
+        Returns:
+            Dict: Step data (step_number, thought, action, result).
+        """
+        await self._notify_observers(StepStartedEvent(
+            event_type="StepStarted",
+            step_number=step,
+            system_prompt=self.history_manager.system_prompt,
+            task_description=self.history_manager.task_description
+        ))
+        for attempt in range(3):
+            try:
+                response: str = await self.generate_action(task, self.history_manager.store, step, max_iters, system_prompt, streaming)
+                thought, code = XMLResultHandler.parse_action_response(response)
+                result: str = await self.execute_action(code, step)
+                step_data = {"step_number": step, "thought": thought, "action": code, "result": result}
+                self.history_manager.add_step(step_data)
+                return step_data
+            except Exception as e:
+                if not self.error_handler(e, step) or attempt == 2:
+                    await self._notify_observers(ErrorOccurredEvent(
+                        event_type="ErrorOccurred", error_message=str(e), step_number=step
+                    ))
+                    raise
+                await asyncio.sleep(2 ** attempt)  # Exponential backoff
+
+    async def _finalize_step(self, task: str, step_data: Dict, 
+                            success_criteria: Optional[str]) -> Tuple[bool, Dict]:
+        """
+        Check completion and notify observers for a step.
+
+        Args:
+            task (str): The task being solved.
+            step_data (Dict): Current step data.
+            success_criteria (Optional[str]): Optional success criteria.
+
+        Returns:
+            Tuple[bool, Dict]: (is_complete, updated_step_data).
+        """
+        is_complete, final_answer = await self.is_task_complete(task, self.history_manager.store, step_data["result"], success_criteria)
+        if is_complete:
+            try:
+                root = etree.fromstring(step_data["result"])
+                if root.find("FinalAnswer") is None:
+                    final_answer_elem = etree.Element("FinalAnswer")
+                    final_answer_elem.text = etree.CDATA(final_answer)
+                    root.append(final_answer_elem)
+                step_data["result"] = etree.tostring(root, pretty_print=True, encoding="unicode")
+            except etree.XMLSyntaxError as e:
+                logger.error(f"Failed to parse result XML for appending FinalAnswer: {e}")
+                if "<FinalAnswer>" not in step_data["result"]:
+                    step_data["result"] += f"\n<FinalAnswer><![CDATA[\n{final_answer}\n]]></FinalAnswer>"
+        await self._notify_observers(StepCompletedEvent(
+            event_type="StepCompleted", step_number=step_data["step_number"], 
+            thought=step_data["thought"], action=step_data["action"], result=step_data["result"],
+            is_complete=is_complete, final_answer=final_answer if is_complete else None
+        ))
+        return is_complete, step_data
+
+    async def solve(
+        self,
+        task: str,
+        success_criteria: Optional[str] = None,
+        system_prompt: Optional[str] = None,
+        max_iterations: Optional[int] = None,
+        streaming: bool = False
+    ) -> List[Dict]:
+        """
+        Solve a task using the ReAct framework with persistent memory.
+
+        Args:
+            task (str): The task to solve.
+            success_criteria (Optional[str]): Criteria for success.
+            system_prompt (Optional[str]): System prompt override.
+            max_iterations (Optional[int]): Override for max steps.
+            streaming (bool): Whether to stream responses.
+
+        Returns:
+            List[Dict]: History of steps taken.
+        """
+        max_iters: int = max_iterations if max_iterations is not None else self.max_iterations
+        self.history_manager.store.clear()  # Reset history for new task
+        if system_prompt is not None:
+            self.history_manager.system_prompt = system_prompt
+        self.history_manager.task_description = task
+        await self._notify_observers(TaskStartedEvent(
+            event_type="TaskStarted",
+            task_description=task,
+            system_prompt=self.history_manager.system_prompt
+        ))
+
+        for step in range(1, max_iters + 1):
+            try:
+                step_data: Dict = await self._run_step(task, step, max_iters, system_prompt, streaming)
+                is_complete, step_data = await self._finalize_step(task, step_data, success_criteria)
+                if is_complete:
+                    await self._notify_observers(TaskCompletedEvent(
+                        event_type="TaskCompleted", final_answer=step_data["result"], reason="success"
+                    ))
+                    break
+            except Exception as e:
+                await self._notify_observers(ErrorOccurredEvent(
+                    event_type="ErrorOccurred", error_message=str(e), step_number=step
+                ))
+                break
+
+        if not any("<FinalAnswer>" in step["result"] for step in self.history_manager.store):
+            await self._notify_observers(TaskCompletedEvent(
+                event_type="TaskCompleted", final_answer=None,
+                reason="max_iterations_reached" if len(self.history_manager.store) == max_iters else "error"
+            ))
+        return self.history_manager.store

quantalogic/codeact/reasoner.py

@@ -0,0 +1,185 @@
+import ast
+import asyncio
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Dict, List, Optional
+
+from quantalogic.tools import Tool
+
+from .constants import MAX_GENERATE_PROGRAM_TOKENS
+from .events import PromptGeneratedEvent
+from .llm_util import litellm_completion
+from .templates import jinja_env
+from .xml_utils import XMLResultHandler, validate_xml
+
+
+async def generate_program(
+    task_description: str,
+    tools: List[Tool],
+    model: str,
+    max_tokens: int,
+    step: int,
+    notify_event: Callable,
+    streaming: bool = False
+) -> str:
+    """Generate a Python program using the specified model with streaming support and retries."""
+    tools_by_toolbox = {}
+    for tool in tools:
+        toolbox_name = tool.toolbox_name if tool.toolbox_name else "default"
+        if toolbox_name not in tools_by_toolbox:
+            tools_by_toolbox[toolbox_name] = []
+        tools_by_toolbox[toolbox_name].append(tool.to_docstring())
+
+    prompt = jinja_env.get_template("generate_program.j2").render(
+        task_description=task_description,
+        tools_by_toolbox=tools_by_toolbox
+    )
+    await notify_event(PromptGeneratedEvent(
+        event_type="PromptGenerated", step_number=step, prompt=prompt
+    ))
+
+    for attempt in range(3):
+        try:
+            response = await litellm_completion(
+                model=model,
+                messages=[
+                    {"role": "system", "content": "You are a Python code generator."},
+                    {"role": "user", "content": prompt}
+                ],
+                max_tokens=max_tokens,
+                temperature=0.3,
+                stream=streaming,
+                step=step,
+                notify_event=notify_event
+            )
+            code = response.strip()
+            return code[9:-3].strip() if code.startswith("```python") and code.endswith("```") else code
+        except Exception as e:
+            if attempt < 2:
+                await asyncio.sleep(2 ** attempt)
+            else:
+                raise Exception(f"Code generation failed with {model} after 3 attempts: {e}")
+
+
+class PromptStrategy(ABC):
+    """Abstract base class for prompt generation strategies."""
+    @abstractmethod
+    async def generate_prompt(self, task: str, history_str: str, step: int, max_iterations: int, available_vars: List[str]) -> str:
+        pass
+
+
+class DefaultPromptStrategy(PromptStrategy):
+    """Default strategy using Jinja2 templates."""
+    async def generate_prompt(self, task: str, history_str: str, step: int, max_iterations: int, available_vars: List[str]) -> str:
+        return jinja_env.get_template("generate_action.j2").render(
+            task=task,
+            history_str=history_str,
+            current_step=step,
+            max_iterations=max_iterations,
+            available_vars=available_vars
+        )
+
+
+class BaseReasoner(ABC):
+    """Abstract base class for reasoning components."""
+    @abstractmethod
+    async def generate_action(
+        self,
+        task: str,
+        history_str: str,
+        step: int,
+        max_iterations: int,
+        system_prompt: Optional[str],
+        notify_event: Callable,
+        streaming: bool,
+        available_vars: List[str]
+    ) -> str:
+        pass
+
+
+class Reasoner(BaseReasoner):
+    """Handles action generation using the language model."""
+    def __init__(self, model: str, tools: List[Tool], config: Optional[Dict[str, Any]] = None, prompt_strategy: Optional[PromptStrategy] = None):
+        self.model = model
+        self.tools = tools
+        self.config = config or {}
+        self.prompt_strategy = prompt_strategy or DefaultPromptStrategy()
+
+    async def generate_action(
+        self,
+        task: str,
+        history_str: str,
+        step: int,
+        max_iterations: int,
+        system_prompt: Optional[str] = None,
+        notify_event: Callable = None,
+        streaming: bool = False,
+        available_vars: List[str] = None
+    ) -> str:
+        """Generate an action based on task and history with streaming support."""
+        try:
+            # Prepare type hints for available variables based on tool return types
+            available_var_types = {}
+            for var_name in available_vars or []:
+                # Infer type from tool documentation if possible (simplified heuristic)
+                if "plan" in var_name.lower():
+                    available_var_types[var_name] = "PlanResult (has attributes: task_id, task_description, subtasks)"
+                else:
+                    available_var_types[var_name] = "Unknown (check history or assume str)"
+
+            task_prompt = await self.prompt_strategy.generate_prompt(
+                task if not system_prompt else f"{system_prompt}\nTask: {task}",
+                history_str,
+                step,
+                max_iterations,
+                available_vars or []  # Default to empty list if None
+            )
+            await notify_event(PromptGeneratedEvent(
+                event_type="PromptGenerated", step_number=step, prompt=task_prompt
+            ))
+            program = await generate_program(
+                task_prompt + f"\n\nVariable Types in context_vars:\n{available_var_types}",
+                self.tools, 
+                self.model, 
+                self.config.get("max_tokens", MAX_GENERATE_PROGRAM_TOKENS), 
+                step, 
+                notify_event, 
+                streaming=streaming
+            )
+            program = self._clean_code(program)
+            response = jinja_env.get_template("response_format.j2").render(
+                task=task,
+                included_stepsincluded_stepshistory_str=history_str,
+                program=program,
+                current_step=step,
+                max_iterations=max_iterations
+            )
+            if not validate_xml(response):
+                raise ValueError("Invalid XML generated")
+            return response
+        except Exception as e:
+            return XMLResultHandler.format_error_result(str(e))
+
+    def _clean_code(self, code: str) -> str:
+        lines = code.splitlines()
+        in_code_block = False
+        code_lines = []
+        
+        for line in lines:
+            if line.startswith('```python'):
+                in_code_block = True
+                code_part = line[len('```python'):].strip()
+                if code_part:
+                    code_lines.append(code_part)
+                continue
+            if in_code_block:
+                if line.startswith('```'):
+                    break
+                code_lines.append(line)
+        
+        final_code = '\n'.join(code_lines) if in_code_block else code
+        
+        try:
+            ast.parse(final_code)
+            return final_code
+        except SyntaxError as e:
+            raise ValueError(f'Invalid Python code: {e}') from e

quantalogic/codeact/templates/toolbox/README.md.j2

@@ -0,0 +1,10 @@
+# {{ name }}
+
+A custom toolbox for Quantalogic.
+
+## Installation
+
+```bash
+poetry install
+```
+

quantalogic/codeact/templates/toolbox/pyproject.toml.j2

@@ -0,0 +1,16 @@
+[tool.poetry]
+name = "{{ name }}"
+version = "0.1.0"
+description = "A custom toolbox for Quantalogic"
+authors = ["Your Name <you@example.com>"]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+quantalogic = ">0.60.0"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.plugins."quantalogic.tools"]
+"{{ name }}" = "{{ package_name }}.tools"

quantalogic/codeact/templates/toolbox/tools.py.j2

@@ -0,0 +1,6 @@
+from quantalogic.tools import create_tool
+
+@create_tool
+async def echo_tool(message: str) -> str:
+    """An example tool that echoes the input."""
+    return f"Echo: {message}"

quantalogic/codeact/templates.py

@@ -0,0 +1,7 @@
+from jinja2 import Environment, FileSystemLoader
+
+from .constants import TEMPLATE_DIR
+
+# Centralized Jinja2 environment for template rendering
+# Note: This is the default environment; custom environments can be passed to Agent
+jinja_env = Environment(loader=FileSystemLoader(TEMPLATE_DIR), trim_blocks=True, lstrip_blocks=True)