hopx-ai 0.1.10__tar.gz → 0.1.16__tar.gz

{hopx_ai-0.1.10 → hopx_ai-0.1.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hopx-ai
-Version: 0.1.10
+Version: 0.1.16
 Summary: Official Python SDK for HOPX.AI Sandboxes
 Project-URL: Homepage, https://hopx.ai
 Project-URL: Documentation, https://docs.hopx.ai
@@ -329,18 +329,20 @@ asyncio.run(terminal_session())
 
 ```python
 sandbox = Sandbox.create(
-    template='code-interpreter',
+    template='code-interpreter',  # Template defines CPU/RAM/Disk resources
     api_key='your-api-key',
-    vcpu=4,              # 4 vCPUs
-    memory_mb=4096,      # 4GB RAM
-    disk_gb=20,          # 20GB disk
-    region='us-west-2',  # Specific region
-    timeout=600,         # 10 minute timeout
-    env_vars={           # Pre-set environment variables
+    region='us-west-2',           # Preferred region (optional)
+    timeout_seconds=600,          # Auto-kill after 10 minutes (optional)
+    internet_access=True,         # Enable internet access (optional, default: True)
+    env_vars={                    # Pre-set environment variables (optional)
         'DATABASE_URL': 'postgres://...',
         'API_KEY': 'sk-...'
     }
 )
+
+# Note: Resources (vCPU, RAM, Disk) come from the template.
+# To customize resources, create a custom template with Template.build()
+# See: https://docs.hopx.ai/templates
 ```
 
 ## Error Handling

{hopx_ai-0.1.10 → hopx_ai-0.1.16}/README.md

@@ -296,18 +296,20 @@ asyncio.run(terminal_session())
 
 ```python
 sandbox = Sandbox.create(
-    template='code-interpreter',
+    template='code-interpreter',  # Template defines CPU/RAM/Disk resources
     api_key='your-api-key',
-    vcpu=4,              # 4 vCPUs
-    memory_mb=4096,      # 4GB RAM
-    disk_gb=20,          # 20GB disk
-    region='us-west-2',  # Specific region
-    timeout=600,         # 10 minute timeout
-    env_vars={           # Pre-set environment variables
+    region='us-west-2',           # Preferred region (optional)
+    timeout_seconds=600,          # Auto-kill after 10 minutes (optional)
+    internet_access=True,         # Enable internet access (optional, default: True)
+    env_vars={                    # Pre-set environment variables (optional)
         'DATABASE_URL': 'postgres://...',
         'API_KEY': 'sk-...'
     }
 )
+
+# Note: Resources (vCPU, RAM, Disk) come from the template.
+# To customize resources, create a custom template with Template.build()
+# See: https://docs.hopx.ai/templates
 ```
 
 ## Error Handling

{hopx_ai-0.1.10 → hopx_ai-0.1.16}/hopx_ai/__init__.py

@@ -39,7 +39,7 @@ from .models import (
     DisplayInfo,
 )
 from .errors import (
-    BunnyshellError,
+    HopxError,
     APIError,
     AuthenticationError,
     NotFoundError,
@@ -85,7 +85,7 @@ __all__ = [
     "RecordingInfo",
     "DisplayInfo",
     # Errors
-    "BunnyshellError",
+    "HopxError",
     "APIError",
     "AuthenticationError",
     "NotFoundError",

{hopx_ai-0.1.10 → hopx_ai-0.1.16}/hopx_ai/_agent_client.py

@@ -36,6 +36,7 @@ class AgentHTTPClient:
         jwt_token: Optional[str] = None,
         timeout: int = 30,
         max_retries: int = 3,
+        token_refresh_callback: Optional[callable] = None,
     ):
         """
         Initialize agent HTTP client.
@@ -45,11 +46,13 @@ class AgentHTTPClient:
             jwt_token: JWT token for agent authentication
             timeout: Default timeout in seconds
             max_retries: Maximum retry attempts
+            token_refresh_callback: Callback to refresh token on 401 (returns new token)
         """
         self._agent_url = agent_url.rstrip('/')
         self._jwt_token = jwt_token
         self._timeout = timeout
         self._max_retries = max_retries
+        self._token_refresh_callback = token_refresh_callback
         
         # Build headers
         headers = {}
@@ -298,6 +301,21 @@ class AgentHTTPClient:
                 return response
             
             except httpx.HTTPStatusError as e:
+                # Handle 401 Unauthorized - try to refresh token
+                if e.response.status_code == 401 and self._token_refresh_callback and attempt == 0:
+                    logger.info(f"{operation} got 401 Unauthorized, attempting token refresh...")
+                    try:
+                        # Call refresh callback to get new token
+                        new_token = self._token_refresh_callback()
+                        if new_token:
+                            # Update token and retry request
+                            self.update_jwt_token(new_token)
+                            logger.info(f"{operation} token refreshed, retrying request...")
+                            continue
+                    except Exception as refresh_error:
+                        logger.error(f"Token refresh failed: {refresh_error}")
+                        # Fall through to raise original error
+                
                 # Check if should retry
                 if attempt < self._max_retries - 1 and self._should_retry(e.response.status_code):
                     delay = self._get_retry_delay(attempt)

hopx_ai-0.1.16/hopx_ai/_async_agent_client.py

@@ -0,0 +1,223 @@
+"""Async HTTP client for agent operations with retry logic."""
+
+import asyncio
+import logging
+from typing import Optional, Dict, Any
+import httpx
+from .errors import (
+    FileNotFoundError,
+    FileOperationError,
+    CodeExecutionError,
+    CommandExecutionError,
+    DesktopNotAvailableError,
+    AgentError,
+    NetworkError,
+    TimeoutError as HopxTimeoutError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncAgentHTTPClient:
+    """
+    Async HTTP client for agent operations with retry logic and error handling.
+    
+    Features:
+    - Connection pooling (reuses TCP connections)
+    - Automatic retries with exponential backoff
+    - Proper error wrapping to HOPX exceptions
+    - Configurable timeouts
+    """
+    
+    def __init__(
+        self,
+        agent_url: str,
+        *,
+        jwt_token: Optional[str] = None,
+        timeout: int = 30,
+        max_retries: int = 3,
+        token_refresh_callback: Optional[callable] = None,
+    ):
+        """
+        Initialize async agent HTTP client.
+        
+        Args:
+            agent_url: Agent base URL (e.g., https://7777-{id}.domain)
+            jwt_token: JWT token for agent authentication
+            timeout: Default timeout in seconds
+            max_retries: Maximum retry attempts
+            token_refresh_callback: Async callback to refresh token on 401
+        """
+        self._agent_url = agent_url.rstrip('/')
+        self._jwt_token = jwt_token
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._token_refresh_callback = token_refresh_callback
+        
+        # Build headers
+        headers = {}
+        if self._jwt_token:
+            headers['Authorization'] = f'Bearer {self._jwt_token}'
+        
+        # Create reusable async HTTP client with connection pooling
+        self._client = httpx.AsyncClient(
+            timeout=httpx.Timeout(timeout),
+            limits=httpx.Limits(max_connections=10, max_keepalive_connections=5),
+            headers=headers,
+            transport=httpx.AsyncHTTPTransport(
+                local_address="0.0.0.0",  # Force IPv4
+            )
+        )
+        
+        logger.debug(f"Async agent client initialized: {self._agent_url}")
+    
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        await self._client.aclose()
+    
+    def update_jwt_token(self, token: str) -> None:
+        """Update JWT token for agent authentication."""
+        self._jwt_token = token
+        self._client.headers['Authorization'] = f'Bearer {token}'
+    
+    def _should_retry(self, status_code: int) -> bool:
+        """Check if request should be retried."""
+        return status_code in {429, 500, 502, 503, 504}
+    
+    def _get_retry_delay(self, attempt: int) -> float:
+        """Calculate retry delay with exponential backoff."""
+        return min(2 ** attempt, 10)  # Max 10 seconds
+    
+    def _wrap_error(
+        self,
+        error: Exception,
+        operation: str,
+        context: Optional[Dict[str, Any]] = None
+    ) -> AgentError:
+        """Wrap httpx errors into HOPX exceptions."""
+        context = context or {}
+        
+        if isinstance(error, httpx.HTTPStatusError):
+            status_code = error.response.status_code
+            
+            try:
+                error_data = error.response.json()
+                error_code = error_data.get('code', '').upper()
+                error_message = error_data.get('message', str(error))
+            except:
+                error_code = None
+                error_message = str(error)
+            
+            # Map error codes to specific exceptions
+            if error_code == 'FILE_NOT_FOUND':
+                return FileNotFoundError(
+                    error_message,
+                    path=context.get('path'),
+                    code='file_not_found'
+                )
+            elif error_code in ('PATH_NOT_ALLOWED', 'PERMISSION_DENIED'):
+                return FileOperationError(
+                    error_message,
+                    path=context.get('path'),
+                    operation=operation,
+                    code='file_operation_failed'
+                )
+            elif error_code in ('EXECUTION_FAILED', 'EXECUTION_TIMEOUT', 'INVALID_TOKEN'):
+                return CodeExecutionError(
+                    error_message,
+                    exit_code=error_data.get('exit_code'),
+                    code='execution_failed'
+                )
+            elif error_code == 'COMMAND_FAILED':
+                return CommandExecutionError(
+                    error_message,
+                    exit_code=error_data.get('exit_code'),
+                    command=context.get('command'),
+                    code='command_failed'
+                )
+            elif error_code == 'DESKTOP_NOT_AVAILABLE':
+                return DesktopNotAvailableError(
+                    error_message,
+                    missing_dependencies=error_data.get('missing_dependencies', []),
+                    code='desktop_not_available'
+                )
+        
+        elif isinstance(error, httpx.TimeoutException):
+            return HopxTimeoutError(f"{operation} timed out after {self._timeout}s")
+        elif isinstance(error, httpx.NetworkError):
+            return NetworkError(f"{operation} failed: {error}")
+        
+        return AgentError(f"{operation} failed: {error}")
+    
+    async def _request(
+        self,
+        method: str,
+        endpoint: str,
+        operation: str = "request",
+        context: Optional[Dict[str, Any]] = None,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """Make HTTP request with retry logic."""
+        url = f"{self._agent_url}{endpoint}"
+        
+        for attempt in range(self._max_retries):
+            try:
+                response = await self._client.request(method, url, **kwargs)
+                response.raise_for_status()
+                
+                # Handle empty responses (204 No Content)
+                if response.status_code == 204 or not response.content:
+                    return {}
+                
+                if response.headers.get('content-type', '').startswith('application/json'):
+                    return response.json()
+                return {"content": response.content}
+                
+            except httpx.HTTPStatusError as e:
+                # Handle 401 Unauthorized - try to refresh token
+                if e.response.status_code == 401 and self._token_refresh_callback and attempt == 0:
+                    logger.info(f"{operation} got 401 Unauthorized, attempting token refresh...")
+                    try:
+                        # Call async refresh callback to get new token
+                        new_token = await self._token_refresh_callback()
+                        if new_token:
+                            # Update token and retry request
+                            self.update_jwt_token(new_token)
+                            logger.info(f"{operation} token refreshed, retrying request...")
+                            continue
+                    except Exception as refresh_error:
+                        logger.error(f"Token refresh failed: {refresh_error}")
+                        # Fall through to raise original error
+                
+                if not self._should_retry(e.response.status_code) or attempt == self._max_retries - 1:
+                    raise self._wrap_error(e, operation, context)
+                
+                await asyncio.sleep(self._get_retry_delay(attempt))
+                
+            except (httpx.TimeoutException, httpx.NetworkError) as e:
+                if attempt == self._max_retries - 1:
+                    raise self._wrap_error(e, operation, context)
+                
+                await asyncio.sleep(self._get_retry_delay(attempt))
+        
+        raise AgentError(f"{operation} failed after {self._max_retries} retries")
+    
+    async def get(self, endpoint: str, operation: str = "GET request", context: Optional[Dict[str, Any]] = None, **kwargs) -> Dict[str, Any]:
+        """Make GET request."""
+        return await self._request("GET", endpoint, operation=operation, context=context, **kwargs)
+    
+    async def post(self, endpoint: str, operation: str = "POST request", context: Optional[Dict[str, Any]] = None, **kwargs) -> Dict[str, Any]:
+        """Make POST request."""
+        return await self._request("POST", endpoint, operation=operation, context=context, **kwargs)
+    
+    async def put(self, endpoint: str, operation: str = "PUT request", context: Optional[Dict[str, Any]] = None, **kwargs) -> Dict[str, Any]:
+        """Make PUT request."""
+        return await self._request("PUT", endpoint, operation=operation, context=context, **kwargs)
+    
+    async def delete(self, endpoint: str, operation: str = "DELETE request", context: Optional[Dict[str, Any]] = None, **kwargs) -> Dict[str, Any]:
+        """Make DELETE request."""
+        return await self._request("DELETE", endpoint, operation=operation, context=context, **kwargs)
+    
+    async def patch(self, endpoint: str, operation: str = "PATCH request", context: Optional[Dict[str, Any]] = None, **kwargs) -> Dict[str, Any]:
+        """Make PATCH request."""
+        return await self._request("PATCH", endpoint, operation=operation, context=context, **kwargs)

hopx_ai-0.1.16/hopx_ai/_async_cache.py

@@ -0,0 +1,38 @@
+"""Async cache operations for sandboxes."""
+
+from typing import Dict, Any
+import logging
+from ._async_agent_client import AsyncAgentHTTPClient
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncCache:
+    """Async cache operations."""
+    
+    def __init__(self, sandbox):
+        """Initialize with sandbox reference."""
+        self._sandbox = sandbox
+        logger.debug("AsyncCache initialized")
+    
+    async def _get_client(self) -> AsyncAgentHTTPClient:
+        """Get agent client from sandbox."""
+        await self._sandbox._ensure_agent_client()
+        return self._sandbox._agent_client
+    
+    async def stats(self) -> Dict[str, Any]:
+        """Get cache statistics."""
+        client = await self._get_client()
+        response = await client.get(
+            "/cache/stats",
+            operation="get cache stats"
+        )
+        return response
+    
+    async def clear(self) -> None:
+        """Clear cache."""
+        client = await self._get_client()
+        await client.post(
+            "/cache/clear",
+            operation="clear cache"
+        )

{hopx_ai-0.1.10 → hopx_ai-0.1.16}/hopx_ai/_async_client.py

@@ -142,7 +142,7 @@ class AsyncHTTPClient:
             Response JSON data
         
         Raises:
-            BunnyshellError: On API errors
+            HopxError: On API errors
             NetworkError: On network errors
             TimeoutError: On timeout
         """

hopx_ai-0.1.16/hopx_ai/_async_commands.py

@@ -0,0 +1,58 @@
+"""Async command execution for sandboxes."""
+
+from typing import Optional, Dict, Any
+import logging
+from ._async_agent_client import AsyncAgentHTTPClient
+from .models import ExecutionResult
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncCommands:
+    """Async command execution for sandboxes."""
+    
+    def __init__(self, sandbox):
+        """Initialize with sandbox reference."""
+        self._sandbox = sandbox
+        logger.debug("AsyncCommands initialized")
+    
+    async def _get_client(self) -> AsyncAgentHTTPClient:
+        """Get agent client from sandbox."""
+        await self._sandbox._ensure_agent_client()
+        return self._sandbox._agent_client
+    
+    async def run(
+        self,
+        command: str,
+        *,
+        timeout_seconds: int = 60,
+        env: Optional[Dict[str, str]] = None,
+        working_dir: str = "/workspace"
+    ) -> ExecutionResult:
+        """Run shell command."""
+        client = await self._get_client()
+        
+        payload = {
+            "command": command,
+            "timeout": timeout_seconds,
+            "working_dir": working_dir
+        }
+        
+        if env:
+            payload["env"] = env
+        
+        response = await client.post(
+            "/commands/run",
+            json=payload,
+            operation="run command",
+            context={"command": command}
+        )
+        
+        return ExecutionResult(
+            success=response.get("success", True),
+            stdout=response.get("stdout", ""),
+            stderr=response.get("stderr", ""),
+            exit_code=response.get("exit_code", 0),
+            execution_time=response.get("execution_time", 0.0),
+            rich_outputs=[]
+        )

hopx_ai-0.1.16/hopx_ai/_async_env_vars.py

@@ -0,0 +1,151 @@
+"""Async environment variables for sandboxes."""
+
+from typing import Dict, Optional
+import logging
+from ._async_agent_client import AsyncAgentHTTPClient
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncEnvironmentVariables:
+    """
+    Async environment variable operations.
+    
+    Provides methods for managing environment variables inside the sandbox at runtime.
+    
+    Features:
+    - Get all environment variables
+    - Set/replace all environment variables
+    - Update specific environment variables (merge)
+    - Delete individual environment variables
+    """
+    
+    def __init__(self, sandbox):
+        """Initialize with sandbox reference."""
+        self._sandbox = sandbox
+        logger.debug("AsyncEnvironmentVariables initialized")
+    
+    async def _get_client(self) -> AsyncAgentHTTPClient:
+        """Get agent client from sandbox."""
+        await self._sandbox._ensure_agent_client()
+        return self._sandbox._agent_client
+    
+    async def get_all(self, *, timeout: Optional[int] = None) -> Dict[str, str]:
+        """
+        Get all environment variables.
+        
+        Args:
+            timeout: Request timeout in seconds (overrides default)
+        
+        Returns:
+            Dictionary of environment variables
+        """
+        logger.debug("Getting all environment variables")
+        
+        client = await self._get_client()
+        response = await client.get(
+            "/env",
+            operation="get environment variables"
+        )
+        
+        return response.get("env_vars", {})
+    
+    async def set_all(
+        self,
+        env_vars: Dict[str, str],
+        *,
+        timeout: Optional[int] = None
+    ) -> Dict[str, str]:
+        """
+        Set/replace all environment variables.
+        
+        This replaces ALL existing environment variables with the provided ones.
+        Use update() if you want to merge instead.
+        
+        Args:
+            env_vars: Dictionary of environment variables to set
+            timeout: Request timeout in seconds
+        
+        Returns:
+            Updated dictionary of all environment variables
+        """
+        logger.debug(f"Setting {len(env_vars)} environment variables (replace all)")
+        
+        client = await self._get_client()
+        response = await client.put(
+            "/env",
+            json={"env_vars": env_vars},
+            operation="set environment variables"
+        )
+        
+        return response.get("env_vars", env_vars)
+    
+    async def update(
+        self,
+        env_vars: Dict[str, str],
+        *,
+        timeout: Optional[int] = None
+    ) -> Dict[str, str]:
+        """
+        Update specific environment variables (merge).
+        
+        This merges the provided variables with existing ones.
+        Existing variables not specified are preserved.
+        
+        Args:
+            env_vars: Dictionary of environment variables to update/add
+            timeout: Request timeout in seconds
+        
+        Returns:
+            Updated dictionary of all environment variables
+        """
+        logger.debug(f"Updating {len(env_vars)} environment variables (merge)")
+        
+        client = await self._get_client()
+        response = await client.patch(
+            "/env",
+            json={"env_vars": env_vars, "merge": True},  # ✅ FIXED: add merge flag
+            operation="update environment variables"
+        )
+        
+        # Agent returns 204 No Content - get updated vars
+        if not response or not response.get("env_vars"):
+            return await self.get_all()
+        
+        return response.get("env_vars", {})
+    
+    async def delete(self, name: str, *, timeout: Optional[int] = None) -> None:
+        """
+        Delete a specific environment variable.
+        
+        Note: Agent's DELETE /env clears ALL custom variables.
+        We work around this by re-setting all vars except the one to delete.
+        
+        Args:
+            name: Variable name to delete
+            timeout: Request timeout in seconds
+        """
+        logger.debug(f"Deleting environment variable: {name}")
+        
+        # Get all current env vars
+        current_vars = await self.get_all()
+        
+        # Remove the specified variable
+        if name in current_vars:
+            del current_vars[name]
+            # Re-set all env vars without the deleted one
+            await self.set_all(current_vars)
+            logger.debug(f"Environment variable {name} deleted")
+        else:
+            logger.debug(f"Environment variable {name} not found (already deleted)")
+    
+    # Convenience methods (aliases)
+    
+    async def get(self, name: str) -> Optional[str]:
+        """Get a single environment variable value."""
+        all_vars = await self.get_all()
+        return all_vars.get(name)
+    
+    async def set(self, name: str, value: str) -> None:
+        """Set a single environment variable (convenience method)."""
+        await self.update({name: value})