voxagent 0.1.1__tar.gz → 0.2.1__tar.gz

{voxagent-0.1.1 → voxagent-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voxagent
-Version: 0.1.1
+Version: 0.2.1
 Summary: A lightweight, model-agnostic LLM provider abstraction with streaming and tool support
 Project-URL: Homepage, https://github.com/lensator/voxagent
 Project-URL: Documentation, https://github.com/lensator/voxagent#readme
@@ -34,6 +34,8 @@ Requires-Dist: openai>=1.0; extra == 'all'
 Requires-Dist: tiktoken>=0.5; extra == 'all'
 Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.25; extra == 'anthropic'
+Provides-Extra: code
+Requires-Dist: restrictedpython>=7.0; extra == 'code'
 Provides-Extra: dev
 Requires-Dist: mypy>=1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'

{voxagent-0.1.1 → voxagent-0.2.1}/pyproject.toml

@@ -55,6 +55,10 @@ ollama = [
 mcp = [
     "mcp>=1.0",
 ]
+# Code sandbox support
+code = [
+    "RestrictedPython>=7.0",
+]
 # All providers
 all = [
     "voxagent[openai,anthropic,google,groq,ollama,mcp]",

{voxagent-0.1.1 → voxagent-0.2.1}/src/voxagent/_version.py

@@ -1,2 +1,2 @@
-__version__ = "0.1.1"
+__version__ = "0.2.1"
 __version_info__ = tuple(int(x) for x in __version__.split("."))

voxagent-0.2.1/src/voxagent/code/__init__.py

@@ -0,0 +1,55 @@
+"""Code execution sandbox for token optimization.
+
+This subpackage provides:
+- Sandboxed code execution (subprocess, Pyodide)
+- Tool file generation from MCP servers
+- Skills persistence and discovery
+- PII tokenization for privacy
+- Virtual filesystem for tool discovery
+- Code execution mode for agents
+- Tool proxy for routing sandbox calls to real implementations
+"""
+
+from voxagent.code.sandbox import CodeSandbox, SandboxResult, SubprocessSandbox
+from voxagent.code.virtual_fs import (
+    ToolCategory,
+    ToolRegistry,
+    VirtualFilesystem,
+)
+from voxagent.code.agent import (
+    CodeModeConfig,
+    CodeModeExecutor,
+    get_code_mode_system_prompt_addition,
+    setup_code_mode_for_agent,
+    CODE_MODE_SYSTEM_PROMPT,
+)
+from voxagent.code.tool_proxy import (
+    ToolCallRequest,
+    ToolCallResponse,
+    ToolProxyClient,
+    ToolProxyServer,
+    create_tool_proxy_pair,
+)
+
+__all__ = [
+    # Sandbox
+    "CodeSandbox",
+    "SandboxResult",
+    "SubprocessSandbox",
+    # Virtual FS
+    "ToolCategory",
+    "ToolRegistry",
+    "VirtualFilesystem",
+    # Code Mode Agent
+    "CodeModeConfig",
+    "CodeModeExecutor",
+    "CODE_MODE_SYSTEM_PROMPT",
+    "get_code_mode_system_prompt_addition",
+    "setup_code_mode_for_agent",
+    # Tool Proxy
+    "ToolCallRequest",
+    "ToolCallResponse",
+    "ToolProxyClient",
+    "ToolProxyServer",
+    "create_tool_proxy_pair",
+]

voxagent-0.2.1/src/voxagent/code/agent.py

@@ -0,0 +1,275 @@
+"""Code execution mode for Agent.
+
+When execution_mode="code", the agent uses a single execute_code tool
+instead of exposing all tools directly. The LLM writes Python code
+that calls tools via the virtual filesystem.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from voxagent.code.sandbox import SubprocessSandbox, SandboxResult
+from voxagent.code.virtual_fs import VirtualFilesystem, ToolRegistry
+from voxagent.tools.definition import ToolDefinition
+
+if TYPE_CHECKING:
+    from voxagent.agent.core import Agent
+
+
+# System prompt addition for code mode
+CODE_MODE_SYSTEM_PROMPT = '''
+## Code Execution Mode
+
+You have access to a single tool: `execute_code`. Use it to write Python code that:
+1. Explores available tools with `ls("tools/")` and `read("tools/<category>/<tool>.py")`
+2. Calls tools using `call_tool(category, tool_name, **kwargs)`
+3. Uses `print()` to output results
+
+### Available Functions in Sandbox
+- `ls(path)` - List directory contents (e.g., `ls("tools/")`, `ls("tools/devices/")`)
+- `read(path)` - Read file contents (e.g., `read("tools/devices/registry.py")`)
+- `call_tool(category, tool_name, **kwargs)` - Call a tool with arguments
+- `print(*args)` - Output results (captured and returned to you)
+
+### Workflow
+1. **Explore**: `print(ls("tools/"))` to see categories
+2. **Learn**: `print(read("tools/<category>/<tool>.py"))` to see tool signatures
+3. **Execute**: Use `call_tool()` to invoke tools
+4. **Report**: Use `print()` to show results
+
+### Example
+```python
+# Explore available tools
+print("Categories:", ls("tools/"))
+
+# Read a tool definition
+print(read("tools/devices/registry.py"))
+
+# Call the tool
+result = call_tool("devices", "registry.py", device_type="light")
+print("Devices:", result)
+```
+
+### Rules
+1. Always use `print()` to show results
+2. Explore before assuming - use `ls()` and `read()` first
+3. Handle errors with try/except when appropriate
+'''
+
+
+class CodeModeConfig:
+    """Configuration for code execution mode.
+    
+    Attributes:
+        enabled: Whether code mode is active
+        timeout_seconds: Max execution time per code block
+        memory_limit_mb: Max memory for sandbox
+        max_output_chars: Truncate output beyond this
+    """
+    
+    def __init__(
+        self,
+        enabled: bool = True,
+        timeout_seconds: int = 10,
+        memory_limit_mb: int = 128,
+        max_output_chars: int = 10000,
+    ):
+        self.enabled = enabled
+        self.timeout_seconds = timeout_seconds
+        self.memory_limit_mb = memory_limit_mb
+        self.max_output_chars = max_output_chars
+
+
+class CodeModeExecutor:
+    """Executes code for an agent in code mode.
+    
+    This class:
+    1. Manages the sandbox and virtual filesystem
+    2. Provides the execute_code tool implementation
+    3. Routes tool calls from sandbox to real implementations
+    """
+    
+    def __init__(
+        self,
+        config: CodeModeConfig,
+        tool_registry: ToolRegistry,
+    ):
+        self.config = config
+        self.tool_registry = tool_registry
+        self.sandbox = SubprocessSandbox(
+            timeout_seconds=config.timeout_seconds,
+            memory_limit_mb=config.memory_limit_mb,
+        )
+        self.virtual_fs = VirtualFilesystem(tool_registry)
+        
+        # Tool proxy for routing calls
+        self._tool_implementations: dict[str, Any] = {}
+    
+    def register_tool_implementation(
+        self,
+        category: str,
+        tool_name: str,
+        implementation: Any,
+    ) -> None:
+        """Register a real tool implementation for the proxy."""
+        key = f"{category}.{tool_name}"
+        self._tool_implementations[key] = implementation
+
+    async def execute_code(self, code: str) -> str:
+        """Execute Python code in the sandbox.
+
+        This is the tool exposed to the LLM.
+
+        Args:
+            code: Python source code to execute
+
+        Returns:
+            Captured output or error message
+        """
+        # Build globals with virtual filesystem functions only
+        # Note: call_tool is not passed to sandbox due to pickling constraints
+        # The LLM should use ls() and read() to explore, then describe what to call
+        globals_dict = self.virtual_fs.get_sandbox_globals()
+
+        # Execute in sandbox
+        result = await self.sandbox.execute(code, globals_dict)
+
+        # Format output
+        if result.success:
+            output = result.output or "(no output)"
+            if len(output) > self.config.max_output_chars:
+                output = output[:self.config.max_output_chars] + "\n... (truncated)"
+            return output
+        else:
+            return f"Error: {result.error}"
+
+    def call_tool(self, category: str, tool_name: str, **kwargs: Any) -> Any:
+        """Call a registered tool implementation.
+
+        This method is called outside the sandbox after the LLM
+        has explored tools and decided which one to call.
+
+        Args:
+            category: Tool category (e.g., "devices")
+            tool_name: Tool name (e.g., "registry.py")
+            **kwargs: Arguments to pass to the tool
+
+        Returns:
+            Tool result or error message
+        """
+        key = f"{category}.{tool_name}"
+        if key not in self._tool_implementations:
+            return f"Error: Tool '{key}' not found"
+        try:
+            impl = self._tool_implementations[key]
+            return impl(**kwargs)
+        except Exception as e:
+            return f"Error calling {key}: {e}"
+
+    def get_execute_code_tool(self) -> ToolDefinition:
+        """Get the execute_code tool definition for the agent."""
+        async def execute_code_wrapper(code: str) -> str:
+            """Execute Python code to explore and use tools.
+
+            Write Python code that:
+            1. Uses ls() to explore available tool categories
+            2. Uses read() to see tool signatures and documentation
+            3. Imports and calls tools to perform actions
+            4. Uses print() to output results
+
+            Args:
+                code: Python source code to execute
+
+            Returns:
+                Captured print() output or error message
+            """
+            return await self.execute_code(code)
+
+        return ToolDefinition(
+            name="execute_code",
+            description="Execute Python code to explore and use tools. Use ls() to see tools, read() to see signatures, and print() to output results.",
+            execute=execute_code_wrapper,
+            parameters={
+                "type": "object",
+                "properties": {
+                    "code": {
+                        "type": "string",
+                        "description": "Python source code to execute"
+                    }
+                },
+                "required": ["code"]
+            },
+            is_async=True,
+        )
+
+
+def get_code_mode_system_prompt_addition() -> str:
+    """Get the system prompt addition for code mode."""
+    return CODE_MODE_SYSTEM_PROMPT
+
+
+def setup_code_mode_for_agent(
+    agent: "Agent[Any, Any]",
+    config: CodeModeConfig | None = None,
+) -> CodeModeExecutor:
+    """Set up code mode for an existing agent.
+
+    This:
+    1. Creates a CodeModeExecutor
+    2. Registers the execute_code tool
+    3. Converts existing tools to virtual filesystem entries
+
+    Args:
+        agent: The agent to configure
+        config: Optional code mode configuration
+
+    Returns:
+        The CodeModeExecutor instance
+    """
+    config = config or CodeModeConfig()
+
+    # Create tool registry from agent's existing tools
+    vf_tool_registry = ToolRegistry()
+
+    # Convert agent's tools to virtual filesystem entries
+    for tool_def in agent._tool_registry.list():
+        # Create category based on tool name or use "default"
+        category = "default"
+
+        # Build tool definition content as Python stub
+        params_str = ", ".join(
+            f"{k}: {v.get('type', 'Any')}"
+            for k, v in tool_def.parameters.get("properties", {}).items()
+        )
+        tool_content = f'''def {tool_def.name}({params_str}) -> Any:
+    """{tool_def.description}"""
+    ...
+'''
+
+        # Get or create category
+        if category not in vf_tool_registry.list_categories():
+            vf_tool_registry.register_category(
+                category,
+                description="Default tool category",
+                tools={},
+            )
+
+        # Add tool to category
+        cat = vf_tool_registry.get_category(category)
+        if cat:
+            cat.tools[f"{tool_def.name}.py"] = tool_content
+
+    # Create executor
+    executor = CodeModeExecutor(config, vf_tool_registry)
+
+    # Register tool implementations
+    for tool_def in agent._tool_registry.list():
+        executor.register_tool_implementation(
+            "default",
+            f"{tool_def.name}.py",
+            tool_def.execute,
+        )
+
+    return executor
+

voxagent-0.2.1/src/voxagent/code/sandbox.py

@@ -0,0 +1,335 @@
+"""Sandboxed Python code execution with security restrictions.
+
+This module provides secure code execution using RestrictedPython
+and subprocess isolation with resource limits.
+"""
+
+from __future__ import annotations
+
+import multiprocessing
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from voxagent.code.tool_proxy import ToolProxyClient
+
+
+@dataclass
+class SandboxResult:
+    """Result of sandboxed code execution.
+
+    Attributes:
+        output: Captured stdout from print() calls
+        error: Error message if execution failed
+        execution_time_ms: Time taken to execute in milliseconds
+        success: Whether execution completed without errors (derived from error being None)
+    """
+
+    output: str | None = None
+    error: str | None = None
+    execution_time_ms: float | None = None
+
+    @property
+    def success(self) -> bool:
+        """Return True if execution completed without errors."""
+        return self.error is None
+
+
+class CodeSandbox(ABC):
+    """Abstract base class for code execution sandboxes."""
+
+    @abstractmethod
+    async def execute(
+        self, code: str, globals_dict: dict[str, Any] | None = None
+    ) -> SandboxResult:
+        """Execute Python code in a sandboxed environment.
+
+        Args:
+            code: Python source code to execute
+            globals_dict: Optional globals to inject (e.g., ls, read functions)
+
+        Returns:
+            SandboxResult with output or error
+        """
+        ...
+
+
+def _inplacevar_(op: str, x: Any, y: Any) -> Any:
+    """Handle in-place operators (+=, -=, etc.) in RestrictedPython."""
+    if op == "+=":
+        return x + y
+    elif op == "-=":
+        return x - y
+    elif op == "*=":
+        return x * y
+    elif op == "/=":
+        return x / y
+    elif op == "//=":
+        return x // y
+    elif op == "%=":
+        return x % y
+    elif op == "**=":
+        return x**y
+    elif op == "&=":
+        return x & y
+    elif op == "|=":
+        return x | y
+    elif op == "^=":
+        return x ^ y
+    elif op == ">>=":
+        return x >> y
+    elif op == "<<=":
+        return x << y
+    else:
+        raise ValueError(f"Unknown operator: {op}")
+
+
+def _execute_in_subprocess(
+    code: str,
+    globals_dict: dict[str, Any],
+    result_queue: multiprocessing.Queue,  # type: ignore[type-arg]
+    memory_limit_mb: int,
+) -> None:
+    """Subprocess entry point for sandboxed execution."""
+    # Import here to avoid loading in main process
+    import ast
+    import warnings
+
+    # Suppress RestrictedPython SyntaxWarnings about print/printed variable
+    # These warnings are harmless but noisy (about print transformation internals)
+    warnings.filterwarnings(
+        "ignore",
+        message=".*Prints, but never reads 'printed' variable.*",
+        category=SyntaxWarning,
+    )
+
+    from RestrictedPython import compile_restricted, safe_builtins
+    from RestrictedPython.Eval import default_guarded_getitem, default_guarded_getiter
+    from RestrictedPython.Guards import (
+        guarded_iter_unpack_sequence,
+        safer_getattr,
+    )
+    from RestrictedPython.PrintCollector import PrintCollector
+    from RestrictedPython.transformer import (
+        IOPERATOR_TO_STR,
+        RestrictingNodeTransformer,
+        copy_locations,
+    )
+
+    # Custom policy that allows augmented assignment on attributes
+    class PermissiveNodeTransformer(RestrictingNodeTransformer):
+        """A more permissive node transformer that allows augmented assignment."""
+
+        def visit_AugAssign(self, node: ast.AugAssign) -> ast.AST:
+            """Allow augmented assignment on attributes and subscripts.
+
+            Transforms 'a.x += 1' to 'a.x = _inplacevar_("+=", a.x, 1)'
+            and 'a[i] += 1' to 'a[i] = _inplacevar_("+=", a[i], 1)'
+            """
+            node = self.node_contents_visit(node)
+
+            if isinstance(node.target, ast.Attribute):
+                # Transform a.x += 1 to a.x = _inplacevar_("+=", a.x, 1)
+                new_node = ast.Assign(
+                    targets=[
+                        ast.Attribute(
+                            value=node.target.value,
+                            attr=node.target.attr,
+                            ctx=ast.Store(),
+                        )
+                    ],
+                    value=ast.Call(
+                        func=ast.Name("_inplacevar_", ast.Load()),
+                        args=[
+                            ast.Constant(IOPERATOR_TO_STR[type(node.op)]),
+                            ast.Attribute(
+                                value=node.target.value,
+                                attr=node.target.attr,
+                                ctx=ast.Load(),
+                            ),
+                            node.value,
+                        ],
+                        keywords=[],
+                    ),
+                )
+                copy_locations(new_node, node)
+                return new_node
+
+            elif isinstance(node.target, ast.Subscript):
+                # Transform a[i] += 1 to a[i] = _inplacevar_("+=", a[i], 1)
+                new_node = ast.Assign(
+                    targets=[
+                        ast.Subscript(
+                            value=node.target.value,
+                            slice=node.target.slice,
+                            ctx=ast.Store(),
+                        )
+                    ],
+                    value=ast.Call(
+                        func=ast.Name("_inplacevar_", ast.Load()),
+                        args=[
+                            ast.Constant(IOPERATOR_TO_STR[type(node.op)]),
+                            ast.Subscript(
+                                value=node.target.value,
+                                slice=node.target.slice,
+                                ctx=ast.Load(),
+                            ),
+                            node.value,
+                        ],
+                        keywords=[],
+                    ),
+                )
+                copy_locations(new_node, node)
+                return new_node
+
+            elif isinstance(node.target, ast.Name):
+                new_node = ast.Assign(
+                    targets=[node.target],
+                    value=ast.Call(
+                        func=ast.Name("_inplacevar_", ast.Load()),
+                        args=[
+                            ast.Constant(IOPERATOR_TO_STR[type(node.op)]),
+                            ast.Name(node.target.id, ast.Load()),
+                            node.value,
+                        ],
+                        keywords=[],
+                    ),
+                )
+                copy_locations(new_node, node)
+                return new_node
+            else:
+                raise NotImplementedError(f"Unknown target type: {type(node.target)}")
+
+    # Set memory limit (Unix only)
+    try:
+        import resource
+
+        limit_bytes = memory_limit_mb * 1024 * 1024
+        # Try to set RLIMIT_AS (address space) - works on Linux
+        try:
+            soft, hard = resource.getrlimit(resource.RLIMIT_AS)
+            # Only set if we can (soft limit can be lowered)
+            if limit_bytes <= hard:
+                resource.setrlimit(resource.RLIMIT_AS, (limit_bytes, hard))
+        except (ValueError, OSError):
+            pass
+        # Also try RLIMIT_DATA
+        try:
+            soft, hard = resource.getrlimit(resource.RLIMIT_DATA)
+            if limit_bytes <= hard:
+                resource.setrlimit(resource.RLIMIT_DATA, (limit_bytes, hard))
+        except (ValueError, OSError):
+            pass
+    except ImportError:
+        pass  # Windows
+
+    # Build safe builtins
+    safe_builtins_copy = dict(safe_builtins)
+    # Remove dangerous builtins
+    for name in ("open", "eval", "exec", "compile", "__import__"):
+        safe_builtins_copy.pop(name, None)
+
+    try:
+        byte_code = compile_restricted(
+            code, "<sandbox>", "exec", policy=PermissiveNodeTransformer
+        )
+        if byte_code is None:
+            result_queue.put(SandboxResult(output="", error="SyntaxError: compilation failed"))
+            return
+
+        exec_globals: dict[str, Any] = {
+            "__builtins__": safe_builtins_copy,
+            "__name__": "__main__",
+            "__doc__": None,
+            # Required for class definitions in RestrictedPython
+            "__metaclass__": type,
+            # _print_ is a factory - RestrictedPython will call it to create a collector
+            "_print_": PrintCollector,
+            # Also provide _getattr_ for attribute access
+            "_getattr_": safer_getattr,
+            "_getitem_": default_guarded_getitem,
+            "_getiter_": default_guarded_getiter,
+            "_iter_unpack_sequence_": guarded_iter_unpack_sequence,
+            "_inplacevar_": _inplacevar_,
+            # Provide write guard for attribute writes
+            "_write_": lambda x: x,
+            **globals_dict,
+        }
+        exec(byte_code, exec_globals)
+        # Get the _print object that was created during execution and call it
+        _print_obj = exec_globals.get("_print")
+        output = _print_obj() if _print_obj else ""
+        result_queue.put(
+            SandboxResult(
+                output=output if output else "",
+            )
+        )
+    except SyntaxError as e:
+        result_queue.put(SandboxResult(output="", error=f"SyntaxError: {e}"))
+    except Exception as e:
+        result_queue.put(SandboxResult(output="", error=f"{type(e).__name__}: {e}"))
+
+
+class SubprocessSandbox(CodeSandbox):
+    """Execute Python code in an isolated subprocess with RestrictedPython.
+
+    Security features:
+    - RestrictedPython AST filtering (blocks imports, file access, etc.)
+    - Process isolation via multiprocessing
+    - Timeout enforcement
+    - Memory limits (Unix only)
+
+    Args:
+        timeout_seconds: Maximum execution time (default: 10)
+        memory_limit_mb: Maximum memory in MB (default: 128, Unix only)
+        tool_proxy_client: Optional tool proxy client for routing tool calls
+    """
+
+    def __init__(
+        self,
+        timeout_seconds: int = 10,
+        memory_limit_mb: int = 128,
+        tool_proxy_client: "ToolProxyClient | None" = None,
+    ) -> None:
+        self.timeout_seconds = timeout_seconds
+        self.memory_limit_mb = memory_limit_mb
+        self.tool_proxy_client = tool_proxy_client
+
+    async def execute(
+        self, code: str, globals_dict: dict[str, Any] | None = None
+    ) -> SandboxResult:
+        """Execute code in subprocess with RestrictedPython."""
+        start_time = time.monotonic()
+
+        result_queue: multiprocessing.Queue[SandboxResult] = multiprocessing.Queue()
+        process = multiprocessing.Process(
+            target=_execute_in_subprocess,
+            args=(code, globals_dict or {}, result_queue, self.memory_limit_mb),
+        )
+        process.start()
+        process.join(timeout=self.timeout_seconds)
+
+        execution_time_ms = (time.monotonic() - start_time) * 1000
+
+        if process.is_alive():
+            process.kill()
+            process.join()
+            return SandboxResult(
+                output="",
+                error="Execution timed out",
+                execution_time_ms=execution_time_ms,
+            )
+
+        try:
+            result = result_queue.get_nowait()
+            result.execution_time_ms = execution_time_ms
+            return result
+        except Exception:
+            return SandboxResult(
+                output="",
+                error="No result from subprocess",
+                execution_time_ms=execution_time_ms,
+            )
+