clouditia 1.0.0__py3-none-any.whl

clouditia/__init__.py

@@ -0,0 +1,57 @@
+"""
+Clouditia SDK - Execute Python and Shell code on remote GPU sessions.
+
+This SDK provides a simple interface to interact with Clouditia GPU sessions,
+allowing you to run Python code, shell commands, and long-running async jobs
+on remote GPU-powered containers.
+
+Basic Usage:
+    >>> from clouditia import GPUSession
+    >>> session = GPUSession("your_api_key")
+    >>> result = session.run("print('Hello from GPU!')")
+    >>> print(result.output)
+    Hello from GPU!
+
+For more examples, see: https://clouditia.com/docs
+"""
+
+__version__ = "1.0.0"
+__author__ = "Clouditia Team"
+__email__ = "support@clouditia.com"
+
+from .client import GPUSession, connect
+from .jobs import AsyncJob
+from .results import ExecutionResult
+from .exceptions import (
+    ClouditiaError,
+    AuthenticationError,
+    SessionError,
+    ExecutionError,
+    TimeoutError,
+    CommandBlockedError
+)
+
+# Jupyter magic loader
+def load_ipython_extension(ipython):
+    """Load the Clouditia Jupyter magic extension."""
+    from .magic import load_ipython_extension as load_magic
+    load_magic(ipython)
+
+__all__ = [
+    # Main classes
+    "GPUSession",
+    "AsyncJob",
+    "ExecutionResult",
+    # Convenience functions
+    "connect",
+    "load_ipython_extension",
+    # Exceptions
+    "ClouditiaError",
+    "AuthenticationError",
+    "SessionError",
+    "ExecutionError",
+    "TimeoutError",
+    "CommandBlockedError",
+    # Version info
+    "__version__",
+]

clouditia/client.py

@@ -0,0 +1,656 @@
+"""
+Clouditia SDK - Main Client
+
+This module provides the GPUSession class for interacting with remote GPU sessions.
+"""
+
+import base64
+import inspect
+import json
+import pickle
+import textwrap
+from functools import wraps
+from typing import Any, Callable, Dict, List, Optional
+
+import requests
+
+from .exceptions import (
+    AuthenticationError,
+    ClouditiaError,
+    CommandBlockedError,
+    ExecutionError,
+    SessionError,
+    TimeoutError,
+)
+from .jobs import AsyncJob
+from .results import ExecutionResult
+
+
+class GPUSession:
+    """
+    Main class for interacting with a Clouditia GPU session.
+
+    A GPUSession represents a connection to a remote GPU-powered container.
+    You can execute Python code, run shell commands, and manage long-running
+    async jobs through this interface.
+
+    Attributes:
+        api_key (str): Your Clouditia API key
+        base_url (str): Base URL of the Clouditia API
+        timeout (int): Default timeout for synchronous operations (seconds)
+        poll_interval (int): Interval for polling async jobs (seconds)
+
+    Example:
+        >>> from clouditia import GPUSession
+        >>>
+        >>> # Create a session
+        >>> session = GPUSession("ck_your_api_key_here")
+        >>>
+        >>> # Execute Python code
+        >>> result = session.run("print('Hello from GPU!')")
+        >>> print(result.output)
+        Hello from GPU!
+        >>>
+        >>> # Execute shell commands
+        >>> result = session.shell("ls -la")
+        >>> print(result.output)
+        >>>
+        >>> # Submit long-running jobs
+        >>> job = session.submit("train_model()", name="training")
+        >>> job.wait(show_logs=True)
+    """
+
+    DEFAULT_BASE_URL = "https://clouditia.com/code-editor"
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: Optional[str] = None,
+        timeout: int = 120,
+        poll_interval: int = 5
+    ):
+        """
+        Initialize a GPU session.
+
+        Args:
+            api_key: Your Clouditia API key (starts with 'ck_' or 'sk_')
+            base_url: Base URL of the API (default: https://clouditia.com/code-editor)
+            timeout: Default timeout for synchronous operations in seconds
+            poll_interval: Interval for polling async job status in seconds
+
+        Example:
+            >>> session = GPUSession("ck_abc123...")
+            >>> session = GPUSession("ck_abc123...", timeout=300)
+        """
+        if not api_key:
+            raise AuthenticationError("API key is required")
+
+        self.api_key = api_key
+        self.base_url = (base_url or self.DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.poll_interval = poll_interval
+        self._session_info: Optional[Dict] = None
+        self._remote_vars: Dict[str, bool] = {}
+
+    def _headers(self) -> Dict[str, str]:
+        """Get headers with authentication."""
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json"
+        }
+
+    def _check_response(self, response: requests.Response) -> Dict:
+        """Check response and raise appropriate exceptions."""
+        try:
+            data = response.json()
+        except json.JSONDecodeError:
+            raise ClouditiaError(f"Invalid JSON response: {response.text[:200]}")
+
+        if response.status_code == 401:
+            raise AuthenticationError(data.get("error", "Invalid API key"))
+        elif response.status_code == 403:
+            error_msg = data.get("error", "Access forbidden")
+            if "blocked" in error_msg.lower() or "blacklist" in error_msg.lower():
+                raise CommandBlockedError(error_msg)
+            raise SessionError(error_msg)
+        elif response.status_code == 404:
+            raise SessionError(data.get("error", "Resource not found"))
+        elif response.status_code >= 400:
+            raise ClouditiaError(data.get("error", f"HTTP {response.status_code}"))
+
+        if not data.get("success", True):
+            error = data.get("error", "Unknown error")
+            if "timeout" in error.lower():
+                raise TimeoutError(error)
+            if "blocked" in error.lower():
+                raise CommandBlockedError(error)
+            raise ExecutionError(error)
+
+        return data
+
+    def verify(self) -> Dict:
+        """
+        Verify the API key and get session information.
+
+        Returns:
+            Dict containing session_id, gpu_type, status, URLs, and billing info.
+
+        Raises:
+            AuthenticationError: If API key is invalid
+            SessionError: If session is not active
+
+        Example:
+            >>> info = session.verify()
+            >>> print(f"GPU: {info['gpu_type']}")
+            >>> print(f"Credit: {info['user_credit']}€")
+        """
+        response = requests.get(
+            f"{self.base_url}/api/verify/",
+            headers=self._headers(),
+            timeout=30
+        )
+        data = self._check_response(response)
+        self._session_info = data
+        return data
+
+    def run(self, code: str, timeout: Optional[int] = None) -> ExecutionResult:
+        """
+        Execute Python code on the remote GPU.
+
+        This is a synchronous call - it waits for the code to complete
+        and returns the result. For long-running code, use submit() instead.
+
+        Args:
+            code: Python code to execute
+            timeout: Timeout in seconds (default: self.timeout)
+
+        Returns:
+            ExecutionResult with output, result, and status.
+
+        Raises:
+            ExecutionError: If code execution fails
+            TimeoutError: If execution times out
+
+        Example:
+            >>> # Simple execution
+            >>> result = session.run("print('Hello!')")
+            >>> print(result.output)  # "Hello!"
+
+            >>> # Get return value
+            >>> result = session.run("2 + 2")
+            >>> print(result.result)  # "4"
+
+            >>> # Multi-line code
+            >>> result = session.run('''
+            ... import torch
+            ... x = torch.randn(100, 100, device='cuda')
+            ... print(f"Shape: {x.shape}")
+            ... ''')
+        """
+        timeout = timeout or self.timeout
+
+        response = requests.post(
+            f"{self.base_url}/api/execute/",
+            headers=self._headers(),
+            json={"code": code},
+            timeout=timeout + 10
+        )
+
+        data = self._check_response(response)
+
+        return ExecutionResult(
+            output=data.get("output", ""),
+            result=data.get("result"),
+            error=data.get("error", ""),
+            exit_code=int(data.get("exit_code", 0)),
+            success=data.get("success", True)
+        )
+
+    def exec(self, code: str, timeout: Optional[int] = None) -> bool:
+        """
+        Execute Python code without returning a result.
+
+        Similar to run() but optimized for code that doesn't need a return value.
+        Raises an exception if execution fails.
+
+        Args:
+            code: Python code to execute
+            timeout: Timeout in seconds
+
+        Returns:
+            True if execution succeeded.
+
+        Raises:
+            ExecutionError: If code execution fails
+
+        Example:
+            >>> session.exec("import torch")
+            >>> session.exec("model = load_model()")
+        """
+        result = self.run(code, timeout)
+        if not result.success:
+            raise ExecutionError(result.error)
+        return True
+
+    def shell(self, command: str, timeout: Optional[int] = None) -> ExecutionResult:
+        """
+        Execute a shell command on the remote GPU pod.
+
+        Args:
+            command: Shell command to execute
+            timeout: Timeout in seconds
+
+        Returns:
+            ExecutionResult with command output.
+
+        Raises:
+            CommandBlockedError: If command is blocked by security filters
+            ExecutionError: If command fails
+
+        Example:
+            >>> # List files
+            >>> result = session.shell("ls -la /workspace")
+            >>> print(result.output)
+
+            >>> # Check disk space
+            >>> result = session.shell("df -h")
+
+            >>> # Multiple commands
+            >>> result = session.shell("cd /workspace && ls && pwd")
+        """
+        timeout = timeout or self.timeout
+
+        response = requests.post(
+            f"{self.base_url}/api/shell/",
+            headers=self._headers(),
+            json={"command": command},
+            timeout=timeout + 10
+        )
+
+        data = self._check_response(response)
+
+        return ExecutionResult(
+            output=data.get("output", ""),
+            result=None,
+            error=data.get("error", ""),
+            exit_code=int(data.get("exit_code", 0)),
+            success=data.get("success", True)
+        )
+
+    def set(self, name: str, value: Any) -> bool:
+        """
+        Send a local variable to the remote GPU session.
+
+        The variable is serialized with pickle and stored in the Python
+        environment on the remote GPU pod.
+
+        Args:
+            name: Variable name on the remote session
+            value: Value to send (must be picklable)
+
+        Returns:
+            True if successful.
+
+        Raises:
+            ClouditiaError: If value cannot be serialized
+
+        Example:
+            >>> # Send data to GPU
+            >>> session.set("data", [1, 2, 3, 4, 5])
+            >>> session.run("print(sum(data))")  # prints: 15
+
+            >>> # Send numpy arrays
+            >>> import numpy as np
+            >>> session.set("arr", np.random.randn(100, 100))
+        """
+        try:
+            pickled = pickle.dumps(value)
+            value_b64 = base64.b64encode(pickled).decode()
+        except Exception as e:
+            raise ClouditiaError(f"Cannot serialize value: {e}")
+
+        code = f'''
+import pickle
+import base64
+{name} = pickle.loads(base64.b64decode("{value_b64}"))
+globals()["{name}"] = {name}
+'''
+        result = self.run(code)
+        if not result.success:
+            raise ExecutionError(f"Failed to set variable: {result.error}")
+
+        self._remote_vars[name] = True
+        return True
+
+    def get(self, name: str) -> Any:
+        """
+        Retrieve a variable from the remote GPU session.
+
+        The variable is serialized on the remote pod and deserialized locally.
+
+        Args:
+            name: Variable name to retrieve
+
+        Returns:
+            The value of the variable.
+
+        Raises:
+            ExecutionError: If variable doesn't exist or can't be retrieved
+
+        Example:
+            >>> session.run("result = [i**2 for i in range(10)]")
+            >>> data = session.get("result")
+            >>> print(data)  # [0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
+        """
+        code = f'''
+import pickle
+import base64
+_tmp_value = base64.b64encode(pickle.dumps({name})).decode()
+_tmp_value
+'''
+        result = self.run(code)
+
+        if not result.success:
+            raise ExecutionError(f"Failed to get variable: {result.error}")
+
+        if result.result is None:
+            raise ExecutionError(f"Variable '{name}' not found or not serializable")
+
+        try:
+            value_b64 = result.result.strip().strip("'\"")
+            pickled = base64.b64decode(value_b64)
+            return pickle.loads(pickled)
+        except Exception as e:
+            raise ClouditiaError(f"Cannot deserialize value: {e}")
+
+    def submit(
+        self,
+        code: str,
+        name: Optional[str] = None,
+        job_type: str = "python"
+    ) -> AsyncJob:
+        """
+        Submit a long-running job for asynchronous execution.
+
+        Use this for tasks that take hours or days (like model training).
+        The job runs in the background and you can monitor its progress.
+
+        Args:
+            code: Python code or shell command to execute
+            name: Optional name to identify the job
+            job_type: "python" or "shell"
+
+        Returns:
+            AsyncJob instance for monitoring and control.
+
+        Example:
+            >>> job = session.submit('''
+            ... for epoch in range(100):
+            ...     print(f"Epoch {epoch}/100")
+            ...     train_one_epoch()
+            ... save_model()
+            ... ''', name="model_training")
+            >>>
+            >>> print(f"Job ID: {job.job_id}")
+            >>>
+            >>> # Wait with live logs
+            >>> result = job.wait(show_logs=True)
+
+            >>> # Or poll manually
+            >>> while not job.is_done():
+            ...     print(job.logs(new_only=True))
+            ...     time.sleep(30)
+        """
+        response = requests.post(
+            f"{self.base_url}/api/jobs/submit/",
+            headers=self._headers(),
+            json={
+                "code": code,
+                "name": name or "",
+                "type": job_type
+            },
+            timeout=30
+        )
+
+        data = self._check_response(response)
+
+        return AsyncJob(
+            session=self,
+            job_id=data["job_id"],
+            name=name
+        )
+
+    def jobs(
+        self,
+        status: Optional[str] = None,
+        limit: int = 10
+    ) -> List[AsyncJob]:
+        """
+        List async jobs for this session.
+
+        Args:
+            status: Filter by status (pending, running, completed, failed, cancelled)
+            limit: Maximum number of jobs to return
+
+        Returns:
+            List of AsyncJob instances.
+
+        Example:
+            >>> # List all running jobs
+            >>> running = session.jobs(status="running")
+            >>> for job in running:
+            ...     print(f"{job.name}: {job.status()}")
+
+            >>> # List recent completed jobs
+            >>> completed = session.jobs(status="completed", limit=5)
+        """
+        params = {"limit": limit}
+        if status:
+            params["status"] = status
+
+        response = requests.get(
+            f"{self.base_url}/api/jobs/list/",
+            headers=self._headers(),
+            params=params,
+            timeout=30
+        )
+
+        data = self._check_response(response)
+
+        return [
+            AsyncJob(
+                session=self,
+                job_id=job["id"],
+                name=job.get("name"),
+                _data=job
+            )
+            for job in data.get("jobs", [])
+        ]
+
+    def remote(
+        self,
+        func: Optional[Callable] = None,
+        **kwargs
+    ) -> Callable:
+        """
+        Decorator to execute a function on the remote GPU.
+
+        The function is serialized, sent to the GPU, executed, and the
+        result is returned locally. All arguments must be picklable.
+
+        Args:
+            func: Function to decorate
+            **kwargs: Options (async_mode, timeout)
+
+        Returns:
+            Decorated function that runs on remote GPU.
+
+        Example:
+            >>> @session.remote
+            ... def compute_on_gpu(data):
+            ...     import torch
+            ...     tensor = torch.tensor(data, device='cuda')
+            ...     return (tensor ** 2).sum().item()
+            >>>
+            >>> result = compute_on_gpu([1, 2, 3, 4, 5])
+            >>> print(result)  # 55
+
+            >>> # Async mode
+            >>> @session.remote(async_mode=True)
+            ... def train():
+            ...     # long training code
+            ...     pass
+            >>>
+            >>> job = train()  # Returns AsyncJob
+        """
+        async_mode = kwargs.get("async_mode", False)
+        timeout = kwargs.get("timeout", self.timeout)
+
+        def decorator(fn: Callable) -> Callable:
+            @wraps(fn)
+            def wrapper(*args, **kw):
+                # Get function source
+                source = inspect.getsource(fn)
+                source = textwrap.dedent(source)
+
+                # Remove decorator from source
+                lines = source.split("\n")
+                func_start = 0
+                for i, line in enumerate(lines):
+                    if line.strip().startswith("def "):
+                        func_start = i
+                        break
+                source = "\n".join(lines[func_start:])
+
+                # Serialize arguments
+                args_b64 = base64.b64encode(pickle.dumps(args)).decode()
+                kwargs_b64 = base64.b64encode(pickle.dumps(kw)).decode()
+
+                exec_code = f'''
+import pickle
+import base64
+
+# Define the function
+{source}
+
+# Deserialize arguments
+_args = pickle.loads(base64.b64decode("{args_b64}"))
+_kwargs = pickle.loads(base64.b64decode("{kwargs_b64}"))
+
+# Execute function
+_result = {fn.__name__}(*_args, **_kwargs)
+
+# Serialize result
+_result_b64 = base64.b64encode(pickle.dumps(_result)).decode()
+_result_b64
+'''
+
+                if async_mode:
+                    return self.submit(exec_code, name=fn.__name__)
+                else:
+                    result = self.run(exec_code, timeout=timeout)
+
+                    if not result.success:
+                        raise ExecutionError(f"Remote execution failed: {result.error}")
+
+                    if result.result:
+                        try:
+                            value_b64 = result.result.strip().strip("'\"")
+                            pickled = base64.b64decode(value_b64)
+                            return pickle.loads(pickled)
+                        except Exception as e:
+                            raise ClouditiaError(f"Cannot deserialize result: {e}")
+
+                    return None
+
+            return wrapper
+
+        if func is not None:
+            return decorator(func)
+        return decorator
+
+    def gpu_info(self) -> Dict:
+        """
+        Get detailed GPU information from the remote pod.
+
+        Returns:
+            Dict with GPU details (name, memory, utilization).
+
+        Example:
+            >>> info = session.gpu_info()
+            >>> for gpu in info['gpus']:
+            ...     print(f"{gpu['name']}: {gpu['memory_used_mb']}/{gpu['memory_total_mb']} MB")
+        """
+        # Use a safe command to get GPU info
+        result = self.run('''
+import subprocess
+result = subprocess.run(
+    ["nvidia-smi", "--query-gpu=name,memory.total,memory.used,memory.free,utilization.gpu",
+     "--format=csv,noheader,nounits"],
+    capture_output=True, text=True
+)
+print(result.stdout)
+''')
+
+        if not result.success:
+            raise ExecutionError("Failed to get GPU info")
+
+        lines = result.output.strip().split("\n")
+        gpus = []
+
+        for line in lines:
+            parts = [p.strip() for p in line.split(",")]
+            if len(parts) >= 5:
+                gpus.append({
+                    "name": parts[0],
+                    "memory_total_mb": int(parts[1]),
+                    "memory_used_mb": int(parts[2]),
+                    "memory_free_mb": int(parts[3]),
+                    "utilization_percent": int(parts[4])
+                })
+
+        return {"gpus": gpus, "count": len(gpus)}
+
+    @property
+    def session_info(self) -> Optional[Dict]:
+        """
+        Get cached session information.
+
+        Call verify() first to populate this property.
+
+        Returns:
+            Session info dict or None if not yet verified.
+        """
+        return self._session_info
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        key_preview = self.api_key[:10] + "..." if len(self.api_key) > 10 else self.api_key
+        return f"GPUSession(api_key='{key_preview}')"
+
+    def __str__(self) -> str:
+        """Return human-readable string."""
+        if self._session_info:
+            return f"GPUSession({self._session_info.get('session_name', 'connected')})"
+        return f"GPUSession(not verified)"
+
+
+def connect(api_key: str, **kwargs) -> GPUSession:
+    """
+    Create and return a GPU session.
+
+    This is a convenience function equivalent to GPUSession(api_key).
+
+    Args:
+        api_key: Your Clouditia API key
+        **kwargs: Additional options for GPUSession
+
+    Returns:
+        Configured GPUSession instance.
+
+    Example:
+        >>> from clouditia import connect
+        >>> session = connect("ck_your_api_key")
+        >>> result = session.run("print('Hello!')")
+    """
+    return GPUSession(api_key, **kwargs)