hopx-ai 0.1.17__py3-none-any.whl

hopx_ai/cache.py

@@ -0,0 +1,97 @@
+"""Cache management resource for Bunnyshell Sandboxes."""
+
+from typing import Dict, Any, Optional
+import logging
+from ._agent_client import AgentHTTPClient
+
+logger = logging.getLogger(__name__)
+
+
+class Cache:
+    """
+    Cache management resource.
+    
+    Provides methods for managing execution result cache.
+    
+    Features:
+    - Get cache statistics
+    - Clear cache
+    
+    Example:
+        >>> sandbox = Sandbox.create(template="code-interpreter")
+        >>> 
+        >>> # Get cache stats
+        >>> stats = sandbox.cache.stats()
+        >>> print(f"Cache hits: {stats['hits']}")
+        >>> print(f"Cache size: {stats['size']} MB")
+        >>> 
+        >>> # Clear cache
+        >>> sandbox.cache.clear()
+    """
+    
+    def __init__(self, client: AgentHTTPClient):
+        """
+        Initialize Cache resource.
+        
+        Args:
+            client: Shared agent HTTP client
+        """
+        self._client = client
+        logger.debug("Cache resource initialized")
+    
+    def stats(self, *, timeout: Optional[int] = None) -> Dict[str, Any]:
+        """
+        Get cache statistics.
+        
+        Args:
+            timeout: Request timeout in seconds (overrides default)
+        
+        Returns:
+            Dictionary with cache statistics (hits, misses, size, etc.)
+        
+        Example:
+            >>> stats = sandbox.cache.stats()
+            >>> print(f"Cache hits: {stats['hits']}")
+            >>> print(f"Cache misses: {stats['misses']}")
+            >>> print(f"Hit rate: {stats['hit_rate']:.2%}")
+            >>> print(f"Cache size: {stats['size']} MB")
+            >>> print(f"Entry count: {stats['count']}")
+        """
+        logger.debug("Getting cache statistics")
+        
+        response = self._client.get(
+            "/cache/stats",
+            operation="get cache stats",
+            timeout=timeout
+        )
+        
+        return response.json()
+    
+    def clear(self, *, timeout: Optional[int] = None) -> Dict[str, Any]:
+        """
+        Clear the execution result cache.
+        
+        Args:
+            timeout: Request timeout in seconds (overrides default)
+        
+        Returns:
+            Dictionary with confirmation message
+        
+        Example:
+            >>> result = sandbox.cache.clear()
+            >>> print(result['message'])  # "Cache cleared successfully"
+            >>> print(f"Entries removed: {result.get('entries_removed', 0)}")
+        """
+        logger.debug("Clearing cache")
+        
+        response = self._client.post(
+            "/cache/clear",
+            operation="clear cache",
+            timeout=timeout
+        )
+        
+        return response.json()
+    
+    def __repr__(self) -> str:
+        return f"<Cache client={self._client}>"
+

hopx_ai/commands.py

@@ -0,0 +1,174 @@
+"""Command execution resource for Bunnyshell Sandboxes."""
+
+from typing import Optional, Dict
+import logging
+from .models import CommandResult
+from ._agent_client import AgentHTTPClient
+
+logger = logging.getLogger(__name__)
+
+
+class Commands:
+    """
+    Command execution resource.
+    
+    Provides methods for running shell commands inside the sandbox.
+    
+    Features:
+    - Automatic retry with exponential backoff
+    - Connection pooling for efficiency  
+    - Proper error handling
+    - Configurable timeouts
+    
+    Example:
+        >>> sandbox = Sandbox.create(template="code-interpreter")
+        >>> 
+        >>> # Run simple command
+        >>> result = sandbox.commands.run('ls -la /workspace')
+        >>> print(result.stdout)
+        >>> 
+        >>> # Check success
+        >>> if result.success:
+        ...     print("Command succeeded!")
+        ... else:
+        ...     print(f"Failed: {result.stderr}")
+    """
+    
+    def __init__(self, client: AgentHTTPClient):
+        """
+        Initialize Commands resource.
+        
+        Args:
+            client: Shared agent HTTP client
+        """
+        self._client = client
+        logger.debug("Commands resource initialized")
+    
+    def run(
+        self,
+        command: str,
+        *,
+        timeout: int = 30,
+        background: bool = False,
+        env: Optional[Dict[str, str]] = None,
+        working_dir: str = "/workspace",
+    ) -> CommandResult:
+        """
+        Run shell command.
+        
+        Args:
+            command: Shell command to run
+            timeout: Command timeout in seconds (default: 30)
+            background: Run in background (returns immediately)
+            env: Optional environment variables for this command only.
+                 Priority: Request env > Global env > Agent env
+            working_dir: Working directory for command (default: /workspace)
+        
+        Returns:
+            CommandResult with stdout, stderr, exit_code
+        
+        Raises:
+            CommandExecutionError: If command execution fails
+            TimeoutError: If command times out
+        
+        Example:
+            >>> # Simple command
+            >>> result = sandbox.commands.run('ls -la')
+            >>> print(result.stdout)
+            >>> print(f"Exit code: {result.exit_code}")
+            >>> 
+            >>> # With environment variables
+            >>> result = sandbox.commands.run(
+            ...     'echo $API_KEY',
+            ...     env={"API_KEY": "sk-test-123"}
+            ... )
+            >>> 
+            >>> # With custom timeout
+            >>> result = sandbox.commands.run('npm install', timeout=300)
+            >>> 
+            >>> # Check success
+            >>> if result.success:
+            ...     print("Success!")
+            ... else:
+            ...     print(f"Failed with exit code {result.exit_code}")
+            ...     print(f"Error: {result.stderr}")
+        """
+        if background:
+            return self._run_background(command, env=env, working_dir=working_dir)
+        
+        logger.debug(f"Running command: {command[:50]}...")
+        
+        # Build request payload
+        payload = {
+            "command": command,
+            "timeout": timeout,
+            "working_dir": working_dir
+        }
+        
+        # Add optional environment variables
+        if env:
+            payload["env"] = env
+        
+        response = self._client.post(
+            "/commands/run",
+            json=payload,
+            operation="run command",
+            context={"command": command},
+            timeout=timeout + 5  # Add buffer to HTTP timeout
+        )
+        
+        data = response.json()
+        
+        return CommandResult(
+            stdout=data.get("stdout", ""),
+            stderr=data.get("stderr", ""),
+            exit_code=data.get("exit_code", 0),
+            execution_time=data.get("execution_time", 0.0)
+        )
+    
+    def _run_background(
+        self,
+        command: str,
+        env: Optional[Dict[str, str]] = None,
+        working_dir: str = "/workspace"
+    ) -> CommandResult:
+        """
+        Run command in background.
+        
+        Args:
+            command: Shell command to run
+            env: Optional environment variables
+            working_dir: Working directory
+        
+        Returns:
+            CommandResult with process info
+        """
+        logger.debug(f"Running command in background: {command[:50]}...")
+        
+        # Build request payload
+        payload = {"command": command, "working_dir": working_dir}
+        
+        # Add optional environment variables
+        if env:
+            payload["env"] = env
+        
+        response = self._client.post(
+            "/commands/background",
+            json=payload,
+            operation="run background command",
+            context={"command": command},
+            timeout=10
+        )
+        
+        data = response.json()
+        
+        # Return a CommandResult indicating background execution
+        return CommandResult(
+            stdout=f"Background process started: {data.get('process_id', 'unknown')}",
+            stderr="",
+            exit_code=0,
+            execution_time=0.0
+        )
+    
+    def __repr__(self) -> str:
+        return f"<Commands client={self._client}>"