hopx-ai 0.1.11__py3-none-any.whl

hopx_ai/async_sandbox.py

@@ -0,0 +1,427 @@
+"""Async Sandbox class - for async/await usage."""
+
+from typing import Optional, List, AsyncIterator, Dict
+from .models import SandboxInfo, Template
+from ._async_client import AsyncHTTPClient
+from ._utils import remove_none_values
+
+
+class AsyncSandbox:
+    """
+    Async Bunnyshell Sandbox - lightweight VM management with async/await.
+    
+    For async Python applications (FastAPI, aiohttp, etc.)
+    
+    Example:
+        >>> from bunnyshell import AsyncSandbox
+        >>> 
+        >>> async with AsyncSandbox.create(template="nodejs") as sandbox:
+        ...     info = await sandbox.get_info()
+        ...     print(info.public_host)
+        # Automatically cleaned up!
+    """
+    
+    def __init__(
+        self,
+        sandbox_id: str,
+        *,
+        api_key: Optional[str] = None,
+        base_url: str = "https://api.hopx.dev",
+        timeout: int = 60,
+        max_retries: int = 3,
+    ):
+        """
+        Initialize AsyncSandbox instance.
+        
+        Note: Prefer using AsyncSandbox.create() or AsyncSandbox.connect() instead.
+        
+        Args:
+            sandbox_id: Sandbox ID
+            api_key: API key (or use HOPX_API_KEY env var)
+            base_url: API base URL
+            timeout: Request timeout in seconds
+            max_retries: Maximum number of retries
+        """
+        self.sandbox_id = sandbox_id
+        self._client = AsyncHTTPClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+    
+    # =============================================================================
+    # CLASS METHODS (Static - for creating/listing sandboxes)
+    # =============================================================================
+    
+    @classmethod
+    async def create(
+        cls,
+        template: Optional[str] = None,
+        *,
+        template_id: Optional[str] = None,
+        region: Optional[str] = None,
+        timeout_seconds: Optional[int] = None,
+        internet_access: Optional[bool] = None,
+        env_vars: Optional[Dict[str, str]] = None,
+        api_key: Optional[str] = None,
+        base_url: str = "https://api.hopx.dev",
+    ) -> "AsyncSandbox":
+        """
+        Create a new sandbox (async).
+        
+        You can create a sandbox in two ways:
+        1. From template ID (resources auto-loaded from template)
+        2. Custom sandbox (specify template name + resources)
+        
+        Args:
+            template: Template name for custom sandbox (e.g., "code-interpreter", "nodejs")
+            template_id: Template ID to create from (resources auto-loaded, no vcpu/memory needed)
+            region: Preferred region (optional)
+            timeout_seconds: Auto-kill timeout in seconds (optional, default: no timeout)
+            internet_access: Enable internet access (optional, default: True)
+            env_vars: Environment variables (optional)
+            api_key: API key (or use HOPX_API_KEY env var)
+            base_url: API base URL
+        
+        Returns:
+            AsyncSandbox instance
+        
+        Examples:
+            >>> # Create from template ID with timeout
+            >>> sandbox = await AsyncSandbox.create(
+            ...     template_id="282",
+            ...     timeout_seconds=600,
+            ...     internet_access=False
+            ... )
+            
+            >>> # Create custom sandbox
+            >>> sandbox = await AsyncSandbox.create(
+            ...     template="nodejs",
+            ...     timeout_seconds=300
+            ... )
+        """
+        client = AsyncHTTPClient(api_key=api_key, base_url=base_url)
+        
+        # Validate parameters
+        if template_id:
+            # Create from template ID (resources from template)
+            # Convert template_id to string if it's an int (API may return int from build)
+            data = remove_none_values({
+                "template_id": str(template_id),
+                "region": region,
+                "timeout_seconds": timeout_seconds,
+                "internet_access": internet_access,
+                "env_vars": env_vars,
+            })
+        elif template:
+            # Create from template name (resources from template)
+            data = remove_none_values({
+                "template_name": template,
+                "region": region,
+                "timeout_seconds": timeout_seconds,
+                "internet_access": internet_access,
+                "env_vars": env_vars,
+            })
+        else:
+            raise ValueError("Either 'template' or 'template_id' must be provided")
+        
+        response = await client.post("/v1/sandboxes", json=data)
+        sandbox_id = response["id"]
+        
+        return cls(
+            sandbox_id=sandbox_id,
+            api_key=api_key,
+            base_url=base_url,
+        )
+    
+    @classmethod
+    async def connect(
+        cls,
+        sandbox_id: str,
+        *,
+        api_key: Optional[str] = None,
+        base_url: str = "https://api.hopx.dev",
+    ) -> "AsyncSandbox":
+        """
+        Connect to an existing sandbox (async).
+        
+        Args:
+            sandbox_id: Sandbox ID
+            api_key: API key (or use HOPX_API_KEY env var)
+            base_url: API base URL
+        
+        Returns:
+            AsyncSandbox instance
+        
+        Example:
+            >>> sandbox = await AsyncSandbox.connect("sandbox_id")
+            >>> info = await sandbox.get_info()
+        """
+        instance = cls(
+            sandbox_id=sandbox_id,
+            api_key=api_key,
+            base_url=base_url,
+        )
+        
+        # Verify it exists
+        await instance.get_info()
+        
+        return instance
+    
+    @classmethod
+    async def list(
+        cls,
+        *,
+        status: Optional[str] = None,
+        region: Optional[str] = None,
+        limit: int = 100,
+        api_key: Optional[str] = None,
+        base_url: str = "https://api.hopx.dev",
+    ) -> List["AsyncSandbox"]:
+        """
+        List all sandboxes (async).
+        
+        Args:
+            status: Filter by status
+            region: Filter by region
+            limit: Maximum number of results
+            api_key: API key
+            base_url: API base URL
+        
+        Returns:
+            List of AsyncSandbox instances
+        
+        Example:
+            >>> sandboxes = await AsyncSandbox.list(status="running")
+            >>> for sb in sandboxes:
+            ...     info = await sb.get_info()
+            ...     print(info.public_host)
+        """
+        client = AsyncHTTPClient(api_key=api_key, base_url=base_url)
+        
+        params = remove_none_values({
+            "status": status,
+            "region": region,
+            "limit": limit,
+        })
+        
+        response = await client.get("/v1/sandboxes", params=params)
+        sandboxes_data = response.get("data", [])
+        
+        return [
+            cls(
+                sandbox_id=sb["id"],
+                api_key=api_key,
+                base_url=base_url,
+            )
+            for sb in sandboxes_data
+        ]
+    
+    @classmethod
+    async def iter(
+        cls,
+        *,
+        status: Optional[str] = None,
+        region: Optional[str] = None,
+        api_key: Optional[str] = None,
+        base_url: str = "https://api.hopx.dev",
+    ) -> AsyncIterator["AsyncSandbox"]:
+        """
+        Lazy async iterator for sandboxes.
+        
+        Yields sandboxes one by one, fetching pages as needed.
+        
+        Args:
+            status: Filter by status
+            region: Filter by region
+            api_key: API key
+            base_url: API base URL
+        
+        Yields:
+            AsyncSandbox instances
+        
+        Example:
+            >>> async for sandbox in AsyncSandbox.iter(status="running"):
+            ...     info = await sandbox.get_info()
+            ...     print(info.public_host)
+            ...     if found:
+            ...         break  # Doesn't fetch remaining pages
+        """
+        client = AsyncHTTPClient(api_key=api_key, base_url=base_url)
+        limit = 100
+        has_more = True
+        cursor = None
+        
+        while has_more:
+            params = {"limit": limit}
+            if status:
+                params["status"] = status
+            if region:
+                params["region"] = region
+            if cursor:
+                params["cursor"] = cursor
+            
+            response = await client.get("/v1/sandboxes", params=params)
+            
+            for item in response.get("data", []):
+                yield cls(
+                    sandbox_id=item["id"],
+                    api_key=api_key,
+                    base_url=base_url,
+                )
+            
+            has_more = response.get("has_more", False)
+            cursor = response.get("next_cursor")
+    
+    @classmethod
+    async def list_templates(
+        cls,
+        *,
+        category: Optional[str] = None,
+        language: Optional[str] = None,
+        api_key: Optional[str] = None,
+        base_url: str = "https://api.hopx.dev",
+    ) -> List[Template]:
+        """
+        List available templates (async).
+        
+        Args:
+            category: Filter by category
+            language: Filter by language
+            api_key: API key
+            base_url: API base URL
+        
+        Returns:
+            List of Template objects
+        
+        Example:
+            >>> templates = await AsyncSandbox.list_templates()
+            >>> for t in templates:
+            ...     print(f"{t.name}: {t.display_name}")
+        """
+        client = AsyncHTTPClient(api_key=api_key, base_url=base_url)
+        
+        params = remove_none_values({
+            "category": category,
+            "language": language,
+        })
+        
+        response = await client.get("/v1/templates", params=params)
+        templates_data = response.get("data", [])
+        
+        return [Template(**t) for t in templates_data]
+    
+    @classmethod
+    async def get_template(
+        cls,
+        name: str,
+        *,
+        api_key: Optional[str] = None,
+        base_url: str = "https://api.hopx.dev",
+    ) -> Template:
+        """
+        Get template details (async).
+        
+        Args:
+            name: Template name
+            api_key: API key
+            base_url: API base URL
+        
+        Returns:
+            Template object
+        
+        Example:
+            >>> template = await AsyncSandbox.get_template("nodejs")
+            >>> print(template.description)
+        """
+        client = AsyncHTTPClient(api_key=api_key, base_url=base_url)
+        response = await client.get(f"/v1/templates/{name}")
+        return Template(**response)
+    
+    # =============================================================================
+    # INSTANCE METHODS (for managing individual sandbox)
+    # =============================================================================
+    
+    async def get_info(self) -> SandboxInfo:
+        """
+        Get current sandbox information (async).
+        
+        Returns:
+            SandboxInfo with current state
+        
+        Example:
+            >>> info = await sandbox.get_info()
+            >>> print(f"Status: {info.status}")
+        """
+        response = await self._client.get(f"/v1/sandboxes/{self.sandbox_id}")
+        return SandboxInfo(
+            sandbox_id=response["id"],
+            template_id=response.get("template_id"),
+            template_name=response.get("template_name"),
+            organization_id=response.get("organization_id", ""),
+            node_id=response.get("node_id"),
+            region=response.get("region"),
+            status=response["status"],
+            public_host=response.get("public_host") or response.get("direct_url", ""),
+            vcpu=response.get("resources", {}).get("vcpu"),
+            memory_mb=response.get("resources", {}).get("memory_mb"),
+            disk_mb=response.get("resources", {}).get("disk_mb"),
+            created_at=response.get("created_at"),
+            started_at=None,
+            end_at=None,
+        )
+    
+    async def stop(self) -> None:
+        """Stop the sandbox (async)."""
+        await self._client.post(f"/v1/sandboxes/{self.sandbox_id}/stop")
+    
+    async def start(self) -> None:
+        """Start a stopped sandbox (async)."""
+        await self._client.post(f"/v1/sandboxes/{self.sandbox_id}/start")
+    
+    async def pause(self) -> None:
+        """Pause the sandbox (async)."""
+        await self._client.post(f"/v1/sandboxes/{self.sandbox_id}/pause")
+    
+    async def resume(self) -> None:
+        """Resume a paused sandbox (async)."""
+        await self._client.post(f"/v1/sandboxes/{self.sandbox_id}/resume")
+    
+    async def kill(self) -> None:
+        """
+        Destroy the sandbox immediately (async).
+        
+        This action is irreversible.
+        
+        Example:
+            >>> await sandbox.kill()
+        """
+        await self._client.delete(f"/v1/sandboxes/{self.sandbox_id}")
+    
+    # =============================================================================
+    # ASYNC CONTEXT MANAGER (auto-cleanup)
+    # =============================================================================
+    
+    async def __aenter__(self) -> "AsyncSandbox":
+        """Async context manager entry."""
+        return self
+    
+    async def __aexit__(self, *args) -> None:
+        """Async context manager exit - auto cleanup."""
+        try:
+            await self.kill()
+        except Exception:
+            # Ignore errors on cleanup
+            pass
+    
+    # =============================================================================
+    # UTILITY METHODS
+    # =============================================================================
+    
+    def __repr__(self) -> str:
+        return f"<AsyncSandbox {self.sandbox_id}>"
+    
+    def __str__(self) -> str:
+        return f"AsyncSandbox(id={self.sandbox_id})"
+

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}>"