quantalogic 0.60.0__py3-none-any.whl → 0.61.0__py3-none-any.whl

quantalogic/codeact/cli.py

@@ -0,0 +1,232 @@
+import asyncio
+from typing import Callable, List, Optional, Union
+
+import typer
+from loguru import logger
+
+from quantalogic.tools import create_tool
+
+from .agent import Agent  # Import only Agent from agent.py
+from .constants import DEFAULT_MODEL, LOG_FILE
+from .events import (  # Import events from events.py
+    ActionExecutedEvent,
+    ActionGeneratedEvent,
+    ErrorOccurredEvent,
+    StepCompletedEvent,
+    StepStartedEvent,
+    StreamTokenEvent,
+    TaskCompletedEvent,
+    TaskStartedEvent,
+    ThoughtGeneratedEvent,
+    ToolExecutionCompletedEvent,
+    ToolExecutionErrorEvent,
+    ToolExecutionStartedEvent,
+)
+from .tools_manager import Tool, get_default_tools
+from .utils import XMLResultHandler
+
+app = typer.Typer(no_args_is_help=True)
+
+class ProgressMonitor:
+    """Handles progress monitoring for agent events."""
+    def __init__(self):
+        self._token_buffer = ""  # Buffer to accumulate streaming tokens
+
+    async def on_task_started(self, event: TaskStartedEvent):
+        typer.echo(typer.style(f"Task Started: {event.task_description}", fg=typer.colors.GREEN, bold=True))
+        typer.echo(f"Timestamp: {event.timestamp.strftime('%Y-%m-%d %H:%M:%S')}")
+        typer.echo("-" * 50)
+
+    async def on_thought_generated(self, event: ThoughtGeneratedEvent):
+        typer.echo(typer.style(f"Step {event.step_number} - Thought Generated:", fg=typer.colors.CYAN, bold=True))
+        typer.echo(f"Thought: {event.thought}")
+        typer.echo(f"Generation Time: {event.generation_time:.2f} seconds")
+        typer.echo("-" * 50)
+
+    async def on_action_generated(self, event: ActionGeneratedEvent):
+        typer.echo(typer.style(f"Step {event.step_number} - Action Generated:", fg=typer.colors.BLUE, bold=True))
+        typer.echo(f"Action Code:\n{event.action_code}")
+        typer.echo(f"Generation Time: {event.generation_time:.2f} seconds")
+        typer.echo("-" * 50)
+
+    async def on_action_executed(self, event: ActionExecutedEvent):
+        summary = XMLResultHandler.format_result_summary(event.result_xml)
+        typer.echo(typer.style(f"Step {event.step_number} - Action Executed:", fg=typer.colors.MAGENTA, bold=True))
+        typer.echo(f"Result Summary:\n{summary}")
+        typer.echo(f"Execution Time: {event.execution_time:.2f} seconds")
+        typer.echo("-" * 50)
+
+    async def on_step_completed(self, event: StepCompletedEvent):
+        typer.echo(typer.style(f"Step {event.step_number} - Completed", fg=typer.colors.YELLOW, bold=True))
+        typer.echo("-" * 50)
+
+    async def on_error_occurred(self, event: ErrorOccurredEvent):
+        typer.echo(typer.style(f"Error Occurred{' at Step ' + str(event.step_number) if event.step_number else ''}:", fg=typer.colors.RED, bold=True))
+        typer.echo(f"Message: {event.error_message}")
+        typer.echo(f"Timestamp: {event.timestamp.strftime('%Y-%m-%d %H:%M:%S')}")
+        typer.echo("-" * 50)
+
+    async def on_task_completed(self, event: TaskCompletedEvent):
+        if event.final_answer:
+            typer.echo(typer.style("Task Completed Successfully:", fg=typer.colors.GREEN, bold=True))
+            typer.echo(f"Final Answer:\n{event.final_answer}")
+        else:
+            typer.echo(typer.style("Task Did Not Complete Successfully:", fg=typer.colors.RED, bold=True))
+            typer.echo(f"Reason: {event.reason}")
+        typer.echo(f"Timestamp: {event.timestamp.strftime('%Y-%m-%d %H:%M:%S')}")
+        typer.echo("-" * 50)
+
+    async def on_step_started(self, event: StepStartedEvent):
+        typer.echo(typer.style(f"Starting Step {event.step_number}", fg=typer.colors.YELLOW, bold=True))
+        typer.echo("-" * 50)
+
+    async def on_tool_execution_started(self, event: ToolExecutionStartedEvent):
+        typer.echo(typer.style(f"Tool {event.tool_name} started execution at step {event.step_number}", fg=typer.colors.CYAN))
+        typer.echo(f"Parameters: {event.parameters_summary}")
+
+    async def on_tool_execution_completed(self, event: ToolExecutionCompletedEvent):
+        typer.echo(typer.style(f"Tool {event.tool_name} completed execution at step {event.step_number}", fg=typer.colors.GREEN))
+        typer.echo(f"Result: {event.result_summary}")
+
+    async def on_tool_execution_error(self, event: ToolExecutionErrorEvent):
+        typer.echo(typer.style(f"Tool {event.tool_name} encountered an error at step {event.step_number}", fg=typer.colors.RED))
+        typer.echo(f"Error: {event.error}")
+
+    async def on_stream_token(self, event: StreamTokenEvent):
+        """Handle streaming token events for real-time output with buffering."""
+        self._token_buffer += event.token
+        # Check for natural breakpoints to flush the buffer
+        if "\n" in event.token or event.token.strip() in [".", ";", ":", "{", "}", "]", ")"]:
+            # Print the accumulated buffer with proper formatting
+            lines = self._token_buffer.split("\n")
+            for line in lines[:-1]:  # Print all complete lines
+                if line.strip():
+                    typer.echo(f"{line}", nl=False)
+                    typer.echo("")  # Add newline after each complete line
+            # Keep the last incomplete line in the buffer
+            self._token_buffer = lines[-1]
+        # Flush buffer if it gets too long (e.g., > 100 chars)
+        if len(self._token_buffer) > 100:
+            typer.echo(f"{self._token_buffer}", nl=False)
+            self._token_buffer = ""
+
+    async def flush_buffer(self):
+        """Flush any remaining tokens in the buffer."""
+        if self._token_buffer.strip():
+            typer.echo(f"{self._token_buffer}")
+            self._token_buffer = ""
+
+    async def __call__(self, event):
+        """Dispatch events to their respective handlers."""
+        if isinstance(event, TaskStartedEvent):
+            await self.on_task_started(event)
+        elif isinstance(event, ThoughtGeneratedEvent):
+            await self.on_thought_generated(event)
+        elif isinstance(event, ActionGeneratedEvent):
+            await self.on_action_generated(event)
+            await self.flush_buffer()  # Flush after action is fully generated
+        elif isinstance(event, ActionExecutedEvent):
+            await self.on_action_executed(event)
+        elif isinstance(event, StepCompletedEvent):
+            await self.on_step_completed(event)
+        elif isinstance(event, ErrorOccurredEvent):
+            await self.on_error_occurred(event)
+        elif isinstance(event, TaskCompletedEvent):
+            await self.on_task_completed(event)
+            await self.flush_buffer()  # Flush at task completion
+        elif isinstance(event, StepStartedEvent):
+            await self.on_step_started(event)
+        elif isinstance(event, ToolExecutionStartedEvent):
+            await self.on_tool_execution_started(event)
+        elif isinstance(event, ToolExecutionCompletedEvent):
+            await self.on_tool_execution_completed(event)
+        elif isinstance(event, ToolExecutionErrorEvent):
+            await self.on_tool_execution_error(event)
+        elif isinstance(event, StreamTokenEvent):
+            await self.on_stream_token(event)
+
+async def run_react_agent(
+    task: str,
+    model: str,
+    max_iterations: int,
+    success_criteria: Optional[str] = None,
+    tools: Optional[List[Union[Tool, Callable]]] = None,
+    personality: Optional[str] = None,
+    backstory: Optional[str] = None,
+    sop: Optional[str] = None,
+    debug: bool = False,
+    streaming: bool = False  # New parameter for enabling streaming
+) -> None:
+    """Run the Agent with detailed event monitoring."""
+    # Configure logging: disable stderr output unless debug is enabled
+    logger.remove()  # Remove default handler
+    if debug:
+        logger.add(typer.stderr, level="INFO")
+    logger.add(LOG_FILE, level="INFO")  # Always log to file
+
+    tools = tools if tools is not None else get_default_tools(model)
+    
+    processed_tools = []
+    for tool in tools:
+        if isinstance(tool, Tool):
+            processed_tools.append(tool)
+        elif callable(tool):
+            processed_tools.append(create_tool(tool))
+        else:
+            logger.warning(f"Invalid tool type: {type(tool)}. Skipping.")
+            typer.echo(typer.style(f"Warning: Invalid tool type {type(tool)} skipped.", fg=typer.colors.YELLOW))
+
+    agent = Agent(
+        model=model,
+        tools=processed_tools,
+        max_iterations=max_iterations,
+        personality=personality,
+        backstory=backstory,
+        sop=sop
+    )
+    
+    progress_monitor = ProgressMonitor()
+    # Use solve with tools enabled for multi-step tasks
+    solve_agent = agent  # Store reference to add observer
+    solve_agent.add_observer(progress_monitor, [
+        "TaskStarted", "ThoughtGenerated", "ActionGenerated", "ActionExecuted",
+        "StepCompleted", "ErrorOccurred", "TaskCompleted", "StepStarted",
+        "ToolExecutionStarted", "ToolExecutionCompleted", "ToolExecutionError",
+        "StreamToken"  # Added to observe streaming tokens
+    ])
+    
+    typer.echo(typer.style(f"Starting task: {task}", fg=typer.colors.GREEN, bold=True))
+    # Pass the streaming flag to the solve method
+    history = await agent.solve(task, success_criteria, streaming=streaming)
+
+@app.command()
+def react(
+    task: str = typer.Argument(..., help="The task to solve"),
+    model: str = typer.Option(DEFAULT_MODEL, help="The litellm model to use"),
+    max_iterations: int = typer.Option(5, help="Maximum reasoning steps"),
+    success_criteria: Optional[str] = typer.Option(None, help="Optional criteria to determine task completion"),
+    personality: Optional[str] = typer.Option(None, help="Agent personality (e.g., 'witty')"),
+    backstory: Optional[str] = typer.Option(None, help="Agent backstory"),
+    sop: Optional[str] = typer.Option(None, help="Standard operating procedure"),
+    debug: bool = typer.Option(False, help="Enable debug logging to stderr"),
+    streaming: bool = typer.Option(False, help="Enable streaming output for real-time token generation")
+) -> None:
+    """CLI command to run the Agent with detailed event monitoring."""
+    try:
+        asyncio.run(run_react_agent(
+            task, model, max_iterations, success_criteria,
+            personality=personality, backstory=backstory, sop=sop, debug=debug,
+            streaming=streaming  # Pass the streaming flag
+        ))
+    except Exception as e:
+        logger.error(f"Agent failed: {e}")
+        typer.echo(typer.style(f"Error: {e}", fg=typer.colors.RED))
+        raise typer.Exit(code=1)
+
+if __name__ == "__main__":
+    app()
+
+
+# Example how to use the CLI
+# python -m quantalogic.codeact.cli "Write a poem, then evaluate the quality, in French, afficher le poem et la critique. Tout doit être Français. Si le poême n'est pas de bonne qualité, ré-écrit le poême"    --streaming
+

quantalogic/codeact/constants.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+BASE_DIR = Path(__file__).parent
+TEMPLATE_DIR = BASE_DIR / "prompts"
+LOG_FILE = "react_agent.log"
+DEFAULT_MODEL = "gemini/gemini-2.0-flash"
+MAX_TOKENS = 4000
+MAX_GENERATE_PROGRAM_TOKENS = 1000
+MAX_HISTORY_TOKENS = 2000

quantalogic/codeact/events.py

@@ -0,0 +1,78 @@
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class Event(BaseModel):
+    event_type: str
+    timestamp: datetime = Field(default_factory=datetime.now)
+
+
+class TaskStartedEvent(Event):
+    task_description: str
+
+
+class ThoughtGeneratedEvent(Event):
+    step_number: int
+    thought: str
+    generation_time: float
+
+
+class ActionGeneratedEvent(Event):
+    step_number: int
+    action_code: str
+    generation_time: float
+
+
+class ActionExecutedEvent(Event):
+    step_number: int
+    result_xml: str
+    execution_time: float
+
+
+class StepCompletedEvent(Event):
+    step_number: int
+    thought: str
+    action: str
+    result: str
+    is_complete: bool
+    final_answer: str | None = None
+
+
+class ErrorOccurredEvent(Event):
+    error_message: str
+    step_number: int | None = None
+
+
+class TaskCompletedEvent(Event):
+    final_answer: str | None
+    reason: str
+
+
+class StepStartedEvent(Event):
+    step_number: int
+
+
+class ToolExecutionStartedEvent(Event):
+    step_number: int
+    tool_name: str
+    parameters_summary: dict  # Summary of tool parameters (e.g., {"param1": "value1"})
+
+
+class ToolExecutionCompletedEvent(Event):
+    step_number: int
+    tool_name: str
+    result_summary: str  # Summary of the execution result
+
+
+class ToolExecutionErrorEvent(Event):
+    step_number: int
+    tool_name: str
+    error: str  # Error message if execution fails
+
+
+# In quantalogic/codeact/events.py
+class StreamTokenEvent(Event):
+    token: str
+    step_number: Optional[int] = None

quantalogic/codeact/llm_util.py

@@ -0,0 +1,76 @@
+from typing import Callable, List, Optional
+
+import litellm
+
+
+async def litellm_completion(
+    model: str,
+    messages: List[dict],
+    max_tokens: int,
+    temperature: float,
+    stream: bool = False,
+    step: Optional[int] = None,
+    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
+
+    if stream:
+        if notify_event is None:
+            raise ValueError("notify_event callback is required when streaming is enabled.")
+        
+        full_response = ""
+        try:
+            response = await litellm.acompletion(
+                model=model,
+                messages=messages,
+                max_tokens=max_tokens,
+                temperature=temperature,
+                stream=True,
+                **kwargs
+            )
+            async for chunk in response:
+                if chunk.choices[0].delta.content:
+                    token = chunk.choices[0].delta.content
+                    full_response += token
+                    await notify_event(StreamTokenEvent(
+                        event_type="StreamToken",
+                        token=token,
+                        step_number=step
+                    ))
+            return full_response
+        except Exception as e:
+            raise Exception(f"Streaming completion failed: {e}")
+    else:
+        try:
+            response = await litellm.acompletion(
+                model=model,
+                messages=messages,
+                max_tokens=max_tokens,
+                temperature=temperature,
+                stream=False,
+                **kwargs
+            )
+            return response.choices[0].message.content
+        except Exception as e:
+            raise Exception(f"Completion failed: {e}")

quantalogic/codeact/prompts/error_format.j2

@@ -0,0 +1,11 @@
+<Action>
+  <Thought>Failed to generate a valid action due to: {{ error }}</Thought>
+  <Error>
+    <Message>{{ error }}</Message>
+  </Error>
+  <Code><![CDATA[
+import asyncio
+async def main():
+    print("Error: Action generation failed")
+  ]]></Code>
+</Action>

quantalogic/codeact/prompts/generate_action.j2

@@ -0,0 +1,26 @@
+Solve the following task: '{{ task }}'
+This is step {{ current_step }} out of {{ max_iterations }} allowed steps.
+Previous steps:
+{{ history_str }}
+
+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'.
+
+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)

quantalogic/codeact/prompts/generate_program.j2

@@ -0,0 +1,39 @@
+You are a Python code generator. Your task is to create a Python program that solves the following task:
+
+"{{ task_description }}"
+
+You have access to the following pre-defined async tool functions, as defined with their signatures and descriptions:
+
+{{ tool_docstrings }}
+
+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.
+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.
+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.
+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))
+11. Be careful to avoid programs that cannot terminate.
+
+
+Example task: "Calculate running total by adding 5 to previous sum stored in context"
+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}"

quantalogic/codeact/prompts/response_format.j2

@@ -0,0 +1,11 @@
+<Action>
+  <Thought>Generated a Python program to take the next step toward solving: {{ task }} Based on history: {{ history_str }}</Thought>
+  <Code><![CDATA[
+{{ program }}
+  ]]></Code>
+  <Metadata>
+    <StepNumber>{{ current_step }}</StepNumber>
+    <MaxIterations>{{ max_iterations }}</MaxIterations>
+    <Task>{{ task }}</Task>
+  </Metadata>
+</Action>

quantalogic/codeact/tools_manager.py

@@ -0,0 +1,135 @@
+import asyncio
+from contextlib import AsyncExitStack
+from typing import List
+
+import litellm
+from loguru import logger
+
+from quantalogic.tools import (
+    EditWholeContentTool,
+    ExecuteBashCommandTool,
+    GrepAppTool,
+    InputQuestionTool,
+    JinjaTool,
+    ListDirectoryTool,
+    ReadFileBlockTool,
+    ReadFileTool,
+    ReadHTMLTool,
+    ReplaceInFileTool,
+    RipgrepTool,
+    SearchDefinitionNamesTool,
+    TaskCompleteTool,
+    Tool,
+    ToolArgument,
+    WriteFileTool,
+    create_tool,
+)
+
+from .utils import log_async_tool, log_tool_method
+
+
+@create_tool
+@log_async_tool("Adding")
+async def add_tool(a: int, b: int) -> str:
+    """Adds two numbers and returns the sum as a string."""
+    return str(a + b)
+
+@create_tool
+@log_async_tool("Multiplying")
+async def multiply_tool(x: int, y: int) -> str:
+    """Multiplies two numbers and returns the product as a string."""
+    return str(x * y)
+
+@create_tool
+@log_async_tool("Concatenating")
+async def concat_tool(s1: str, s2: str) -> str:
+    """Concatenates two strings and returns the result."""
+    return s1 + s2
+
+class AgentTool(Tool):
+    """Tool for generating text using a language model."""
+    def __init__(self, model: str = "gemini/gemini-2.0-flash"):
+        super().__init__(
+            name="agent_tool",
+            description="Generates text using a language model.",
+            arguments=[
+                ToolArgument(name="system_prompt", arg_type="string", 
+                           description="System prompt to guide the model", required=True),
+                ToolArgument(name="prompt", arg_type="string", 
+                           description="User prompt to generate a response", required=True),
+                ToolArgument(name="temperature", arg_type="float", 
+                           description="Temperature for generation (0 to 1)", required=True)
+            ],
+            return_type="string"
+        )
+        self.model = model
+
+    @log_tool_method
+    async def async_execute(self, **kwargs) -> str:
+        system_prompt = kwargs["system_prompt"]
+        prompt = kwargs["prompt"]
+        temperature = float(kwargs["temperature"])
+
+        if not 0 <= temperature <= 1:
+            raise ValueError("Temperature must be between 0 and 1")
+
+        logger.info(f"Generating with {self.model}, temp={temperature}")
+        async with AsyncExitStack() as stack:
+            await stack.enter_async_context(asyncio.timeout(30))
+            response = await litellm.acompletion(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": prompt}
+                ],
+                temperature=temperature,
+                max_tokens=1000
+            )
+            return response.choices[0].message.content.strip()
+
+class RetrieveStepTool(Tool):
+    """Tool to retrieve information from a specific previous step."""
+    def __init__(self, history_store: List[dict]):
+        super().__init__(
+            name="retrieve_step",
+            description="Retrieve the thought, action, and result from a specific step.",
+            arguments=[
+                ToolArgument(name="step_number", arg_type="int", 
+                            description="The step number to retrieve (1-based)", required=True)
+            ],
+            return_type="string"
+        )
+        self.history_store = history_store
+
+    @log_tool_method
+    async def async_execute(self, **kwargs) -> str:
+        step_number = kwargs["step_number"]
+        if step_number < 1 or step_number > len(self.history_store):
+            return f"Error: Step {step_number} does not exist."
+        step = self.history_store[step_number - 1]
+        return (
+            f"Step {step_number}:\n"
+            f"Thought: {step['thought']}\n"
+            f"Action: {step['action']}\n"
+            f"Result: {step['result']}"
+        )
+
+def get_default_tools(model: str) -> List[Tool]:
+    """Return list of default tools."""
+    return [
+        #EditWholeContentTool(), 
+        #ExecuteBashCommandTool(), 
+        GrepAppTool(),
+        InputQuestionTool(), 
+        JinjaTool(), 
+        ListDirectoryTool(),
+        ReadFileBlockTool(), 
+        ReadFileTool(), 
+        ReadHTMLTool(),
+        #ReplaceInFileTool(), 
+        # RipgrepTool(), 
+        # SearchDefinitionNamesTool(),
+        #TaskCompleteTool(), 
+        WriteFileTool(), 
+        AgentTool(model=model),
+    ]