voltagegpu-cli 1.0.0__py3-none-any.whl

volt/sdk/client.py

@@ -0,0 +1,270 @@
+"""VoltageGPU SDK Client - Main API client for VoltageGPU."""
+
+import httpx
+from typing import Any, Dict, List, Optional
+from dataclasses import dataclass
+
+from .config import Config
+
+
+@dataclass
+class Pod:
+    """Represents a GPU pod."""
+    id: str
+    name: str
+    status: str
+    gpu_type: str
+    gpu_count: int
+    hourly_price: float
+    ssh_host: Optional[str] = None
+    ssh_port: Optional[int] = None
+    template_id: Optional[str] = None
+    created_at: Optional[str] = None
+
+
+@dataclass
+class Template:
+    """Represents a pod template."""
+    id: str
+    name: str
+    description: str
+    docker_image: str
+    category: Optional[str] = None
+
+
+@dataclass
+class SSHKey:
+    """Represents an SSH key."""
+    id: str
+    name: str
+    public_key: str
+    fingerprint: Optional[str] = None
+    created_at: Optional[str] = None
+
+
+@dataclass
+class Machine:
+    """Represents an available GPU machine type."""
+    name: str
+    hourly_price: float
+    total_gpu_count: int
+    available: bool
+
+
+def _as_list(data):
+    """Normalize API response to a list."""
+    if isinstance(data, list):
+        return data
+    if isinstance(data, dict):
+        # Try common wrapper keys
+        for key in ("pods", "templates", "machines", "sshKeys", "keys", "data"):
+            if key in data:
+                return data[key]
+        return [data]
+    return []
+
+
+class VoltageGPUClient:
+    """Main client for interacting with VoltageGPU API."""
+
+    def __init__(self, config: Optional[Config] = None):
+        """Initialize the client with optional config."""
+        self.config = config or Config.load()
+        self._client = httpx.Client(
+            base_url=self.config.base_url,
+            headers={
+                "X-API-Key": self.config.api_key,
+                "Content-Type": "application/json",
+                "User-Agent": "VoltageGPU-CLI/1.0.0"
+            },
+            timeout=30.0
+        )
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self._client.close()
+
+    def close(self):
+        """Close the HTTP client."""
+        self._client.close()
+
+    # ==================== PODS ====================
+
+    def list_pods(self) -> List[Pod]:
+        """List all pods for the current user."""
+        response = self._client.get("/volt/pods")
+        response.raise_for_status()
+        return [self._parse_pod(p) for p in _as_list(response.json())]
+
+    def get_pod(self, pod_id: str) -> Pod:
+        """Get details of a specific pod."""
+        response = self._client.get(f"/volt/pods/{pod_id}")
+        response.raise_for_status()
+        return self._parse_pod(response.json())
+
+    def create_pod(
+        self,
+        template_id: str,
+        name: str,
+        gpu_count: int = 1,
+        ssh_key_ids: Optional[List[str]] = None,
+        docker_credentials_id: Optional[str] = None,
+        env_vars: Optional[Dict[str, str]] = None
+    ) -> Pod:
+        """Create a new pod from a template."""
+        payload = {
+            "templateId": template_id,
+            "name": name,
+            "gpuCount": gpu_count,
+        }
+        if ssh_key_ids:
+            payload["sshKeyIds"] = ssh_key_ids
+        if docker_credentials_id:
+            payload["dockerCredentialsId"] = docker_credentials_id
+        if env_vars:
+            payload["envVars"] = env_vars
+
+        response = self._client.post("/volt/pods", json=payload)
+        response.raise_for_status()
+        return self._parse_pod(response.json())
+
+    def start_pod(self, pod_id: str) -> Pod:
+        """Start a stopped pod."""
+        response = self._client.post(f"/volt/pods/{pod_id}/start")
+        response.raise_for_status()
+        return self._parse_pod(response.json())
+
+    def stop_pod(self, pod_id: str) -> Pod:
+        """Stop a running pod."""
+        response = self._client.post(f"/volt/pods/{pod_id}/stop")
+        response.raise_for_status()
+        return self._parse_pod(response.json())
+
+    def delete_pod(self, pod_id: str) -> bool:
+        """Delete a pod."""
+        response = self._client.delete(f"/volt/pods/{pod_id}")
+        response.raise_for_status()
+        return True
+
+    def _parse_pod(self, data: Dict[str, Any]) -> Pod:
+        """Parse pod data from API response."""
+        # Handle both camelCase and snake_case fields from Lium API
+        executor = data.get("executor", {}) or {}
+        gpu_details = executor.get("specs", {}).get("gpu", {}).get("details", [])
+        gpu_name = gpu_details[0].get("name", "") if gpu_details else ""
+        gpu_count = executor.get("specs", {}).get("gpu", {}).get("count", 1) if executor else 1
+
+        return Pod(
+            id=data.get("id", data.get("uuid", data.get("podId", ""))),
+            name=data.get("name", ""),
+            status=data.get("status", "unknown"),
+            gpu_type=data.get("gpuType", data.get("gpu_type", gpu_name)),
+            gpu_count=data.get("gpuCount", data.get("gpu_count", gpu_count)),
+            hourly_price=float(data.get("hourlyPrice", data.get("price_per_hour",
+                               data.get("hourly_price", 0)))),
+            ssh_host=data.get("sshHost", data.get("ssh_host")),
+            ssh_port=data.get("sshPort", data.get("ssh_port")),
+            template_id=data.get("templateId", data.get("template_id",
+                                  data.get("template", {}).get("id") if isinstance(data.get("template"), dict) else None)),
+            created_at=data.get("createdAt", data.get("created_at"))
+        )
+
+    # ==================== TEMPLATES ====================
+
+    def list_templates(self, category: Optional[str] = None) -> List[Template]:
+        """List available templates."""
+        params = {}
+        if category:
+            params["category"] = category
+        response = self._client.get("/volt/templates", params=params)
+        response.raise_for_status()
+        return [self._parse_template(t) for t in _as_list(response.json())]
+
+    def get_template(self, template_id: str) -> Template:
+        """Get details of a specific template."""
+        response = self._client.get(f"/volt/templates/{template_id}")
+        response.raise_for_status()
+        return self._parse_template(response.json())
+
+    def _parse_template(self, data: Dict[str, Any]) -> Template:
+        """Parse template data from API response."""
+        return Template(
+            id=data.get("id", data.get("templateId", "")),
+            name=data.get("name", ""),
+            description=data.get("description", ""),
+            docker_image=data.get("docker_image", data.get("dockerImage", "")),
+            category=data.get("category")
+        )
+
+    # ==================== SSH KEYS ====================
+
+    def list_ssh_keys(self) -> List[SSHKey]:
+        """List all SSH keys for the current user."""
+        response = self._client.get("/volt/ssh-keys")
+        response.raise_for_status()
+        return [self._parse_ssh_key(k) for k in _as_list(response.json())]
+
+    def add_ssh_key(self, name: str, public_key: str) -> SSHKey:
+        """Add a new SSH key."""
+        response = self._client.post("/volt/ssh-keys", json={
+            "name": name,
+            "publicKey": public_key
+        })
+        response.raise_for_status()
+        return self._parse_ssh_key(response.json())
+
+    def delete_ssh_key(self, key_id: str) -> bool:
+        """Delete an SSH key."""
+        response = self._client.delete(f"/volt/ssh-keys/{key_id}")
+        response.raise_for_status()
+        return True
+
+    def _parse_ssh_key(self, data: Dict[str, Any]) -> SSHKey:
+        """Parse SSH key data from API response."""
+        return SSHKey(
+            id=data.get("id", data.get("keyId", "")),
+            name=data.get("name", ""),
+            public_key=data.get("publicKey", data.get("public_key", "")),
+            fingerprint=data.get("fingerprint"),
+            created_at=data.get("createdAt", data.get("created_at"))
+        )
+
+    # ==================== MACHINES ====================
+
+    def list_machines(self, gpu_type: Optional[str] = None) -> List[Machine]:
+        """List available machines."""
+        response = self._client.get("/volt/machines")
+        response.raise_for_status()
+        machines = []
+        for m in _as_list(response.json()):
+            name = m.get("name", "")
+            # Flexible match: "RTX4090" matches "NVIDIA GeForce RTX 4090"
+            if gpu_type and gpu_type.lower().replace(" ", "") not in name.lower().replace(" ", ""):
+                continue
+            machines.append(Machine(
+                name=name,
+                hourly_price=float(m.get("price", 0)),
+                total_gpu_count=int(m.get("total_gpu_count", 0)),
+                available=int(m.get("total_gpu_count", 0)) > 0
+            ))
+        return machines
+
+    # ==================== ACCOUNT ====================
+
+    def get_balance(self) -> float:
+        """Get current account balance."""
+        response = self._client.get("/user/balance")
+        response.raise_for_status()
+        data = response.json()
+        return float(data.get("balance", 0))
+
+    def get_account_info(self) -> Dict[str, Any]:
+        """Get account information."""
+        response = self._client.get("/account")
+        response.raise_for_status()
+        return response.json()
+
+
+__all__ = ["VoltageGPUClient", "Pod", "Template", "SSHKey", "Machine"]

volt/sdk/config.py

@@ -0,0 +1,62 @@
+"""Configuration loading for the VoltageGPU SDK."""
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+
+@dataclass
+class Config:
+    api_key: str
+    base_url: str = "https://voltagegpu.com/api"
+    base_pay_url: str = "https://pay-api.celiumcompute.ai"
+    ssh_key_path: Optional[Path] = None
+
+    @classmethod
+    def load(cls) -> "Config":
+        """Load config from env/file with smart defaults."""
+        # Support both VOLT_API_KEY and legacy LIUM_API_KEY for compatibility
+        api_key = os.getenv("VOLT_API_KEY") or os.getenv("LIUM_API_KEY")
+        if not api_key:
+            from configparser import ConfigParser
+            # Check VoltageGPU config first, then fallback to legacy
+            config_file = Path.home() / ".volt" / "config.ini"
+            if not config_file.exists():
+                config_file = Path.home() / ".lium" / "config.ini"
+            if config_file.exists():
+                config = ConfigParser()
+                config.read(config_file)
+                api_key = config.get("api", "api_key", fallback=None)
+
+        if not api_key:
+            raise ValueError("No API key found. Set VOLT_API_KEY or ~/.volt/config.ini")
+
+        # Find SSH key with fallback
+        ssh_key = None
+        for key_name in ["id_ed25519", "id_rsa", "id_ecdsa"]:
+            key_path = Path.home() / ".ssh" / key_name
+            if key_path.exists():
+                ssh_key = key_path
+                break
+
+        return cls(
+            api_key=api_key,
+            base_url=os.getenv("VOLT_BASE_URL", os.getenv("LIUM_BASE_URL", "https://voltagegpu.com/api")),
+            base_pay_url=os.getenv("VOLT_PAY_URL", os.getenv("LIUM_PAY_URL", "https://pay-api.celiumcompute.ai")),
+            ssh_key_path=ssh_key
+        )
+
+    @property
+    def ssh_public_keys(self) -> List[str]:
+        """Get SSH public keys."""
+        if not self.ssh_key_path:
+            return []
+        pub_path = self.ssh_key_path.with_suffix('.pub')
+        if pub_path.exists():
+            with open(pub_path) as f:
+                return [line.strip() for line in f if line.strip().startswith(('ssh-', 'ecdsa-'))]
+        return []
+
+
+__all__ = ["Config"]

volt/sdk/decorators.py

@@ -0,0 +1,200 @@
+"""Higher-level decorators built on top of the Lium SDK."""
+
+import inspect
+import json
+import os
+import random
+import shlex
+import tempfile
+import time
+from functools import wraps
+from typing import Optional, Sequence
+
+from .client import Lium
+from .exceptions import LiumError
+
+
+def machine(
+    machine: str,
+    template_id: Optional[str] = None,
+    cleanup: bool = True,
+    requirements: Optional[Sequence[str]] = None,
+):
+    """Decorator to execute a function on a remote Lium machine.
+
+    Creates a new pod, sends function source code and executes it remotely,
+    returns the result, and optionally cleans up the pod.
+
+    Args:
+        machine: Machine type (e.g., "1xH200", "1xA100")
+        template_id: Docker template ID (optional, uses default if not specified)
+        cleanup: Whether to delete the pod after execution (default: True)
+        requirements: Optional iterable of pip-installable packages to install on the pod
+    """
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # Initialize SDK
+            sdk = Lium()
+            pod_info = None
+
+            try:
+                # Step 1: Find executor matching machine type
+                executors = sdk.ls()
+                matching_executor = None
+                for executor in executors:
+                    if machine.lower() in executor.machine_name.lower():
+                        matching_executor = executor
+                        break
+
+                if not matching_executor:
+                    raise LiumError(f"No executor found matching machine type: {machine}")
+
+                # Step 2: Create pod
+                pod_name = f"remote-{func.__name__}-{int(time.time())}"
+
+                template = sdk.default_docker_template(matching_executor.id)
+
+                pod_dict = sdk.up(
+                    executor_id=matching_executor.id,
+                    name=pod_name,
+                    template_id=template.id if template else None,
+                )
+
+                # Wait for pod to be ready
+                max_wait = 300
+                pod_info = sdk.wait_ready(pod_dict, timeout=max_wait)
+                if not pod_info:
+                    raise LiumError(f"Pod {pod_name} failed to start within {max_wait}s")
+
+                # Step 3: Extract function source code without decorators
+                func_source = inspect.getsource(func)
+                func_name = func.__name__
+
+                # Strip decorator lines - find the 'def' line and keep from there
+                lines = func_source.split('\n')
+                def_index = next(i for i, line in enumerate(lines) if 'def ' in line)
+                func_source = '\n'.join(lines[def_index:])
+
+                # Step 4: Create runner script with function source and arguments
+                runner_script = f'''#!/usr/bin/env python3
+import sys
+import traceback
+import json
+
+# Function source code
+{func_source}
+
+try:
+    # Arguments
+    args = {repr(args)}
+    kwargs = {repr(kwargs)}
+
+    # Execute function
+    result = {func_name}(*args, **kwargs)
+
+    # Save result as JSON
+    with open('/tmp/result.json', 'w') as f:
+        json.dump({{'success': True, 'result': result}}, f)
+
+except Exception as e:
+    # Save error
+    with open('/tmp/result.json', 'w') as f:
+        json.dump({{
+            'success': False,
+            'error': str(e),
+            'traceback': traceback.format_exc()
+        }}, f)
+    sys.exit(1)
+'''
+
+                # Write runner script to temp file
+                with tempfile.NamedTemporaryFile(mode='w', suffix='.py', delete=False) as f:
+                    runner_file = f.name
+                    f.write(runner_script)
+
+                try:
+                    # Step 5: Upload runner script
+                    sdk.upload(pod_info, local=runner_file, remote='/tmp/runner.py')
+
+                    # Step 6: Create isolated virtual environment
+                    venv_path = f"/tmp/lium_venv_{int(time.time())}_{random.randint(1000,9999)}"
+                    venv_python = f"{venv_path}/bin/python"
+                    venv_cmd = f"python3 -m venv {shlex.quote(venv_path)}"
+                    venv_result = sdk.exec(pod_info, command=venv_cmd)
+                    if not venv_result['success']:
+                        raise LiumError(f"Failed to create virtual environment:\n{venv_result['stderr']}")
+
+                    # Step 7: Install requirements if requested
+                    reqs = [req for req in (requirements or []) if req]
+                    if reqs:
+                        packages = " ".join(shlex.quote(req) for req in reqs)
+                        install_cmd = f"{shlex.quote(venv_python)} -m pip install {packages}"
+                        install_result = sdk.exec(pod_info, command=install_cmd)
+                        if not install_result['success']:
+                            raise LiumError(
+                                "Failed installing requirements "
+                                f"({', '.join(reqs)}):\n{install_result['stderr']}"
+                            )
+
+                    # Step 8: Execute runner via virtual environment python
+                    exec_result = sdk.exec(
+                        pod_info,
+                        command=f"{shlex.quote(venv_python)} /tmp/runner.py"
+                    )
+
+                    # Step 9: Download result (even when execution failed to capture error details)
+                    result_data = None
+                    result_file = None
+                    try:
+                        with tempfile.NamedTemporaryFile(mode='w', delete=False) as f:
+                            result_file = f.name
+                        sdk.download(pod_info, remote='/tmp/result.json', local=result_file)
+                        with open(result_file, 'r') as f:
+                            result_data = json.load(f)
+                    except Exception:
+                        result_data = None
+                    finally:
+                        if result_file and os.path.exists(result_file):
+                            os.unlink(result_file)
+
+                    if result_data and result_data.get('success'):
+                        return result_data['result']
+
+                    # Construct detailed error message
+                    if result_data and not result_data.get('success', True):
+                        err_msg = result_data.get('error', 'Unknown remote error')
+                        tb = result_data.get('traceback')
+                        if tb:
+                            err_msg = f"{err_msg}\n\nTraceback:\n{tb}"
+                        raise LiumError(f"Remote execution failed:\n{err_msg}")
+
+                    stderr = exec_result.get('stderr') or exec_result.get('stdout') or 'Unknown remote error'
+                    raise LiumError(f"Remote execution failed:\n{stderr}")
+
+                finally:
+                    # Clean up local temp file
+                    os.unlink(runner_file)
+
+            finally:
+                # Remove virtual environment directory best-effort when pod stays alive
+                if pod_info and 'venv_path' in locals():
+                    try:
+                        sdk.exec(pod_info, command=f"rm -rf {shlex.quote(venv_path)}")
+                    except Exception:
+                        pass
+
+                # Step 10: Cleanup pod
+                if cleanup and pod_info:
+                    try:
+                        sdk.down(pod_info)
+                    except Exception:
+                        pass  # Best effort cleanup
+
+        return wrapper
+
+    return decorator
+
+
+__all__ = ["machine"]

volt/sdk/exceptions.py

@@ -0,0 +1,29 @@
+"""Exception hierarchy for the Lium SDK."""
+
+class LiumError(Exception):
+    """Base exception for Lium SDK."""
+
+
+class LiumAuthError(LiumError):
+    """Authentication error."""
+
+
+class LiumRateLimitError(LiumError):
+    """Rate limit exceeded."""
+
+
+class LiumServerError(LiumError):
+    """Server error."""
+
+
+class LiumNotFoundError(LiumError):
+    """Resource not found (404)."""
+
+
+__all__ = [
+    "LiumError",
+    "LiumAuthError",
+    "LiumRateLimitError",
+    "LiumServerError",
+    "LiumNotFoundError",
+]

volt/sdk/models.py

@@ -0,0 +1,132 @@
+"""Datamodels used across the Lium SDK."""
+
+from dataclasses import dataclass
+import re
+from typing import Dict, List, Optional
+
+
+@dataclass
+class ExecutorInfo:
+    id: str
+    huid: str
+    machine_name: str
+    gpu_type: str
+    gpu_count: int
+    price_per_hour: float
+    price_per_gpu_hour: float
+    location: Dict
+    specs: Dict
+    status: str
+    docker_in_docker: bool
+    ip: str
+    available_port_count: Optional[int] = None
+
+    @property
+    def driver_version(self) -> str:
+        """Extract GPU driver version from specs."""
+        return self.specs.get('gpu', {}).get('driver', '')
+
+    @property
+    def gpu_model(self) -> str:
+        """Extract GPU model name from specs."""
+        gpu_details = self.specs.get('gpu', {}).get('details', [])
+        return gpu_details[0].get('name', '') if gpu_details else ''
+
+
+@dataclass
+class PodInfo:
+    id: str
+    name: str
+    status: str
+    huid: str
+    ssh_cmd: Optional[str]
+    ports: Dict
+    created_at: str
+    updated_at: str
+    executor: Optional[ExecutorInfo]
+    template: Dict
+    removal_scheduled_at: Optional[str]
+    jupyter_installation_status: Optional[str]
+    jupyter_url: Optional[str]
+
+    @property
+    def host(self) -> Optional[str]:
+        return (re.findall(r'@(\S+)', self.ssh_cmd) or [None])[0] if self.ssh_cmd else None
+
+    @property
+    def username(self) -> Optional[str]:
+        return (re.findall(r'ssh (\S+)@', self.ssh_cmd) or [None])[0] if self.ssh_cmd else None
+
+    @property
+    def ssh_port(self) -> int:
+        """Extract SSH port from command."""
+        if not self.ssh_cmd or '-p ' not in self.ssh_cmd:
+            return 22
+        return int(self.ssh_cmd.split('-p ')[1].split()[0])
+
+
+@dataclass
+class Template:
+    """Template information."""
+    id: str
+    name: str
+    huid: str
+    docker_image: str
+    docker_image_tag: str
+    category: str
+    status: str
+
+
+@dataclass
+class BackupConfig:
+    """Backup configuration information."""
+    id: str
+    huid: str
+    pod_executor_id: str
+    backup_frequency_hours: int
+    retention_days: int
+    backup_path: str
+    is_active: bool
+    created_at: str
+    updated_at: Optional[str] = None
+
+
+@dataclass
+class BackupLog:
+    """Backup log information."""
+    id: str
+    huid: str
+    backup_config_id: str
+    status: str
+    started_at: str
+    completed_at: Optional[str] = None
+    error_message: Optional[str] = None
+    progress: Optional[float] = None
+    backup_volume_id: Optional[str] = None
+    created_at: Optional[str] = None
+
+
+@dataclass
+class VolumeInfo:
+    """Volume information."""
+    id: str
+    huid: str
+    name: str
+    description: str
+    created_at: str
+    updated_at: Optional[str] = None
+    current_size_bytes: int = 0
+    current_file_count: int = 0
+    current_size_gb: float = 0.0
+    current_size_mb: float = 0.0
+    last_metrics_update: Optional[str] = None
+
+
+__all__ = [
+    "ExecutorInfo",
+    "PodInfo",
+    "Template",
+    "BackupConfig",
+    "BackupLog",
+    "VolumeInfo",
+]