clouditia 1.2.4__tar.gz → 1.3.0__tar.gz

{clouditia-1.2.4/clouditia.egg-info → clouditia-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clouditia
-Version: 1.2.4
+Version: 1.3.0
 Summary: Execute Python and Shell code on remote GPU sessions
 Author-email: Aina KIKI-SAGBE <support@clouditia.com>
 Maintainer-email: Aina KIKI-SAGBE <support@clouditia.com>
@@ -81,6 +81,7 @@ print(result.output)
 - **Shell Commands**: Execute shell commands on the GPU pod
 - **Persistent Sessions**: Keep variables between executions with `start()`/`stop()`
 - **Variable Transfer**: Send and retrieve variables between local and remote
+- **File Transfer**: Upload/download files and folders between local and remote
 - **Async Jobs**: Submit long-running tasks with real-time log monitoring
 - **Jupyter Magic**: Use `%%clouditia` magic in notebooks
 - **Decorator Support**: Use `@session.remote` to run functions on GPU
@@ -95,11 +96,12 @@ print(result.output)
 4. [Executing Python Code](#executing-python-code)
 5. [Shell Commands](#shell-commands)
 6. [Variable Transfer](#variable-transfer)
-7. [Remote Functions (Decorator)](#remote-functions-decorator)
-8. [Async Jobs (Long-Running Tasks)](#async-jobs-long-running-tasks)
-9. [Jupyter Magic](#jupyter-magic)
-10. [Error Handling](#error-handling)
-11. [API Reference](#api-reference)
+7. [File Transfer](#file-transfer)
+8. [Remote Functions (Decorator)](#remote-functions-decorator)
+9. [Async Jobs (Long-Running Tasks)](#async-jobs-long-running-tasks)
+10. [Jupyter Magic](#jupyter-magic)
+11. [Error Handling](#error-handling)
+12. [API Reference](#api-reference)
 
 ---
 
@@ -377,6 +379,182 @@ print(f"Learning rate: {config['learning_rate']}")
 
 ---
 
+## File Transfer
+
+Transfer files and folders between your local machine and the remote GPU session.
+
+### Uploading a Single File
+
+```python
+# Upload a local file to the remote session
+session.upload("./data.csv", "/home/coder/workspace/data.csv")
+
+# Upload with custom path
+session.upload("./model.pkl", "/home/coder/workspace/models/trained_model.pkl")
+
+# Disable progress output
+session.upload("./config.json", "/home/coder/workspace/config.json", show_progress=False)
+```
+
+### Downloading a Single File
+
+```python
+# Download a file from the remote session
+session.download("/home/coder/workspace/results.csv", "./results.csv")
+
+# Download trained model
+session.download("/home/coder/workspace/checkpoints/model.pt", "./local_model.pt")
+
+# Download silently
+session.download("/home/coder/workspace/logs.txt", "./logs.txt", show_progress=False)
+```
+
+### Uploading a Folder
+
+Upload an entire directory with all its contents:
+
+```python
+# Upload a project folder
+session.upload_folder("./my_project", "/home/coder/workspace/project")
+
+# Upload with exclusions (default excludes: __pycache__, .git, *.pyc, .DS_Store, node_modules)
+session.upload_folder(
+    "./my_project",
+    "/home/coder/workspace/project",
+    exclude=["*.log", ".env", "__pycache__", ".git"]
+)
+
+# Upload data folder
+session.upload_folder("./datasets", "/home/coder/workspace/data")
+```
+
+### Downloading a Folder
+
+Download an entire directory with all its contents:
+
+```python
+# Download results folder
+session.download_folder("/home/coder/workspace/results", "./local_results")
+
+# Download checkpoints
+session.download_folder(
+    "/home/coder/workspace/checkpoints",
+    "./checkpoints",
+    exclude=["*.tmp", "*.log"]
+)
+
+# Download trained models
+session.download_folder("/home/coder/workspace/models", "./downloaded_models")
+```
+
+### Listing Remote Files
+
+```python
+# List files in a directory
+files = session.list_files("/home/coder/workspace")
+for f in files:
+    icon = "📁" if f["is_dir"] else "📄"
+    print(f"{icon} {f['name']} - {f['size']} bytes")
+
+# Filter by pattern
+python_files = session.list_files("/home/coder/workspace", pattern="*.py")
+for f in python_files:
+    print(f"📄 {f['name']}")
+
+# List with full details
+files = session.list_files("/home/coder/workspace")
+for f in files:
+    print(f"Name: {f['name']}")
+    print(f"  Path: {f['path']}")
+    print(f"  Size: {f['size']} bytes")
+    print(f"  Is Directory: {f['is_dir']}")
+    print(f"  Modified: {f['modified']}")
+```
+
+### Checking if a File Exists
+
+```python
+# Check before downloading
+if session.file_exists("/home/coder/workspace/model.pt"):
+    session.download("/home/coder/workspace/model.pt", "./model.pt")
+    print("Model downloaded!")
+else:
+    print("Model not found, training required...")
+
+# Check multiple files
+files_to_check = ["config.json", "data.csv", "model.pt"]
+for filename in files_to_check:
+    path = f"/home/coder/workspace/{filename}"
+    exists = session.file_exists(path)
+    status = "✓" if exists else "✗"
+    print(f"{status} {filename}")
+```
+
+### Complete Workflow Example
+
+```python
+from clouditia import GPUSession
+
+session = GPUSession("ck_your_api_key")
+
+# 1. Upload training data and code
+session.upload_folder("./training_code", "/home/coder/workspace/code")
+session.upload("./data/train.csv", "/home/coder/workspace/data/train.csv")
+session.upload("./data/test.csv", "/home/coder/workspace/data/test.csv")
+
+# 2. Run training
+result = session.run("""
+import sys
+sys.path.insert(0, '/home/coder/workspace/code')
+from train import train_model
+
+model = train_model('/home/coder/workspace/data/train.csv')
+model.save('/home/coder/workspace/output/model.pt')
+print("Training complete!")
+""")
+
+# 3. Check and download results
+if session.file_exists("/home/coder/workspace/output/model.pt"):
+    session.download("/home/coder/workspace/output/model.pt", "./trained_model.pt")
+    print("Model saved locally!")
+
+# 4. Download all outputs
+session.download_folder("/home/coder/workspace/output", "./results")
+print("All results downloaded!")
+
+# 5. List what was created
+files = session.list_files("/home/coder/workspace/output")
+print(f"Created {len(files)} files during training")
+```
+
+### Working with Different File Types
+
+```python
+# CSV files
+session.upload("./data.csv", "/home/coder/workspace/data.csv")
+
+# Pickle files (models, data)
+session.upload("./model.pkl", "/home/coder/workspace/model.pkl")
+
+# PyTorch models
+session.download("/home/coder/workspace/checkpoint.pt", "./checkpoint.pt")
+
+# JSON configuration
+session.upload("./config.json", "/home/coder/workspace/config.json")
+
+# Text files
+session.upload("./requirements.txt", "/home/coder/workspace/requirements.txt")
+
+# Binary files
+session.upload("./image.png", "/home/coder/workspace/image.png")
+
+# Any file type works!
+session.upload("./data.parquet", "/home/coder/workspace/data.parquet")
+session.upload("./weights.h5", "/home/coder/workspace/weights.h5")
+```
+
+---
+
 ## Remote Functions (Decorator)
 
 Use the `@session.remote` decorator to run functions on the GPU:
@@ -707,6 +885,12 @@ GPUSession(
 | `stop()` | Stop the persistent session |
 | `set(name, value)` | Send variable to remote |
 | `get(name)` | Retrieve variable from remote |
+| `upload(local_path, remote_path, show_progress=True)` | Upload a file to remote session |
+| `download(remote_path, local_path, show_progress=True)` | Download a file from remote session |
+| `upload_folder(local_path, remote_path, exclude=None)` | Upload a folder to remote session |
+| `download_folder(remote_path, local_path, exclude=None)` | Download a folder from remote session |
+| `list_files(remote_path, pattern=None)` | List files in remote directory |
+| `file_exists(remote_path)` | Check if a file exists on remote |
 | `submit(code, name=None, job_type="python")` | Submit async job |
 | `jobs(status=None, limit=10)` | List jobs |
 | `gpu_info()` | Get GPU information |

{clouditia-1.2.4 → clouditia-1.3.0}/README.md

@@ -38,6 +38,7 @@ print(result.output)
 - **Shell Commands**: Execute shell commands on the GPU pod
 - **Persistent Sessions**: Keep variables between executions with `start()`/`stop()`
 - **Variable Transfer**: Send and retrieve variables between local and remote
+- **File Transfer**: Upload/download files and folders between local and remote
 - **Async Jobs**: Submit long-running tasks with real-time log monitoring
 - **Jupyter Magic**: Use `%%clouditia` magic in notebooks
 - **Decorator Support**: Use `@session.remote` to run functions on GPU
@@ -52,11 +53,12 @@ print(result.output)
 4. [Executing Python Code](#executing-python-code)
 5. [Shell Commands](#shell-commands)
 6. [Variable Transfer](#variable-transfer)
-7. [Remote Functions (Decorator)](#remote-functions-decorator)
-8. [Async Jobs (Long-Running Tasks)](#async-jobs-long-running-tasks)
-9. [Jupyter Magic](#jupyter-magic)
-10. [Error Handling](#error-handling)
-11. [API Reference](#api-reference)
+7. [File Transfer](#file-transfer)
+8. [Remote Functions (Decorator)](#remote-functions-decorator)
+9. [Async Jobs (Long-Running Tasks)](#async-jobs-long-running-tasks)
+10. [Jupyter Magic](#jupyter-magic)
+11. [Error Handling](#error-handling)
+12. [API Reference](#api-reference)
 
 ---
 
@@ -334,6 +336,182 @@ print(f"Learning rate: {config['learning_rate']}")
 
 ---
 
+## File Transfer
+
+Transfer files and folders between your local machine and the remote GPU session.
+
+### Uploading a Single File
+
+```python
+# Upload a local file to the remote session
+session.upload("./data.csv", "/home/coder/workspace/data.csv")
+
+# Upload with custom path
+session.upload("./model.pkl", "/home/coder/workspace/models/trained_model.pkl")
+
+# Disable progress output
+session.upload("./config.json", "/home/coder/workspace/config.json", show_progress=False)
+```
+
+### Downloading a Single File
+
+```python
+# Download a file from the remote session
+session.download("/home/coder/workspace/results.csv", "./results.csv")
+
+# Download trained model
+session.download("/home/coder/workspace/checkpoints/model.pt", "./local_model.pt")
+
+# Download silently
+session.download("/home/coder/workspace/logs.txt", "./logs.txt", show_progress=False)
+```
+
+### Uploading a Folder
+
+Upload an entire directory with all its contents:
+
+```python
+# Upload a project folder
+session.upload_folder("./my_project", "/home/coder/workspace/project")
+
+# Upload with exclusions (default excludes: __pycache__, .git, *.pyc, .DS_Store, node_modules)
+session.upload_folder(
+    "./my_project",
+    "/home/coder/workspace/project",
+    exclude=["*.log", ".env", "__pycache__", ".git"]
+)
+
+# Upload data folder
+session.upload_folder("./datasets", "/home/coder/workspace/data")
+```
+
+### Downloading a Folder
+
+Download an entire directory with all its contents:
+
+```python
+# Download results folder
+session.download_folder("/home/coder/workspace/results", "./local_results")
+
+# Download checkpoints
+session.download_folder(
+    "/home/coder/workspace/checkpoints",
+    "./checkpoints",
+    exclude=["*.tmp", "*.log"]
+)
+
+# Download trained models
+session.download_folder("/home/coder/workspace/models", "./downloaded_models")
+```
+
+### Listing Remote Files
+
+```python
+# List files in a directory
+files = session.list_files("/home/coder/workspace")
+for f in files:
+    icon = "📁" if f["is_dir"] else "📄"
+    print(f"{icon} {f['name']} - {f['size']} bytes")
+
+# Filter by pattern
+python_files = session.list_files("/home/coder/workspace", pattern="*.py")
+for f in python_files:
+    print(f"📄 {f['name']}")
+
+# List with full details
+files = session.list_files("/home/coder/workspace")
+for f in files:
+    print(f"Name: {f['name']}")
+    print(f"  Path: {f['path']}")
+    print(f"  Size: {f['size']} bytes")
+    print(f"  Is Directory: {f['is_dir']}")
+    print(f"  Modified: {f['modified']}")
+```
+
+### Checking if a File Exists
+
+```python
+# Check before downloading
+if session.file_exists("/home/coder/workspace/model.pt"):
+    session.download("/home/coder/workspace/model.pt", "./model.pt")
+    print("Model downloaded!")
+else:
+    print("Model not found, training required...")
+
+# Check multiple files
+files_to_check = ["config.json", "data.csv", "model.pt"]
+for filename in files_to_check:
+    path = f"/home/coder/workspace/{filename}"
+    exists = session.file_exists(path)
+    status = "✓" if exists else "✗"
+    print(f"{status} {filename}")
+```
+
+### Complete Workflow Example
+
+```python
+from clouditia import GPUSession
+
+session = GPUSession("ck_your_api_key")
+
+# 1. Upload training data and code
+session.upload_folder("./training_code", "/home/coder/workspace/code")
+session.upload("./data/train.csv", "/home/coder/workspace/data/train.csv")
+session.upload("./data/test.csv", "/home/coder/workspace/data/test.csv")
+
+# 2. Run training
+result = session.run("""
+import sys
+sys.path.insert(0, '/home/coder/workspace/code')
+from train import train_model
+
+model = train_model('/home/coder/workspace/data/train.csv')
+model.save('/home/coder/workspace/output/model.pt')
+print("Training complete!")
+""")
+
+# 3. Check and download results
+if session.file_exists("/home/coder/workspace/output/model.pt"):
+    session.download("/home/coder/workspace/output/model.pt", "./trained_model.pt")
+    print("Model saved locally!")
+
+# 4. Download all outputs
+session.download_folder("/home/coder/workspace/output", "./results")
+print("All results downloaded!")
+
+# 5. List what was created
+files = session.list_files("/home/coder/workspace/output")
+print(f"Created {len(files)} files during training")
+```
+
+### Working with Different File Types
+
+```python
+# CSV files
+session.upload("./data.csv", "/home/coder/workspace/data.csv")
+
+# Pickle files (models, data)
+session.upload("./model.pkl", "/home/coder/workspace/model.pkl")
+
+# PyTorch models
+session.download("/home/coder/workspace/checkpoint.pt", "./checkpoint.pt")
+
+# JSON configuration
+session.upload("./config.json", "/home/coder/workspace/config.json")
+
+# Text files
+session.upload("./requirements.txt", "/home/coder/workspace/requirements.txt")
+
+# Binary files
+session.upload("./image.png", "/home/coder/workspace/image.png")
+
+# Any file type works!
+session.upload("./data.parquet", "/home/coder/workspace/data.parquet")
+session.upload("./weights.h5", "/home/coder/workspace/weights.h5")
+```
+
+---
+
 ## Remote Functions (Decorator)
 
 Use the `@session.remote` decorator to run functions on the GPU:
@@ -664,6 +842,12 @@ GPUSession(
 | `stop()` | Stop the persistent session |
 | `set(name, value)` | Send variable to remote |
 | `get(name)` | Retrieve variable from remote |
+| `upload(local_path, remote_path, show_progress=True)` | Upload a file to remote session |
+| `download(remote_path, local_path, show_progress=True)` | Download a file from remote session |
+| `upload_folder(local_path, remote_path, exclude=None)` | Upload a folder to remote session |
+| `download_folder(remote_path, local_path, exclude=None)` | Download a folder from remote session |
+| `list_files(remote_path, pattern=None)` | List files in remote directory |
+| `file_exists(remote_path)` | Check if a file exists on remote |
 | `submit(code, name=None, job_type="python")` | Submit async job |
 | `jobs(status=None, limit=10)` | List jobs |
 | `gpu_info()` | Get GPU information |

{clouditia-1.2.4 → clouditia-1.3.0}/clouditia/__init__.py

@@ -15,7 +15,7 @@ Basic Usage:
 For more examples, see: https://clouditia.com/docs
 """
 
-__version__ = "1.2.4"
+__version__ = "1.3.0"
 __author__ = "Aina KIKI-SAGBE"
 __email__ = "support@clouditia.com"
 

{clouditia-1.2.4 → clouditia-1.3.0}/clouditia/client.py

@@ -6,11 +6,15 @@ This module provides the GPUSession class for interacting with remote GPU sessio
 
 import base64
 import inspect
+import io
 import json
+import os
 import pickle
+import tarfile
 import textwrap
 from functools import wraps
-from typing import Any, Callable, Dict, List, Optional
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Union
 
 import requests
 
@@ -548,6 +552,487 @@ _tmp_value
         except Exception as e:
             raise ClouditiaError(f"Cannot deserialize value: {e}")
 
+    # ==================== FILE TRANSFER METHODS ====================
+
+    def upload(
+        self,
+        local_path: Union[str, Path],
+        remote_path: str,
+        show_progress: bool = True
+    ) -> bool:
+        """
+        Upload a file from local machine to the remote GPU session.
+
+        Args:
+            local_path: Path to the local file
+            remote_path: Destination path on the remote pod
+            show_progress: Show upload progress (default: True)
+
+        Returns:
+            True if upload succeeded.
+
+        Raises:
+            FileNotFoundError: If local file doesn't exist
+            ClouditiaError: If upload fails
+
+        Example:
+            >>> session.upload("./data.csv", "/workspace/data.csv")
+            >>> session.upload("model.pkl", "/workspace/models/model.pkl")
+        """
+        local_path = Path(local_path)
+
+        if not local_path.exists():
+            raise FileNotFoundError(f"Local file not found: {local_path}")
+
+        if not local_path.is_file():
+            raise ClouditiaError(f"Not a file: {local_path}. Use upload_folder() for directories.")
+
+        # Read and encode file
+        file_size = local_path.stat().st_size
+        if show_progress:
+            print(f"📤 Uploading {local_path.name} ({self._format_size(file_size)})...")
+
+        with open(local_path, 'rb') as f:
+            file_data = f.read()
+
+        file_b64 = base64.b64encode(file_data).decode()
+
+        # Create directory and write file on remote
+        remote_dir = os.path.dirname(remote_path)
+        code = f'''
+import base64
+import os
+
+# Create directory if needed
+os.makedirs("{remote_dir}", exist_ok=True)
+
+# Decode and write file
+file_data = base64.b64decode("{file_b64}")
+with open("{remote_path}", "wb") as f:
+    f.write(file_data)
+
+print(f"File written: {remote_path} ({{len(file_data)}} bytes)")
+'''
+        result = self.run(code, stream=False)
+
+        if not result.success:
+            raise ClouditiaError(f"Upload failed: {result.error}")
+
+        if show_progress:
+            print(f"✅ Uploaded to {remote_path}")
+
+        return True
+
+    def download(
+        self,
+        remote_path: str,
+        local_path: Union[str, Path],
+        show_progress: bool = True
+    ) -> bool:
+        """
+        Download a file from the remote GPU session to local machine.
+
+        Args:
+            remote_path: Path to the file on the remote pod
+            local_path: Destination path on local machine
+            show_progress: Show download progress (default: True)
+
+        Returns:
+            True if download succeeded.
+
+        Raises:
+            ClouditiaError: If file doesn't exist or download fails
+
+        Example:
+            >>> session.download("/workspace/results.csv", "./results.csv")
+            >>> session.download("/workspace/model.pt", "./models/trained_model.pt")
+        """
+        local_path = Path(local_path)
+
+        if show_progress:
+            print(f"📥 Downloading {os.path.basename(remote_path)}...")
+
+        # Read and encode file on remote - use print to output the base64
+        code = f'''
+import base64
+import os
+
+if not os.path.exists("{remote_path}"):
+    raise FileNotFoundError("File not found: {remote_path}")
+
+if os.path.isdir("{remote_path}"):
+    raise IsADirectoryError("Path is a directory. Use download_folder() instead.")
+
+with open("{remote_path}", "rb") as f:
+    file_data = f.read()
+
+file_b64 = base64.b64encode(file_data).decode()
+print("__FILEDATA_START__")
+print(file_b64)
+print("__FILEDATA_END__")
+'''
+        result = self.run(code, stream=False)
+
+        if not result.success:
+            raise ClouditiaError(f"Download failed: {result.error}")
+
+        # Extract base64 data from output
+        output = result.output or ""
+        if "__FILEDATA_START__" not in output or "__FILEDATA_END__" not in output:
+            raise ClouditiaError("No data received from remote")
+
+        # Parse the base64 data between markers
+        try:
+            start = output.index("__FILEDATA_START__") + len("__FILEDATA_START__")
+            end = output.index("__FILEDATA_END__")
+            file_b64 = output[start:end].strip()
+            file_data = base64.b64decode(file_b64)
+        except Exception as e:
+            raise ClouditiaError(f"Failed to decode file data: {e}")
+
+        # Create local directory if needed
+        local_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(local_path, 'wb') as f:
+            f.write(file_data)
+
+        if show_progress:
+            print(f"✅ Downloaded to {local_path} ({self._format_size(len(file_data))})")
+
+        return True
+
+    def upload_folder(
+        self,
+        local_path: Union[str, Path],
+        remote_path: str,
+        exclude: Optional[List[str]] = None,
+        show_progress: bool = True
+    ) -> bool:
+        """
+        Upload an entire folder from local machine to the remote GPU session.
+
+        The folder is compressed locally, transferred, and extracted on the remote.
+
+        Args:
+            local_path: Path to the local folder
+            remote_path: Destination path on the remote pod
+            exclude: List of patterns to exclude (e.g., ['__pycache__', '.git', '*.pyc'])
+            show_progress: Show upload progress (default: True)
+
+        Returns:
+            True if upload succeeded.
+
+        Raises:
+            FileNotFoundError: If local folder doesn't exist
+            ClouditiaError: If upload fails
+
+        Example:
+            >>> session.upload_folder("./my_project", "/workspace/project")
+            >>> session.upload_folder("./data", "/workspace/data", exclude=['*.tmp', '.git'])
+        """
+        local_path = Path(local_path)
+
+        if not local_path.exists():
+            raise FileNotFoundError(f"Local folder not found: {local_path}")
+
+        if not local_path.is_dir():
+            raise ClouditiaError(f"Not a directory: {local_path}. Use upload() for files.")
+
+        # Default exclusions
+        if exclude is None:
+            exclude = ['__pycache__', '.git', '*.pyc', '.DS_Store', 'node_modules']
+
+        if show_progress:
+            print(f"📦 Compressing {local_path.name}...")
+
+        # Create tar.gz in memory
+        tar_buffer = io.BytesIO()
+
+        def filter_func(tarinfo):
+            # Check exclusion patterns
+            for pattern in exclude:
+                if pattern.startswith('*'):
+                    if tarinfo.name.endswith(pattern[1:]):
+                        return None
+                elif pattern in tarinfo.name:
+                    return None
+            return tarinfo
+
+        with tarfile.open(fileobj=tar_buffer, mode='w:gz') as tar:
+            tar.add(local_path, arcname=os.path.basename(local_path), filter=filter_func)
+
+        tar_data = tar_buffer.getvalue()
+        tar_b64 = base64.b64encode(tar_data).decode()
+
+        if show_progress:
+            print(f"📤 Uploading {self._format_size(len(tar_data))}...")
+
+        # Transfer and extract on remote
+        code = f'''
+import base64
+import tarfile
+import io
+import os
+
+# Decode tar data
+tar_data = base64.b64decode("{tar_b64}")
+
+# Create destination directory
+os.makedirs("{remote_path}", exist_ok=True)
+
+# Extract
+tar_buffer = io.BytesIO(tar_data)
+with tarfile.open(fileobj=tar_buffer, mode='r:gz') as tar:
+    tar.extractall(path="{remote_path}")
+
+# Count files
+file_count = sum(1 for root, dirs, files in os.walk("{remote_path}") for f in files)
+print(f"Extracted {{file_count}} files to {remote_path}")
+'''
+        result = self.run(code, stream=False)
+
+        if not result.success:
+            raise ClouditiaError(f"Upload folder failed: {result.error}")
+
+        if show_progress:
+            print(f"✅ Folder uploaded to {remote_path}")
+
+        return True
+
+    def download_folder(
+        self,
+        remote_path: str,
+        local_path: Union[str, Path],
+        exclude: Optional[List[str]] = None,
+        show_progress: bool = True
+    ) -> bool:
+        """
+        Download an entire folder from the remote GPU session to local machine.
+
+        The folder is compressed on the remote, transferred, and extracted locally.
+
+        Args:
+            remote_path: Path to the folder on the remote pod
+            local_path: Destination path on local machine
+            exclude: List of patterns to exclude (e.g., ['__pycache__', '*.pyc'])
+            show_progress: Show download progress (default: True)
+
+        Returns:
+            True if download succeeded.
+
+        Raises:
+            ClouditiaError: If folder doesn't exist or download fails
+
+        Example:
+            >>> session.download_folder("/workspace/results", "./results")
+            >>> session.download_folder("/workspace/checkpoints", "./checkpoints", exclude=['*.tmp'])
+        """
+        local_path = Path(local_path)
+
+        # Default exclusions
+        if exclude is None:
+            exclude = ['__pycache__', '*.pyc', '.DS_Store']
+
+        if show_progress:
+            print(f"📦 Compressing remote folder...")
+
+        # Build exclude filter for Python
+        exclude_patterns = repr(exclude)
+
+        # Compress on remote and get base64
+        code = f'''
+import base64
+import tarfile
+import io
+import os
+import fnmatch
+
+if not os.path.exists("{remote_path}"):
+    raise FileNotFoundError("Folder not found: {remote_path}")
+
+if not os.path.isdir("{remote_path}"):
+    raise NotADirectoryError("Path is not a directory. Use download() instead.")
+
+exclude_patterns = {exclude_patterns}
+
+def should_exclude(name):
+    for pattern in exclude_patterns:
+        if fnmatch.fnmatch(name, pattern) or fnmatch.fnmatch(os.path.basename(name), pattern):
+            return True
+    return False
+
+def filter_func(tarinfo):
+    if should_exclude(tarinfo.name):
+        return None
+    return tarinfo
+
+# Create tar.gz in memory
+tar_buffer = io.BytesIO()
+with tarfile.open(fileobj=tar_buffer, mode='w:gz') as tar:
+    tar.add("{remote_path}", arcname=os.path.basename("{remote_path}"), filter=filter_func)
+
+tar_data = tar_buffer.getvalue()
+tar_b64 = base64.b64encode(tar_data).decode()
+print(f"Compressed size: {{len(tar_data)}} bytes")
+print("__FOLDERDATA_START__")
+print(tar_b64)
+print("__FOLDERDATA_END__")
+'''
+        result = self.run(code, stream=False)
+
+        if not result.success:
+            raise ClouditiaError(f"Download folder failed: {result.error}")
+
+        # Extract base64 data from output
+        output = result.output or ""
+        if "__FOLDERDATA_START__" not in output or "__FOLDERDATA_END__" not in output:
+            raise ClouditiaError("No data received from remote")
+
+        if show_progress:
+            print(f"📥 Downloading...")
+
+        # Decode and extract locally
+        try:
+            start = output.index("__FOLDERDATA_START__") + len("__FOLDERDATA_START__")
+            end = output.index("__FOLDERDATA_END__")
+            tar_b64 = output[start:end].strip()
+            tar_data = base64.b64decode(tar_b64)
+        except Exception as e:
+            raise ClouditiaError(f"Failed to decode folder data: {e}")
+
+        # Create local directory
+        local_path.mkdir(parents=True, exist_ok=True)
+
+        # Extract
+        tar_buffer = io.BytesIO(tar_data)
+        with tarfile.open(fileobj=tar_buffer, mode='r:gz') as tar:
+            tar.extractall(path=local_path)
+
+        # Count files
+        file_count = sum(1 for root, dirs, files in os.walk(local_path) for f in files)
+
+        if show_progress:
+            print(f"✅ Downloaded to {local_path} ({file_count} files, {self._format_size(len(tar_data))})")
+
+        return True
+
+    def list_files(
+        self,
+        remote_path: str = "/workspace",
+        pattern: Optional[str] = None
+    ) -> List[Dict]:
+        """
+        List files in a remote directory.
+
+        Args:
+            remote_path: Directory path to list (default: /workspace)
+            pattern: Optional glob pattern to filter files (e.g., '*.py')
+
+        Returns:
+            List of dicts with file info (name, path, size, is_dir, modified).
+
+        Example:
+            >>> files = session.list_files("/workspace")
+            >>> for f in files:
+            ...     print(f"{f['name']} - {f['size']} bytes")
+
+            >>> py_files = session.list_files("/workspace", pattern="*.py")
+        """
+        pattern_code = f'"{pattern}"' if pattern else 'None'
+
+        code = f'''
+import os
+import json
+from datetime import datetime
+import fnmatch
+
+path = "{remote_path}"
+pattern = {pattern_code}
+
+if not os.path.exists(path):
+    raise FileNotFoundError(f"Path not found: {{path}}")
+
+files = []
+for item in os.listdir(path):
+    item_path = os.path.join(path, item)
+    stat = os.stat(item_path)
+
+    if pattern and not fnmatch.fnmatch(item, pattern):
+        continue
+
+    files.append({{
+        "name": item,
+        "path": item_path,
+        "size": stat.st_size,
+        "is_dir": os.path.isdir(item_path),
+        "modified": datetime.fromtimestamp(stat.st_mtime).isoformat()
+    }})
+
+# Sort: directories first, then by name
+files.sort(key=lambda x: (not x["is_dir"], x["name"].lower()))
+
+print("__LISTFILES_START__")
+print(json.dumps(files))
+print("__LISTFILES_END__")
+'''
+        result = self.run(code, stream=False)
+
+        if not result.success:
+            raise ClouditiaError(f"Failed to list files: {result.error}")
+
+        output = result.output or ""
+        if "__LISTFILES_START__" in output and "__LISTFILES_END__" in output:
+            try:
+                start = output.index("__LISTFILES_START__") + len("__LISTFILES_START__")
+                end = output.index("__LISTFILES_END__")
+                files_json = output[start:end].strip()
+                return json.loads(files_json)
+            except (json.JSONDecodeError, ValueError):
+                return []
+
+        return []
+
+    def file_exists(self, remote_path: str) -> bool:
+        """
+        Check if a file or directory exists on the remote pod.
+
+        Args:
+            remote_path: Path to check
+
+        Returns:
+            True if path exists, False otherwise.
+
+        Example:
+            >>> if session.file_exists("/workspace/model.pt"):
+            ...     session.download("/workspace/model.pt", "./model.pt")
+        """
+        code = f'''
+import os
+exists = os.path.exists("{remote_path}")
+print("__EXISTS_START__")
+print("TRUE" if exists else "FALSE")
+print("__EXISTS_END__")
+'''
+        result = self.run(code, stream=False)
+
+        output = result.output or ""
+        if "__EXISTS_START__" in output and "__EXISTS_END__" in output:
+            start = output.index("__EXISTS_START__") + len("__EXISTS_START__")
+            end = output.index("__EXISTS_END__")
+            value = output[start:end].strip()
+            return value == "TRUE"
+        return False
+
+    def _format_size(self, size: int) -> str:
+        """Format file size in human-readable format."""
+        for unit in ['B', 'KB', 'MB', 'GB']:
+            if size < 1024:
+                return f"{size:.1f} {unit}"
+            size /= 1024
+        return f"{size:.1f} TB"
+
+    # ==================== END FILE TRANSFER METHODS ====================
+
     def submit(
         self,
         code: str,

{clouditia-1.2.4 → clouditia-1.3.0/clouditia.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clouditia
-Version: 1.2.4
+Version: 1.3.0
 Summary: Execute Python and Shell code on remote GPU sessions
 Author-email: Aina KIKI-SAGBE <support@clouditia.com>
 Maintainer-email: Aina KIKI-SAGBE <support@clouditia.com>
@@ -81,6 +81,7 @@ print(result.output)
 - **Shell Commands**: Execute shell commands on the GPU pod
 - **Persistent Sessions**: Keep variables between executions with `start()`/`stop()`
 - **Variable Transfer**: Send and retrieve variables between local and remote
+- **File Transfer**: Upload/download files and folders between local and remote
 - **Async Jobs**: Submit long-running tasks with real-time log monitoring
 - **Jupyter Magic**: Use `%%clouditia` magic in notebooks
 - **Decorator Support**: Use `@session.remote` to run functions on GPU
@@ -95,11 +96,12 @@ print(result.output)
 4. [Executing Python Code](#executing-python-code)
 5. [Shell Commands](#shell-commands)
 6. [Variable Transfer](#variable-transfer)
-7. [Remote Functions (Decorator)](#remote-functions-decorator)
-8. [Async Jobs (Long-Running Tasks)](#async-jobs-long-running-tasks)
-9. [Jupyter Magic](#jupyter-magic)
-10. [Error Handling](#error-handling)
-11. [API Reference](#api-reference)
+7. [File Transfer](#file-transfer)
+8. [Remote Functions (Decorator)](#remote-functions-decorator)
+9. [Async Jobs (Long-Running Tasks)](#async-jobs-long-running-tasks)
+10. [Jupyter Magic](#jupyter-magic)
+11. [Error Handling](#error-handling)
+12. [API Reference](#api-reference)
 
 ---
 
@@ -377,6 +379,182 @@ print(f"Learning rate: {config['learning_rate']}")
 
 ---
 
+## File Transfer
+
+Transfer files and folders between your local machine and the remote GPU session.
+
+### Uploading a Single File
+
+```python
+# Upload a local file to the remote session
+session.upload("./data.csv", "/home/coder/workspace/data.csv")
+
+# Upload with custom path
+session.upload("./model.pkl", "/home/coder/workspace/models/trained_model.pkl")
+
+# Disable progress output
+session.upload("./config.json", "/home/coder/workspace/config.json", show_progress=False)
+```
+
+### Downloading a Single File
+
+```python
+# Download a file from the remote session
+session.download("/home/coder/workspace/results.csv", "./results.csv")
+
+# Download trained model
+session.download("/home/coder/workspace/checkpoints/model.pt", "./local_model.pt")
+
+# Download silently
+session.download("/home/coder/workspace/logs.txt", "./logs.txt", show_progress=False)
+```
+
+### Uploading a Folder
+
+Upload an entire directory with all its contents:
+
+```python
+# Upload a project folder
+session.upload_folder("./my_project", "/home/coder/workspace/project")
+
+# Upload with exclusions (default excludes: __pycache__, .git, *.pyc, .DS_Store, node_modules)
+session.upload_folder(
+    "./my_project",
+    "/home/coder/workspace/project",
+    exclude=["*.log", ".env", "__pycache__", ".git"]
+)
+
+# Upload data folder
+session.upload_folder("./datasets", "/home/coder/workspace/data")
+```
+
+### Downloading a Folder
+
+Download an entire directory with all its contents:
+
+```python
+# Download results folder
+session.download_folder("/home/coder/workspace/results", "./local_results")
+
+# Download checkpoints
+session.download_folder(
+    "/home/coder/workspace/checkpoints",
+    "./checkpoints",
+    exclude=["*.tmp", "*.log"]
+)
+
+# Download trained models
+session.download_folder("/home/coder/workspace/models", "./downloaded_models")
+```
+
+### Listing Remote Files
+
+```python
+# List files in a directory
+files = session.list_files("/home/coder/workspace")
+for f in files:
+    icon = "📁" if f["is_dir"] else "📄"
+    print(f"{icon} {f['name']} - {f['size']} bytes")
+
+# Filter by pattern
+python_files = session.list_files("/home/coder/workspace", pattern="*.py")
+for f in python_files:
+    print(f"📄 {f['name']}")
+
+# List with full details
+files = session.list_files("/home/coder/workspace")
+for f in files:
+    print(f"Name: {f['name']}")
+    print(f"  Path: {f['path']}")
+    print(f"  Size: {f['size']} bytes")
+    print(f"  Is Directory: {f['is_dir']}")
+    print(f"  Modified: {f['modified']}")
+```
+
+### Checking if a File Exists
+
+```python
+# Check before downloading
+if session.file_exists("/home/coder/workspace/model.pt"):
+    session.download("/home/coder/workspace/model.pt", "./model.pt")
+    print("Model downloaded!")
+else:
+    print("Model not found, training required...")
+
+# Check multiple files
+files_to_check = ["config.json", "data.csv", "model.pt"]
+for filename in files_to_check:
+    path = f"/home/coder/workspace/{filename}"
+    exists = session.file_exists(path)
+    status = "✓" if exists else "✗"
+    print(f"{status} {filename}")
+```
+
+### Complete Workflow Example
+
+```python
+from clouditia import GPUSession
+
+session = GPUSession("ck_your_api_key")
+
+# 1. Upload training data and code
+session.upload_folder("./training_code", "/home/coder/workspace/code")
+session.upload("./data/train.csv", "/home/coder/workspace/data/train.csv")
+session.upload("./data/test.csv", "/home/coder/workspace/data/test.csv")
+
+# 2. Run training
+result = session.run("""
+import sys
+sys.path.insert(0, '/home/coder/workspace/code')
+from train import train_model
+
+model = train_model('/home/coder/workspace/data/train.csv')
+model.save('/home/coder/workspace/output/model.pt')
+print("Training complete!")
+""")
+
+# 3. Check and download results
+if session.file_exists("/home/coder/workspace/output/model.pt"):
+    session.download("/home/coder/workspace/output/model.pt", "./trained_model.pt")
+    print("Model saved locally!")
+
+# 4. Download all outputs
+session.download_folder("/home/coder/workspace/output", "./results")
+print("All results downloaded!")
+
+# 5. List what was created
+files = session.list_files("/home/coder/workspace/output")
+print(f"Created {len(files)} files during training")
+```
+
+### Working with Different File Types
+
+```python
+# CSV files
+session.upload("./data.csv", "/home/coder/workspace/data.csv")
+
+# Pickle files (models, data)
+session.upload("./model.pkl", "/home/coder/workspace/model.pkl")
+
+# PyTorch models
+session.download("/home/coder/workspace/checkpoint.pt", "./checkpoint.pt")
+
+# JSON configuration
+session.upload("./config.json", "/home/coder/workspace/config.json")
+
+# Text files
+session.upload("./requirements.txt", "/home/coder/workspace/requirements.txt")
+
+# Binary files
+session.upload("./image.png", "/home/coder/workspace/image.png")
+
+# Any file type works!
+session.upload("./data.parquet", "/home/coder/workspace/data.parquet")
+session.upload("./weights.h5", "/home/coder/workspace/weights.h5")
+```
+
+---
+
 ## Remote Functions (Decorator)
 
 Use the `@session.remote` decorator to run functions on the GPU:
@@ -707,6 +885,12 @@ GPUSession(
 | `stop()` | Stop the persistent session |
 | `set(name, value)` | Send variable to remote |
 | `get(name)` | Retrieve variable from remote |
+| `upload(local_path, remote_path, show_progress=True)` | Upload a file to remote session |
+| `download(remote_path, local_path, show_progress=True)` | Download a file from remote session |
+| `upload_folder(local_path, remote_path, exclude=None)` | Upload a folder to remote session |
+| `download_folder(remote_path, local_path, exclude=None)` | Download a folder from remote session |
+| `list_files(remote_path, pattern=None)` | List files in remote directory |
+| `file_exists(remote_path)` | Check if a file exists on remote |
 | `submit(code, name=None, job_type="python")` | Submit async job |
 | `jobs(status=None, limit=10)` | List jobs |
 | `gpu_info()` | Get GPU information |

{clouditia-1.2.4 → clouditia-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "clouditia"
-version = "1.2.4"
+version = "1.3.0"
 description = "Execute Python and Shell code on remote GPU sessions"
 readme = "README.md"
 license = {text = "MIT"}