tsugite-cli 0.3.3__py3-none-any.whl

tsugite/core/executor.py

@@ -0,0 +1,300 @@
+"""Code execution backends for agents.
+
+Provides local execution using Python's exec().
+WARNING: Not secure! Only use for development.
+
+Maintains state (variables persist between runs).
+"""
+
+import ast
+import io
+import pprint
+import sys
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+PPRINT_WIDTH = 100
+
+
+@dataclass
+class ExecutionResult:
+    """Result from code execution."""
+
+    output: str
+    error: Optional[str]
+    stdout: str
+    stderr: str
+    final_answer: Optional[Any] = None
+    tools_called: List[str] = field(default_factory=list)
+
+
+class CodeExecutor(ABC):
+    """Abstract interface for code execution.
+
+    Defines the contract for code executors used by agents.
+    """
+
+    @abstractmethod
+    async def execute(self, code: str) -> ExecutionResult:
+        """Execute Python code and return results.
+
+        Args:
+            code: Python code to execute
+
+        Returns:
+            ExecutionResult with output, errors, etc.
+        """
+        pass
+
+    @abstractmethod
+    async def send_variables(self, variables: Dict[str, Any]):
+        """Inject variables into execution namespace.
+
+        This is used for multi-step agents to pass results between steps.
+
+        Args:
+            variables: Dict of {name: value} to make available in code
+        """
+        pass
+
+
+class LocalExecutor(CodeExecutor):
+    """Simple local code executor using Python's exec().
+
+    WARNING: This is NOT secure! Only use for development.
+
+    Uses Python's built-in exec() function. State persists between
+    runs by maintaining a shared namespace dict.
+
+    Example:
+        executor = LocalExecutor()
+
+        # First run
+        result = await executor.execute("x = 5")
+
+        # Second run - x still exists!
+        result = await executor.execute("print(x + 3)")  # Prints: 8
+    """
+
+    def __init__(self):
+        """Initialize executor with empty namespace."""
+        self.namespace = {}
+        self._final_answer_value = None
+        self._tools_called = []
+
+        # Inject final_answer function into namespace
+        def final_answer(value):
+            self._final_answer_value = value
+            # Don't print here - the UI handler will display it properly via FINAL_ANSWER event
+
+        self.namespace["final_answer"] = final_answer
+
+    def _split_code_for_last_expr(self, code: str) -> tuple[str, Optional[str]]:
+        """Split code into setup and last expression if applicable.
+
+        If the last statement is an expression, return (setup, last_expr).
+        Otherwise, return (code, None).
+
+        Args:
+            code: Python code to analyze
+
+        Returns:
+            Tuple of (setup_code, last_expression_or_none)
+        """
+        try:
+            tree = ast.parse(code)
+            if not tree.body:
+                return (code, None)
+
+            # Check if last statement is an expression
+            last_node = tree.body[-1]
+            if not isinstance(last_node, ast.Expr):
+                return (code, None)
+
+            # Split: everything except last statement vs last statement
+            if len(tree.body) == 1:
+                # Only one statement and it's an expression
+                setup_code = ""
+                last_expr = ast.unparse(last_node.value)  # Unparse the expression itself
+            else:
+                # Multiple statements - use ast.unparse to reconstruct
+                setup_tree = ast.Module(body=tree.body[:-1], type_ignores=[])
+                setup_code = ast.unparse(setup_tree)
+                last_expr = ast.unparse(last_node.value)
+
+            return (setup_code, last_expr)
+
+        except SyntaxError:
+            # Code has syntax errors, let exec handle it normally
+            return (code, None)
+
+    def _format_value(self, value: Any) -> str:
+        """Format a value for display.
+
+        Uses pprint for complex objects, repr for simple ones.
+
+        Args:
+            value: Value to format
+
+        Returns:
+            Formatted string representation
+        """
+        # For dicts and lists, use pprint for nice formatting
+        if isinstance(value, (dict, list, tuple, set)):
+            return pprint.pformat(value, width=PPRINT_WIDTH, compact=False)
+        else:
+            return repr(value)
+
+    def _check_code_safety(self, code: str) -> Optional[str]:
+        """Check code for anti-patterns before execution.
+
+        Detects common mistakes where LLMs use built-in Python functions
+        instead of the provided tools.
+
+        Args:
+            code: Python code to check
+
+        Returns:
+            Error message string if violations found, None if code is safe
+        """
+        import re
+
+        # Check for file operations using open() instead of read_file/write_file
+        # Match: word boundary before 'open', then whitespace, then '('
+        # This avoids false positives like 'reopen(' or 'is_open()'
+        # Pattern explanation:
+        #   \b       - word boundary (not preceded by alphanumeric or _)
+        #   open     - literal 'open'
+        #   \s*      - optional whitespace
+        #   \(       - opening parenthesis
+        if re.search(r"\bopen\s*\(", code):
+            # Quick check to avoid false positives in strings/comments
+            # Remove strings and comments before checking
+            # This is a simple heuristic - not perfect but good enough
+            code_without_strings = re.sub(r'["\'].*?["\']', "", code)  # Remove string contents
+            code_without_comments = re.sub(r"#.*$", "", code_without_strings, flags=re.MULTILINE)  # Remove comments
+
+            # Check again after removing strings/comments
+            if re.search(r"\bopen\s*\(", code_without_comments):
+                return """Code Safety Check Failed: Detected use of 'open()' for file operations.
+
+Please use the provided tools instead:
+  - read_file(path) - to read file contents
+  - write_file(path, content) - to write to files
+
+Example:
+  # Instead of:
+  with open('file.txt') as f:
+      content = f.read()
+
+  # Use:
+  content = read_file('file.txt')
+
+  # Instead of:
+  with open('output.txt', 'w') as f:
+      f.write(data)
+
+  # Use:
+  write_file('output.txt', data)"""
+
+        # Code passed all safety checks
+        return None
+
+    async def execute(self, code: str) -> ExecutionResult:
+        """Execute code using exec().
+
+        Automatically displays the value of the last expression (REPL-like behavior).
+
+        Args:
+            code: Python code to execute
+
+        Returns:
+            ExecutionResult with output, error, stdout, stderr, final_answer, and tools_called
+        """
+        # Reset final answer and tool tracking
+        self._final_answer_value = None
+        self._tools_called = []
+
+        # Check code safety before execution
+        safety_error = self._check_code_safety(code)
+        if safety_error:
+            return ExecutionResult(
+                output="",
+                error=safety_error,
+                stdout="",
+                stderr=safety_error,
+                final_answer=None,
+                tools_called=[],
+            )
+
+        # Capture stdout/stderr
+        stdout_capture = io.StringIO()
+        stderr_capture = io.StringIO()
+
+        old_stdout = sys.stdout
+        old_stderr = sys.stderr
+
+        try:
+            # Redirect output
+            sys.stdout = stdout_capture
+            sys.stderr = stderr_capture
+
+            # Check if we should handle the last expression specially
+            setup_code, last_expr = self._split_code_for_last_expr(code)
+
+            if last_expr:
+                # Execute setup code first (if any)
+                if setup_code.strip():
+                    exec(setup_code, self.namespace)
+
+                # Evaluate the last expression and capture its value
+                result = eval(last_expr, self.namespace)
+
+                # Display the result if it's not None
+                if result is not None:
+                    formatted = self._format_value(result)
+                    print(formatted)
+            else:
+                # No special handling needed, execute normally
+                exec(code, self.namespace)
+
+            # Get output
+            output = stdout_capture.getvalue()
+            stderr_output = stderr_capture.getvalue()
+
+            return ExecutionResult(
+                output=output,
+                error=None,
+                stdout=output,
+                stderr=stderr_output,
+                final_answer=self._final_answer_value,
+                tools_called=self._tools_called.copy(),
+            )
+
+        except Exception as e:
+            # Code execution failed
+            error_msg = f"{type(e).__name__}: {str(e)}"
+            return ExecutionResult(
+                output=stdout_capture.getvalue(),
+                error=error_msg,
+                stdout=stdout_capture.getvalue(),
+                stderr=stderr_capture.getvalue() + "\n" + error_msg,
+                final_answer=None,
+                tools_called=self._tools_called.copy(),
+            )
+
+        finally:
+            # Restore stdout/stderr
+            sys.stdout = old_stdout
+            sys.stderr = old_stderr
+
+    async def send_variables(self, variables: Dict[str, Any]):
+        """Inject variables into namespace.
+
+        Simply updates the shared namespace dict.
+
+        Args:
+            variables: Dict of {name: value} to inject
+        """
+        self.namespace.update(variables)

tsugite/core/memory.py

@@ -0,0 +1,67 @@
+"""Agent memory system.
+
+Tracks execution history for building conversation context.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, List, Optional
+
+
+@dataclass
+class StepResult:
+    """Result from a single agent step."""
+
+    step_number: int
+    thought: str
+    code: str
+    output: str
+    error: Optional[str] = None
+    tools_called: List[str] = field(default_factory=list)
+
+
+@dataclass
+class AgentMemory:
+    """Memory of agent execution.
+
+    Stores:
+    - The task
+    - All steps (thought/code/observation)
+    - Reasoning content (for o1/o3/Claude)
+    - Final answer
+    """
+
+    task: str = ""
+    steps: List[StepResult] = field(default_factory=list)
+    reasoning_history: List[str] = field(default_factory=list)
+    final_answer: Optional[Any] = None
+
+    def add_task(self, task: str) -> None:
+        """Set the task."""
+        self.task = task
+
+    def add_step(
+        self,
+        thought: str,
+        code: str,
+        output: str,
+        error: Optional[str] = None,
+        tools_called: Optional[List[str]] = None,
+    ) -> None:
+        """Add a step to history."""
+        step = StepResult(
+            step_number=len(self.steps) + 1,
+            thought=thought,
+            code=code,
+            output=output,
+            error=error,
+            tools_called=tools_called or [],
+        )
+        self.steps.append(step)
+
+    def add_reasoning(self, reasoning: str) -> None:
+        """Add reasoning content (from o1/o3/Claude thinking)."""
+        self.reasoning_history.append(reasoning)
+
+    def add_final_answer(self, answer: Any) -> None:
+        """Set final answer."""
+        self.final_answer = answer

tsugite/core/tools.py

@@ -0,0 +1,271 @@
+"""Tool system for agents.
+
+Provides a simple Tool class and converters to wrap:
+- Existing tsugite tools
+- MCP tools
+- Custom functions
+"""
+
+import asyncio
+import inspect
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Optional
+
+
+@dataclass
+class Tool:
+    """A tool that agents can use.
+
+    Tools are Python functions with:
+    - name: Identifier
+    - description: What it does
+    - parameters: JSON schema of arguments
+    - function: The actual callable
+
+    Example:
+        def add(a: int, b: int) -> int:
+            '''Add two numbers'''
+            return a + b
+
+        tool = Tool(
+            name="add",
+            description="Add two numbers",
+            parameters={
+                "type": "object",
+                "properties": {
+                    "a": {"type": "integer"},
+                    "b": {"type": "integer"}
+                },
+                "required": ["a", "b"]
+            },
+            function=add
+        )
+    """
+
+    name: str
+    description: str
+    parameters: Dict[str, Any]
+    function: Callable
+
+    def to_code_prompt(self) -> str:
+        """Format tool as Python function for system prompt.
+
+        The agent sees tools as Python functions it can call.
+
+        Returns:
+            str: Python function signature with docstring
+
+        Example output:
+            def add(a: int, b: int) -> Any:
+                '''Add two numbers
+
+                Args:
+                    a: First number
+                    b: Second number
+                '''
+                pass
+        """
+        # Extract parameter info from JSON schema
+        props = self.parameters.get("properties", {})
+        required = self.parameters.get("required", [])
+
+        # Build function signature
+        params = []
+        for param_name, param_info in props.items():
+            # Get type (default to Any)
+            param_type = param_info.get("type", "Any")
+
+            # Convert JSON schema types to Python types
+            type_map = {
+                "string": "str",
+                "integer": "int",
+                "number": "float",
+                "boolean": "bool",
+                "array": "list",
+                "object": "dict",
+            }
+            python_type = type_map.get(param_type, "Any")
+
+            # Add to params list
+            params.append(f"{param_name}: {python_type}")
+
+        # Add * to indicate keyword-only parameters
+        param_str = f"*, {', '.join(params)}" if params else ""
+
+        # Build docstring with parameter descriptions
+        param_docs = []
+        for param_name, param_info in props.items():
+            desc = param_info.get("description", "")
+            required_marker = " (required)" if param_name in required else ""
+            param_docs.append(f"        {param_name}: {desc}{required_marker}")
+
+        param_doc_str = "\n".join(param_docs) if param_docs else "        No parameters"
+
+        # Build usage example with keyword arguments
+        example_args = []
+        for param_name, param_info in props.items():
+            # Create example values based on type
+            param_type = param_info.get("type", "string")
+            if param_type == "string":
+                example_value = f'"{param_name}_value"'
+            elif param_type == "integer":
+                example_value = "42"
+            elif param_type == "number":
+                example_value = "3.14"
+            elif param_type == "boolean":
+                example_value = "True"
+            elif param_type == "array":
+                example_value = '["item1", "item2"]'
+            elif param_type == "object":
+                example_value = '{"key": "value"}'
+            else:
+                example_value = "value"
+
+            example_args.append(f"{param_name}={example_value}")
+
+        usage_example = (
+            f"result = {self.name}({', '.join(example_args)})" if example_args else f"result = {self.name}()"
+        )
+
+        # Build full function definition
+        return f'''def {self.name}({param_str}) -> Any:
+    """{self.description}
+
+    Args:
+{param_doc_str}
+
+    Usage:
+        {usage_example}
+    """
+    pass
+'''
+
+    async def execute(self, **kwargs) -> Any:
+        """Execute the tool with given arguments.
+
+        Handles both sync and async functions.
+
+        Args:
+            **kwargs: Arguments to pass to the tool
+
+        Returns:
+            Tool execution result
+        """
+        # Check if function is async
+        if asyncio.iscoroutinefunction(self.function):
+            return await self.function(**kwargs)
+        else:
+            # Run sync function
+            return self.function(**kwargs)
+
+
+def create_tool_from_function(func: Callable, name: Optional[str] = None, description: Optional[str] = None) -> Tool:
+    """Create a Tool from a Python function.
+
+    Extracts parameter info from function signature and docstring.
+
+    Args:
+        func: The function to wrap
+        name: Tool name (defaults to function name)
+        description: Tool description (defaults to docstring)
+
+    Returns:
+        Tool: Wrapped function
+
+    Example:
+        def multiply(a: int, b: int) -> int:
+            '''Multiply two numbers'''
+            return a * b
+
+        tool = create_tool_from_function(multiply)
+    """
+    # Get name and description
+    tool_name = name or func.__name__
+    tool_description = description or (func.__doc__ or "").strip().split("\n")[0]
+
+    # Extract parameters from signature
+    sig = inspect.signature(func)
+    parameters = {"type": "object", "properties": {}, "required": []}
+
+    for param_name, param in sig.parameters.items():
+        # Skip self/cls
+        if param_name in ("self", "cls"):
+            continue
+
+        # Get type annotation and convert to JSON schema type
+        if param.annotation != inspect.Parameter.empty:
+            # Convert Python type to JSON schema type
+            type_map = {
+                str: "string",
+                int: "integer",
+                float: "number",
+                bool: "boolean",
+                list: "array",
+                dict: "object",
+            }
+            param_type = type_map.get(param.annotation)
+
+            if param_type:
+                # Known type - add type constraint
+                parameters["properties"][param_name] = {"type": param_type}
+            else:
+                # Unknown type - omit type constraint (accepts any value, but valid JSON Schema)
+                parameters["properties"][param_name] = {}
+        else:
+            # No annotation - omit type constraint
+            parameters["properties"][param_name] = {}
+
+        # Check if required (no default value)
+        if param.default == inspect.Parameter.empty:
+            parameters["required"].append(param_name)
+
+    return Tool(
+        name=tool_name,
+        description=tool_description,
+        parameters=parameters,
+        function=func,
+    )
+
+
+def create_tool_from_tsugite(tool_name: str) -> Tool:
+    """Convert existing tsugite tool to Tool object.
+
+    Tsugite has its own tool registry. This function wraps those
+    tools in our Tool interface.
+
+    Args:
+        tool_name: Name of tool in tsugite registry
+
+    Returns:
+        Tool: Wrapped tsugite tool
+
+    Example:
+        tool = create_tool_from_tsugite("read_file")
+        result = await tool.execute(file_path="/path/to/file")
+    """
+    from tsugite.tools import call_tool, get_tool
+
+    # Get tool info from registry
+    tool_info = get_tool(tool_name)
+
+    # Create async wrapper function that preserves signature
+    sig = inspect.signature(tool_info.func)
+
+    async def tool_wrapper(**kwargs):
+        """Wrapper that calls tsugite tool."""
+        # call_tool might be sync or async, handle both
+        result = call_tool(tool_name, **kwargs)
+        # If result is a coroutine, await it
+        if inspect.iscoroutine(result):
+            return await result
+        return result
+
+    # Set the signature on the wrapper
+    tool_wrapper.__signature__ = sig
+
+    # Create Tool using function converter
+    return create_tool_from_function(
+        tool_wrapper,
+        name=tool_name,
+        description=tool_info.description,
+    )