hopx-ai 0.1.17__py3-none-any.whl

hopx_ai/template/types.py

@@ -0,0 +1,199 @@
+"""
+Template Building Types
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import List, Dict, Optional, Callable, Any
+from datetime import datetime
+
+
+class StepType(str, Enum):
+    """Step types for template building"""
+    FROM = "FROM"
+    COPY = "COPY"
+    RUN = "RUN"
+    ENV = "ENV"
+    WORKDIR = "WORKDIR"
+    USER = "USER"
+    CMD = "CMD"
+
+
+@dataclass
+class RegistryAuth:
+    """Basic registry authentication"""
+    username: str
+    password: str
+
+
+@dataclass
+class GCPRegistryAuth:
+    """GCP Container Registry authentication"""
+    service_account_json: Any  # str (file path) or dict
+
+
+@dataclass
+class AWSRegistryAuth:
+    """AWS ECR authentication"""
+    access_key_id: str
+    secret_access_key: str
+    region: str
+    session_token: Optional[str] = None
+
+
+@dataclass
+class Step:
+    """Represents a build step"""
+    type: StepType
+    args: List[str]
+    files_hash: Optional[str] = None
+    skip_cache: bool = False
+    registry_auth: Optional[RegistryAuth] = None
+    gcp_auth: Optional[GCPRegistryAuth] = None
+    aws_auth: Optional[AWSRegistryAuth] = None
+
+
+@dataclass
+class CopyOptions:
+    """Options for COPY steps"""
+    owner: Optional[str] = None
+    permissions: Optional[str] = None
+
+
+class ReadyCheckType(str, Enum):
+    """Types of ready checks"""
+    PORT = "port"
+    URL = "url"
+    FILE = "file"
+    PROCESS = "process"
+    COMMAND = "command"
+
+
+@dataclass
+class ReadyCheck:
+    """Ready check configuration"""
+    type: ReadyCheckType
+    port: Optional[int] = None
+    url: Optional[str] = None
+    path: Optional[str] = None
+    process_name: Optional[str] = None
+    command: Optional[str] = None
+    timeout: int = 30000
+    interval: int = 2000
+
+
+@dataclass
+class BuildOptions:
+    """Options for building a template"""
+    alias: str
+    api_key: str
+    base_url: str = "https://api.your-domain.com"
+    cpu: int = 2
+    memory: int = 2048
+    disk_gb: int = 10
+    skip_cache: bool = False
+    context_path: Optional[str] = None
+    on_log: Optional[Callable[[Dict[str, Any]], None]] = None
+    on_progress: Optional[Callable[[int], None]] = None
+
+
+@dataclass
+class LogEntry:
+    """Log entry from build"""
+    timestamp: str
+    level: str
+    message: str
+
+
+@dataclass
+class StatusUpdate:
+    """Status update from build"""
+    status: str
+    progress: int
+    current_step: Optional[str] = None
+
+
+@dataclass
+class CreateVMOptions:
+    """Options for creating a VM from template"""
+    alias: Optional[str] = None
+    cpu: Optional[int] = None
+    memory: Optional[int] = None
+    disk_gb: Optional[int] = None
+    env_vars: Optional[Dict[str, str]] = None
+
+
+@dataclass
+class VM:
+    """Represents a VM instance"""
+    vm_id: str
+    template_id: str
+    status: str
+    ip: str
+    agent_url: str
+    started_at: str
+    _delete_func: Optional[Callable[[], None]] = None
+    
+    async def delete(self):
+        """Delete this VM"""
+        if self._delete_func:
+            await self._delete_func()
+
+
+@dataclass
+class BuildResult:
+    """Result of a template build"""
+    build_id: str
+    template_id: str
+    duration: int
+    _create_vm_func: Optional[Callable[[CreateVMOptions], Any]] = None
+    
+    async def create_vm(self, options: CreateVMOptions = None) -> VM:
+        """Create a VM from this template"""
+        if self._create_vm_func:
+            return await self._create_vm_func(options or CreateVMOptions())
+        raise RuntimeError("create_vm function not available")
+
+
+@dataclass
+class UploadLinkResponse:
+    """Response from upload link request"""
+    present: bool
+    upload_url: Optional[str] = None
+    expires_at: Optional[str] = None
+    request_id: Optional[str] = None
+
+
+@dataclass
+class BuildResponse:
+    """Response from build trigger"""
+    build_id: str
+    template_id: str
+    status: str
+    logs_url: str
+    request_id: Optional[str] = None
+
+
+@dataclass
+class BuildStatusResponse:
+    """Response from build status check"""
+    build_id: str
+    template_id: str
+    status: str
+    progress: int
+    started_at: str
+    current_step: Optional[str] = None
+    estimated_completion: Optional[str] = None
+    error: Optional[str] = None
+    request_id: Optional[str] = None
+
+
+@dataclass
+class LogsResponse:
+    """Response from build logs polling"""
+    logs: str
+    offset: int
+    status: str
+    complete: bool
+    request_id: Optional[str] = None
+

hopx_ai/terminal.py

@@ -0,0 +1,164 @@
+"""Interactive terminal access via WebSocket."""
+
+import logging
+from typing import Optional, AsyncIterator, Dict, Any
+
+try:
+    from websockets.client import WebSocketClientProtocol
+    WEBSOCKETS_AVAILABLE = True
+except ImportError:
+    WEBSOCKETS_AVAILABLE = False
+    WebSocketClientProtocol = Any  # type: ignore
+
+from ._ws_client import WebSocketClient
+
+logger = logging.getLogger(__name__)
+
+
+class Terminal:
+    """
+    Interactive terminal resource with PTY support via WebSocket.
+    
+    Provides real-time terminal access to the sandbox for interactive commands.
+    
+    Features:
+    - Full PTY support
+    - Real-time output streaming
+    - Terminal resize support
+    - Process exit notifications
+    
+    Example:
+        >>> import asyncio
+        >>> 
+        >>> async def interactive_terminal():
+        ...     sandbox = Sandbox.create(template="code-interpreter")
+        ...     
+        ...     # Connect to terminal
+        ...     async with await sandbox.terminal.connect() as ws:
+        ...         # Send command
+        ...         await sandbox.terminal.send_input(ws, "ls -la\\n")
+        ...         
+        ...         # Receive output
+        ...         async for message in sandbox.terminal.iter_output(ws):
+        ...             if message['type'] == 'output':
+        ...                 print(message['data'], end='')
+        ...             elif message['type'] == 'exit':
+        ...                 print(f"\\nProcess exited: {message['code']}")
+        ...                 break
+        >>> 
+        >>> asyncio.run(interactive_terminal())
+    """
+    
+    def __init__(self, ws_client: WebSocketClient):
+        """
+        Initialize Terminal resource.
+        
+        Args:
+            ws_client: WebSocket client
+        """
+        if not WEBSOCKETS_AVAILABLE:
+            raise ImportError(
+                "websockets library is required for terminal features. "
+                "Install with: pip install websockets"
+            )
+        
+        self._ws_client = ws_client
+        logger.debug("Terminal resource initialized")
+    
+    async def connect(
+        self,
+        *,
+        timeout: Optional[int] = 30
+    ) -> WebSocketClientProtocol:
+        """
+        Connect to interactive terminal.
+        
+        Args:
+            timeout: Connection timeout in seconds
+        
+        Returns:
+            WebSocket connection (use with async context manager)
+        
+        Example:
+            >>> async with await sandbox.terminal.connect() as ws:
+            ...     await sandbox.terminal.send_input(ws, "echo 'Hello'\\n")
+            ...     async for msg in sandbox.terminal.iter_output(ws):
+            ...         print(msg['data'], end='')
+            ...         if msg['type'] == 'exit':
+            ...             break
+        """
+        return await self._ws_client.connect("/terminal", timeout=timeout)
+    
+    async def send_input(
+        self,
+        ws: WebSocketClientProtocol,
+        data: str
+    ) -> None:
+        """
+        Send input to terminal.
+        
+        Args:
+            ws: WebSocket connection
+            data: Input data (include \\n for commands)
+        
+        Example:
+            >>> await terminal.send_input(ws, "ls -la\\n")
+            >>> await terminal.send_input(ws, "cd /workspace\\n")
+        """
+        await self._ws_client.send_message(ws, {
+            "type": "input",
+            "data": data
+        })
+    
+    async def resize(
+        self,
+        ws: WebSocketClientProtocol,
+        cols: int,
+        rows: int
+    ) -> None:
+        """
+        Resize terminal window.
+        
+        Args:
+            ws: WebSocket connection
+            cols: Number of columns
+            rows: Number of rows
+        
+        Example:
+            >>> await terminal.resize(ws, cols=120, rows=40)
+        """
+        await self._ws_client.send_message(ws, {
+            "type": "resize",
+            "cols": cols,
+            "rows": rows
+        })
+    
+    async def iter_output(
+        self,
+        ws: WebSocketClientProtocol
+    ) -> AsyncIterator[Dict[str, Any]]:
+        """
+        Iterate over terminal output messages.
+        
+        Args:
+            ws: WebSocket connection
+        
+        Yields:
+            Message dictionaries:
+            - {"type": "output", "data": "..."}
+            - {"type": "exit", "code": 0}
+        
+        Example:
+            >>> async for message in terminal.iter_output(ws):
+            ...     if message['type'] == 'output':
+            ...         print(message['data'], end='')
+            ...     elif message['type'] == 'exit':
+            ...         print(f"Exit code: {message['code']}")
+            ...         break
+        """
+        async for message in self._ws_client.iter_messages(ws):
+            yield message
+    
+    def __repr__(self) -> str:
+        return f"<Terminal ws_client={self._ws_client}>"
+