wavesimpro 0.9.0__py3-none-any.whl

wavesimpro/client.py

@@ -0,0 +1,1475 @@
+"""
+Main client class for interacting with RayfosJobServer
+"""
+
+import os
+import logging
+from typing import Dict, List, Optional, Any, BinaryIO
+from pathlib import Path
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from .config import ClientConfig
+from .exceptions import (
+    RayfosAPIError,
+    AuthenticationError,
+    NotFoundError,
+    ValidationError,
+    ServerError,
+    ConfigurationError,
+)
+
+# Set up logger for the client
+logger = logging.getLogger(__name__)
+
+
+class RayfosClient:
+    """
+    Client for interacting with RayfosJobServer API
+    
+    This client supports both cloud and local deployment modes and provides
+    methods for managing projects, versions, files, and commands.
+    """
+    
+    def __init__(
+        self,
+        api_token: str,
+        server_url: str = "https://server.rayfos.com",
+        machine_service_url: Optional[str] = None,
+        timeout: int = 30,
+        verify_ssl: bool = True,
+        verify_ssl_machine_service: bool = True,
+    ):
+        """
+        Initialize the Rayfos API client
+        
+        Args:
+            api_token: User API token for authentication
+            server_url: Base URL of RayfosJobServer for project management
+            machine_service_url: Optional URL of RayfosMachineService for file uploads
+            timeout: Request timeout in seconds
+            verify_ssl: Whether to verify SSL certificates for server_url
+            verify_ssl_machine_service: Whether to verify SSL for machine_service_url
+        """
+        self.config = ClientConfig(
+            api_token=api_token,
+            server_url=server_url,
+            machine_service_url=machine_service_url,
+            timeout=timeout,
+            verify_ssl=verify_ssl,
+            verify_ssl_machine_service=verify_ssl_machine_service,
+        )
+        
+        # Create session with retry logic
+        self.session = self._create_session()
+    
+    @classmethod
+    def from_env(cls) -> "RayfosClient":
+        """
+        Create client from environment variables
+        
+        Environment variables:
+            RAYFOS_API_TOKEN: API token (required)
+            RAYFOS_SERVER_URL: Project server URL (optional, defaults to server.rayfos.com)
+            RAYFOS_MACHINE_SERVICE_URL: Machine service URL for file uploads (optional)
+        
+        Returns:
+            RayfosClient instance
+        """
+        config = ClientConfig.from_env()
+        return cls(
+            api_token=config.api_token,
+            server_url=config.server_url,
+            machine_service_url=config.machine_service_url,
+            timeout=config.timeout,
+            verify_ssl=config.verify_ssl,
+            verify_ssl_machine_service=config.verify_ssl_machine_service,
+        )
+    
+    def _create_session(self) -> requests.Session:
+        """Create requests session with retry logic and authentication"""
+        session = requests.Session()
+        
+        # Add retry logic
+        retry_strategy = Retry(
+            total=3,
+            backoff_factor=1,
+            status_forcelist=[429, 500, 502, 503, 504],
+            allowed_methods=["HEAD", "GET", "OPTIONS", "POST", "PUT", "DELETE"],
+        )
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        session.mount("http://", adapter)
+        session.mount("https://", adapter)
+        
+        # Set default headers with Bearer token authentication (industry standard)
+        # Works for both Firebase JWT tokens and RayfosJobServer API tokens
+        session.headers.update({
+            "Authorization": f"Bearer {self.config.api_token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        })
+        
+        return session
+    
+    def _handle_response(self, response: requests.Response) -> Any:
+        """
+        Handle API response and raise appropriate exceptions
+        
+        Args:
+            response: Response object from requests
+        
+        Returns:
+            Parsed JSON response
+        
+        Raises:
+            AuthenticationError: For 401 responses
+            NotFoundError: For 404 responses
+            ValidationError: For 400 responses
+            ServerError: For 5xx responses
+            RayfosAPIError: For other error responses
+        """
+        try:
+            response.raise_for_status()
+            
+            # Log response details for debugging
+            logger.debug(f"Response status: {response.status_code}, Content-Type: {response.headers.get('Content-Type')}")
+            
+            # Return None for 204 No Content
+            if response.status_code == 204:
+                logger.debug("Returning None for 204 No Content")
+                return None
+            
+            # Try to parse JSON response
+            try:
+                json_data = response.json()
+                logger.debug(f"Parsed JSON response with keys: {list(json_data.keys()) if isinstance(json_data, dict) else type(json_data)}")
+                return json_data
+            except ValueError:
+                logger.debug(f"Could not parse JSON, returning text (length: {len(response.text)})")
+                return response.text
+        
+        except requests.exceptions.HTTPError as e:
+            status_code = response.status_code
+            
+            # Try to get error message from response
+            try:
+                error_data = response.json()
+                message = error_data.get("message") or error_data.get("error") or str(e)
+            except ValueError:
+                message = response.text or str(e)
+            
+            # Raise specific exception based on status code
+            if status_code == 401:
+                raise AuthenticationError(message, status_code, response)
+            elif status_code == 404:
+                raise NotFoundError(message, status_code, response)
+            elif status_code == 400:
+                raise ValidationError(message, status_code, response)
+            elif status_code >= 500:
+                raise ServerError(message, status_code, response)
+            else:
+                raise RayfosAPIError(message, status_code, response)
+    
+    def _get(self, endpoint: str, params: Optional[Dict] = None) -> Any:
+        """Make GET request"""
+        url = self.config.get_api_url(endpoint)
+        logger.info(f"GET {url} [Cloud Service]")
+        response = self.session.get(
+            url,
+            params=params,
+            timeout=self.config.timeout,
+            verify=self.config.verify_ssl,
+        )
+        return self._handle_response(response)
+    
+    def _post(self, endpoint: str, data: Optional[Dict] = None, json: Optional[Dict] = None) -> Any:
+        """Make POST request"""
+        url = self.config.get_api_url(endpoint)
+        logger.info(f"POST {url} [Cloud Service]")
+        response = self.session.post(
+            url,
+            data=data,
+            json=json,
+            timeout=self.config.timeout,
+            verify=self.config.verify_ssl,
+        )
+        return self._handle_response(response)
+    
+    def _put(self, endpoint: str, data: Optional[Dict] = None, json: Optional[Dict] = None) -> Any:
+        """Make PUT request"""
+        url = self.config.get_api_url(endpoint)
+        logger.info(f"PUT {url} [Cloud Service]")
+        response = self.session.put(
+            url,
+            data=data,
+            json=json,
+            timeout=self.config.timeout,
+            verify=self.config.verify_ssl,
+        )
+        return self._handle_response(response)
+    
+    def _delete(self, endpoint: str) -> Any:
+        """Make DELETE request"""
+        url = self.config.get_api_url(endpoint)
+        logger.info(f"DELETE {url} [Cloud Service]")
+        response = self.session.delete(
+            url,
+            timeout=self.config.timeout,
+            verify=self.config.verify_ssl,
+        )
+        return self._handle_response(response)
+    
+    # ========================================================================
+    # PROJECT MANAGEMENT METHODS
+    # ========================================================================
+    
+    def get_projects(self) -> List[Dict[str, Any]]:
+        """
+        Get all projects for the authenticated user
+        
+        Returns:
+            List of project dictionaries with structure matching ProjectDto
+        
+        Example:
+            >>> projects = client.get_projects()
+            >>> for project in projects:
+            ...     print(f"{project['name']}: {len(project['versions'])} versions")
+        """
+        return self._get("/api/projects")
+    
+    def get_project(self, project_id: str) -> Dict[str, Any]:
+        """
+        Get a specific project by ID
+        
+        Args:
+            project_id: Project UUID
+        
+        Returns:
+            Project dictionary
+        """
+        return self._get(f"/api/projects/{project_id}")
+    
+    def create_project(
+        self,
+        name: str,
+        app: str,
+        description: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a new project
+        
+        Args:
+            name: Project name
+            app: Application type (e.g., "wavesim")
+            description: Optional project description
+        
+        Returns:
+            Created project dictionary
+        
+        Example:
+            >>> project = client.create_project(
+            ...     name="My Simulation",
+            ...     app="wavesim",
+            ...     description="Test simulation project"
+            ... )
+        """
+        data = {
+            "name": name,
+            "app": app,
+        }
+        if description:
+            data["description"] = description
+        
+        return self._post("/api/projects", json=data)
+    
+    def delete_project(self, project_id: str) -> bool:
+        """
+        Delete a project
+        
+        Args:
+            project_id: Project UUID
+        
+        Returns:
+            True if successful
+        """
+        self._delete(f"/api/projects/{project_id}")
+        return True
+    
+    # ========================================================================
+    # PROJECT VERSION METHODS
+    # ========================================================================
+    
+    def get_project_versions(self, project_id: str) -> List[Dict[str, Any]]:
+        """
+        Get all versions of a project
+        
+        Args:
+            project_id: Project UUID
+        
+        Returns:
+            List of version dictionaries
+        """
+        return self._get(f"/api/projects/{project_id}/versions")
+    
+    def get_project_version(self, project_id: str, version_id: str) -> Dict[str, Any]:
+        """
+        Get a specific version with full hierarchy (command and output files)
+        
+        This endpoint returns the complete ProjectVersionDtoV2 including:
+        - Command with OutputFiles metadata (FileMetadataDtoV2)
+        - ProjectVersionFiles with file metadata
+        - All version properties
+        
+        Args:
+            project_id: Project UUID
+            version_id: Version UUID
+        
+        Returns:
+            ProjectVersionDtoV2 dictionary with full hierarchy
+        
+        Example:
+            >>> version = client.get_project_version(project_id, version_id)
+            >>> if version.get('command') and version['command'].get('outputFiles'):
+            ...     for file in version['command']['outputFiles']:
+            ...         print(f"Output file: {file['originalFileName']}")
+        """
+        return self._get(f"/api/projects/{project_id}/versions/{version_id}")
+    
+    def create_project_version(
+        self,
+        project_id: str,
+        notes: str = "",
+        app_version: str = "1.0.0",
+        new_major_version: bool = False
+    ) -> Dict[str, Any]:
+        """
+        Create a new project version
+        
+        Args:
+            project_id: Project UUID
+            notes: Version notes
+            app_version: Target application version
+            new_major_version: Whether to increment major version (default: False for minor)
+        
+        Returns:
+            Created version dictionary
+        """
+        data = {
+            "Notes": notes,
+            "AppVersion": app_version,
+            "NewMajorVersion": new_major_version,
+        }
+        return self._post(f"/api/projects/{project_id}/versions", json=data)
+    
+    def delete_project_version(self, project_id: str, version_id: str) -> bool:
+        """
+        Delete a project version
+        
+        Args:
+            project_id: Project UUID
+            version_id: Version UUID
+        
+        Returns:
+            True if successful
+        """
+        self._delete(f"/api/projects/{project_id}/versions/{version_id}")
+        return True
+    
+    def update_project_properties(
+        self,
+        properties_id: str,
+        wavesim_properties: Dict[str, Any]
+    ) -> bool:
+        """
+        Update project version properties with complete WavesimProperties JSON
+        
+        Args:
+            properties_id: Properties UUID (from version.propertiesId)
+            wavesim_properties: Complete WavesimProperties dictionary
+        
+        Returns:
+            True if successful
+        
+        Example:
+            >>> # Get version to get properties_id
+            >>> version = client.get_project_version(project_id, version_id)
+            >>> properties_id = version['propertiesId']
+            >>> 
+            >>> # Build wavesim properties
+            >>> wavesim_props = create_wavesim_properties(...)
+            >>> 
+            >>> # Update properties on server
+            >>> client.update_project_properties(properties_id, wavesim_props)
+        """
+        import json
+        
+        # Wrap in ProjectVersionPropertiesDtoV2 structure
+        properties_dto = {
+            "Id": properties_id,
+            "JsonContent": json.dumps(wavesim_properties)
+        }
+        
+        self._post(f"/api/projects/{properties_id}/propertiesUpdate", json=properties_dto)
+        return True
+    
+    # ========================================================================
+    # FILE OPERATIONS
+    # ========================================================================
+    
+    def upload_file(
+        self,
+        project_id: str,
+        version_id: str,
+        file_path: str,
+        file_type: str = "input",
+        progress_callback: Optional[callable] = None
+    ) -> Dict[str, Any]:
+        """
+        Upload a file to a project version
+        
+        Args:
+            project_id: Project UUID
+            version_id: Version UUID
+            file_path: Path to the file to upload
+            file_type: Type of file ("input" or "output")
+            progress_callback: Optional callback function for upload progress
+        
+        Returns:
+            File metadata dictionary
+        
+        Example:
+            >>> def progress(bytes_sent, total_bytes):
+            ...     print(f"Uploaded {bytes_sent}/{total_bytes} bytes")
+            >>> 
+            >>> file_meta = client.upload_file(
+            ...     project_id="...",
+            ...     version_id="...",
+            ...     file_path="/path/to/file.gds",
+            ...     progress_callback=progress
+            ... )
+        """
+        file_path = Path(file_path)
+        
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+        
+        # Get file name and size
+        file_name = file_path.name
+        file_size = file_path.stat().st_size
+        
+        # Use machine service for file upload if configured
+        if self.config.machine_service_url:
+            return self._upload_file_machine_service(
+                project_id, version_id, file_path, file_type, progress_callback
+            )
+        else:
+            return self._upload_file_cloud(
+                project_id, version_id, file_path, file_type, progress_callback
+            )
+    
+    def _upload_file_cloud(
+        self,
+        project_id: str,
+        version_id: str,
+        file_path: Path,
+        file_type: str,
+        progress_callback: Optional[callable]
+    ) -> Dict[str, Any]:
+        """Upload file in cloud mode (via Azure Blob Storage)"""
+        # Step 1: Request SAS token from server
+        endpoint = "/api/files/upload/token"
+        params = {
+            "ProjectId": project_id,
+            "VersionId": version_id,
+            "FileName": file_path.name,
+            "FileType": file_type,
+            "ContentType": "application/octet-stream"
+        }
+        
+        sas_response = self._post(endpoint, json=params)
+        sas_url = sas_response.get("sasUrl") or sas_response.get("SasUrl")
+        blob_name = sas_response.get("blobName") or sas_response.get("BlobName")
+        
+        if not sas_url:
+            raise RayfosAPIError("Server did not return SAS URL")
+        
+        # Step 2: Upload directly to Azure Blob Storage
+        file_size = 0
+        with open(file_path, "rb") as f:
+            file_data = f.read()
+            file_size = len(file_data)
+            
+            headers = {
+                "x-ms-blob-type": "BlockBlob",
+            }
+            
+            # Upload file
+            upload_response = requests.put(
+                sas_url,
+                data=file_data,
+                headers=headers,
+                timeout=self.config.timeout * 10,  # Longer timeout for file upload
+            )
+            upload_response.raise_for_status()
+        
+        # Step 3: Notify server of completion
+        complete_endpoint = "/api/files/upload/complete"
+        complete_params = {
+            "FileId": blob_name,  # BlobName is used as FileId
+            "SizeInBytes": file_size
+        }
+        result = self._post(complete_endpoint, json=complete_params)
+        
+        # Add fileId to result for consistency with machine service response
+        if result and isinstance(result, dict):
+            result['fileId'] = blob_name
+            result['blobName'] = blob_name
+        
+        return result
+    
+    def _upload_file_machine_service(
+        self,
+        project_id: str,
+        version_id: str,
+        file_path: Path,
+        file_type: str,
+        progress_callback: Optional[callable]
+    ) -> Dict[str, Any]:
+        """Upload file via machine service"""
+        if not self.config.machine_service_url:
+            raise ConfigurationError("Machine service URL is not configured")
+        
+        # Upload via the machine service HTTP endpoint
+        # Correct endpoint: /api/files/projects/{projectId}/versions/{versionId}/upload
+        endpoint = f"/api/files/projects/{project_id}/versions/{version_id}/upload"
+        
+        with open(file_path, "rb") as f:
+            files = {
+                "file": (file_path.name, f, "application/octet-stream")
+            }
+            data = {
+                "fileType": file_type,
+            }
+            
+            # Remove Content-Type header to let requests set it with boundary
+            headers = dict(self.session.headers)
+            headers.pop("Content-Type", None)
+            
+            url = self.config.get_machine_service_url(endpoint)
+            logger.info(f"POST {url} [Machine Service]")
+            response = requests.post(
+                url,
+                files=files,
+                data=data,
+                headers=headers,
+                timeout=self.config.timeout * 10,  # Longer timeout for upload
+                verify=self.config.verify_ssl_machine_service,
+            )
+        
+        return self._handle_response(response)
+    
+    def download_file(
+        self,
+        project_id: str,
+        version_id: str,
+        file_id: str,
+        output_path: str,
+        command_id: Optional[str] = None,
+        progress_callback: Optional[callable] = None
+    ) -> str:
+        """
+        Download a file from a project version
+        
+        Args:
+            project_id: Project UUID
+            version_id: Version UUID
+            file_id: File UUID
+            output_path: Path where to save the downloaded file
+            command_id: Optional command ID (avoids re-fetching version for machine service)
+            progress_callback: Optional callback for download progress
+        
+        Returns:
+            Path to downloaded file
+        
+        Example:
+            >>> output = client.download_file(
+            ...     project_id="...",
+            ...     version_id="...",
+            ...     file_id="...",
+            ...     output_path="/path/to/output/file.vtk"
+            ... )
+        """
+        output_path = Path(output_path)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        
+        # Use machine service for file download if configured
+        if self.config.machine_service_url:
+            return self._download_file_machine_service(
+                project_id, version_id, file_id, output_path, command_id, progress_callback
+            )
+        else:
+            return self._download_file_cloud(
+                project_id, version_id, file_id, output_path, progress_callback
+            )
+    
+    def _download_file_cloud(
+        self,
+        project_id: str,
+        version_id: str,
+        file_id: str,
+        output_path: Path,
+        progress_callback: Optional[callable]
+    ) -> str:
+        """Download file in cloud mode (via Azure Blob Storage)"""
+        # Step 1: Request SAS token for download
+        # file_id is a blob name - URL-encode it for slashes
+        from urllib.parse import quote
+        encoded_blob_name = quote(file_id, safe='')
+        endpoint = f"/api/files/download/token/{encoded_blob_name}"
+        sas_response = self._get(endpoint)
+
+        # Server may return dict with sasUrl key, or URL string directly
+        if isinstance(sas_response, str):
+            sas_url = sas_response
+        elif isinstance(sas_response, dict):
+            sas_url = sas_response.get("sasUrl") or sas_response.get("SasUrl")
+        else:
+            sas_url = None
+
+        if not sas_url:
+            raise RayfosAPIError("Server did not return SAS URL for download")
+
+        # Step 2: Download from Azure Blob Storage
+        response = requests.get(sas_url, stream=True, timeout=self.config.timeout * 10)
+        response.raise_for_status()
+
+        # Write to file with progress tracking
+        total_size = int(response.headers.get("content-length", 0))
+        bytes_downloaded = 0
+
+        # Use larger chunk size (1MB) for better performance on local networks
+        chunk_size = 1024 * 1024  # 1MB chunks
+
+        with open(output_path, "wb", buffering=8*1024*1024) as f:  # 8MB buffer
+            for chunk in response.iter_content(chunk_size=chunk_size):
+                if chunk:
+                    f.write(chunk)
+                    bytes_downloaded += len(chunk)
+                    if progress_callback:
+                        progress_callback(bytes_downloaded, total_size)
+
+        return str(output_path)
+    
+    def _download_file_machine_service(
+        self,
+        project_id: str,
+        version_id: str,
+        file_id: str,
+        output_path: Path,
+        command_id: Optional[str],
+        progress_callback: Optional[callable]
+    ) -> str:
+        """Download file via machine service"""
+        if not self.config.machine_service_url:
+            raise ConfigurationError("Machine service URL is not configured")
+        
+        # Get commandId if not provided
+        if not command_id:
+            version = self.get_project_version(project_id, version_id)
+            if version.get('command') and version['command'].get('id'):
+                command_id = version['command']['id']
+            elif version.get('commandId'):
+                command_id = version['commandId']
+            else:
+                raise ConfigurationError("Version does not have an associated command")
+        
+        # Machine service endpoint: /api/files/commands/{commandId}/files/{fileId}/download
+        endpoint = f"/api/files/commands/{command_id}/files/{file_id}/download"
+        url = self.config.get_machine_service_url(endpoint)
+        logger.info(f"GET {url} [Machine Service]")
+        
+        response = self.session.get(
+            url,
+            stream=True,
+            timeout=self.config.timeout * 10,
+            verify=self.config.verify_ssl_machine_service,
+        )
+        response.raise_for_status()
+        
+        # Write to file
+        total_size = int(response.headers.get("content-length", 0))
+        bytes_downloaded = 0
+        
+        # Use larger chunk size (1MB) for better performance on local networks
+        chunk_size = 1024 * 1024  # 1MB chunks
+        
+        with open(output_path, "wb", buffering=8*1024*1024) as f:  # 8MB buffer
+            for chunk in response.iter_content(chunk_size=chunk_size):
+                if chunk:
+                    f.write(chunk)
+                    bytes_downloaded += len(chunk)
+                    if progress_callback:
+                        progress_callback(bytes_downloaded, total_size)
+        
+        return str(output_path)
+    
+    def download_file_data(
+        self,
+        project_id: str,
+        version_id: str,
+        file_id: str,
+        command_id: Optional[str] = None
+    ) -> bytes:
+        """
+        Download a file directly to memory (returns bytes)
+        
+        Args:
+            project_id: Project UUID
+            version_id: Version UUID
+            file_id: File UUID
+            command_id: Optional command ID (avoids re-fetching version for machine service)
+        
+        Returns:
+            File contents as bytes
+        
+        Example:
+            >>> data = client.download_file_data(project_id, version_id, file_id)
+            >>> # Use data directly without saving to disk
+            >>> field = read_binary_field(data, dimensions, 'Complex64')
+        """
+        if self.config.machine_service_url:
+            return self._download_file_data_machine_service(
+                project_id, version_id, file_id, command_id
+            )
+        else:
+            return self._download_file_data_cloud(
+                project_id, version_id, file_id
+            )
+    
+    def _download_file_data_cloud(
+        self,
+        project_id: str,
+        version_id: str,
+        file_id: str
+    ) -> bytes:
+        """Download file data in cloud mode (via Azure Blob Storage)"""
+        # Step 1: Request SAS token for download
+        # file_id is a blob name - URL-encode it for slashes
+        from urllib.parse import quote
+        encoded_blob_name = quote(file_id, safe='')
+        endpoint = f"/api/files/download/token/{encoded_blob_name}"
+        sas_response = self._get(endpoint)
+        if isinstance(sas_response, str):
+            sas_url = sas_response
+        elif isinstance(sas_response, dict):
+            sas_url = sas_response.get("sasUrl") or sas_response.get("SasUrl")
+        else:
+            sas_url = None
+
+        if not sas_url:
+            raise RayfosAPIError("Server did not return SAS URL for download")
+        
+        # Step 2: Download from Azure Blob Storage
+        response = requests.get(sas_url, timeout=self.config.timeout * 10)
+        response.raise_for_status()
+        
+        return response.content
+    
+    def _download_file_data_machine_service(
+        self,
+        project_id: str,
+        version_id: str,
+        file_id: str,
+        command_id: Optional[str]
+    ) -> bytes:
+        """Download file data via machine service"""
+        if not self.config.machine_service_url:
+            raise ConfigurationError("Machine service URL is not configured")
+        
+        # Get commandId if not provided
+        if not command_id:
+            version = self.get_project_version(project_id, version_id)
+            if version.get('command') and version['command'].get('id'):
+                command_id = version['command']['id']
+            elif version.get('commandId'):
+                command_id = version['commandId']
+            else:
+                raise ConfigurationError("Version does not have an associated command")
+        
+        # Machine service endpoint: /api/files/commands/{commandId}/files/{fileId}/download
+        endpoint = f"/api/files/commands/{command_id}/files/{file_id}/download"
+        url = self.config.get_machine_service_url(endpoint)
+        logger.info(f"GET {url} [Machine Service]")
+        
+        response = self.session.get(
+            url,
+            timeout=self.config.timeout * 10,
+            verify=self.config.verify_ssl_machine_service,
+        )
+        response.raise_for_status()
+        
+        return response.content
+    
+    def get_file_info(self, project_id: str, version_id: str, file_id: str) -> Dict[str, Any]:
+        """
+        Get file metadata
+        
+        Args:
+            project_id: Project UUID
+            version_id: Version UUID
+            file_id: File UUID
+        
+        Returns:
+            File metadata dictionary
+        """
+        return self._get(f"/api/projects/{project_id}/versions/{version_id}/files/{file_id}")
+    
+    # ========================================================================
+    # COMMAND OPERATIONS
+    # ========================================================================
+    
+    def get_commands(self) -> List[Dict[str, Any]]:
+        """
+        Get all commands for the authenticated user
+        
+        Returns:
+            List of command dictionaries
+        """
+        return self._get("/api/commands")
+    
+    def get_command(self, command_id: str) -> Dict[str, Any]:
+        """
+        Get a specific command
+        
+        Args:
+            command_id: Command UUID
+        
+        Returns:
+            Command dictionary
+        """
+        return self._get(f"/api/commands/{command_id}")
+    
+    def submit_command(
+        self,
+        project_id: str,
+        version_id: str,
+        command_type: str,
+        parameters: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        Submit a command for execution
+        
+        Args:
+            project_id: Project UUID
+            version_id: Version UUID
+            command_type: Type of command (e.g., "simulation", "voxelization")
+            parameters: Command parameters
+        
+        Returns:
+            Created command dictionary
+        """
+        data = {
+            "projectId": project_id,
+            "versionId": version_id,
+            "commandType": command_type,
+            "parameters": parameters or {},
+        }
+        return self._post("/api/commands", json=data)
+    
+    def cancel_command(self, command_id: str) -> bool:
+        """
+        Cancel a running command
+        
+        Args:
+            command_id: Command UUID
+        
+        Returns:
+            True if successful
+        """
+        self._post(f"/api/commands/{command_id}/cancel")
+        return True
+    
+    def create_command(
+        self,
+        project_id: str,
+        version_id: str,
+        engine_preference: str = 'Any',
+        use_gpu: Optional[bool] = None,
+    ) -> Dict[str, Any]:
+        """
+        Create a simulation command for a project version.
+
+        The command will read WavesimProperties from the project version's properties
+        that were previously saved using update_project_properties().
+
+        WORKFLOW:
+        1. First save properties: client.update_project_properties(properties_id, wavesim_props)
+        2. Then create command: client.create_command(project_id, version_id)
+        3. Command reads properties from database automatically
+
+        Args:
+            project_id: Project UUID
+            version_id: Version UUID
+            engine_preference: Engine to use — 'Any' (default), 'Python', or 'Cpp'.
+                'Any' lets the job server pick the best available machine.
+            use_gpu: GPU selection — None (auto, default), True (require GPU), False (force CPU).
+                Ignored when using a local machine service URL.
+
+        Returns:
+            Command status dictionary with the created command ID and status
+
+        Example:
+            >>> command = client.create_command(project_id, version_id,
+            ...                                 engine_preference='Python', use_gpu=True)
+            >>> print(f"Command created: {command['id']}")
+        """
+        if self.config.machine_service_url:
+            return self._create_command_machine_service(project_id, version_id)
+        else:
+            return self._create_command_cloud(project_id, version_id, engine_preference, use_gpu)
+    
+    def _create_command_machine_service(
+        self,
+        project_id: str,
+        version_id: str
+    ) -> Dict[str, Any]:
+        """Create command via RayfosMachineService (local mode)"""
+        if not self.config.machine_service_url:
+            raise ConfigurationError("Machine service URL is not configured")
+        
+        # Use the machine service command creation endpoint with route parameters
+        endpoint = f"/api/commands/{project_id}/{version_id}"
+        
+        url = f"{self.config.machine_service_url.rstrip('/')}{endpoint}"
+        logger.info(f"POST {url} [Machine Service]")
+        response = self.session.post(
+            url,
+            timeout=self.config.timeout,
+            verify=self.config.verify_ssl_machine_service,
+        )
+        return self._handle_response(response)
+    
+    def _create_command_cloud(
+        self,
+        project_id: str,
+        version_id: str,
+        engine_preference: str = 'Any',
+        use_gpu: Optional[bool] = None,
+    ) -> Dict[str, Any]:
+        """Create command via RayfosJobServer (cloud mode)"""
+        data: Dict[str, Any] = {}
+        if engine_preference and engine_preference != 'Any':
+            data['enginePreference'] = engine_preference
+        if use_gpu is not None:
+            data['useGpu'] = use_gpu
+        return self._post(f"/api/projects/{project_id}/versions/{version_id}/command", json=data)
+    
+    # ========================================================================
+    # COMMAND EXECUTION
+    # ========================================================================
+    
+    @staticmethod
+    def _parse_command_status(status_raw) -> str:
+        """
+        Parse commandStatus from C# enum (integer) to string name
+        
+        Args:
+            status_raw: Either integer enum value or string name
+        
+        Returns:
+            String name of the status
+        """
+        # CommandStatus enum from C# RayfosCommandModels
+        COMMAND_STATUS_MAP = {
+            0: 'New',
+            1: 'Assigned', 
+            2: 'SentToMachine',
+            3: 'SendToMachineForceCancellation',
+            4: 'SendToMachineForceDeleteTask',
+            5: 'RequestedForceCancellationInMachine',
+            6: 'RequestedForceStopTaskInMachine',
+            7: 'Cancelled',
+            8: 'Deleted',
+            9: 'Running',
+            10: 'Completed',
+            11: 'Failed',
+            12: 'FailedRemovedFromMachine'
+        }
+        
+        if isinstance(status_raw, int):
+            return COMMAND_STATUS_MAP.get(status_raw, f'Unknown({status_raw})')
+        return status_raw
+    
+    @staticmethod
+    def _parse_progress_data(progress_obj) -> Dict[str, Any]:
+        """
+        Parse CommandProgressDto with nested JSON strings
+        
+        Args:
+            progress_obj: CommandProgressDto dictionary with Status, Progress, Data fields
+        
+        Returns:
+            Dictionary with parsed progress information
+            {
+                'status': str,           # e.g., "Running"
+                'iteration': int,        # Current iteration
+                'percentage': float,     # Progress percentage (0-100)
+                'max_iterations': int,   # Total iterations
+                'residual_norm': float,  # Current residual (if available)
+                'threshold': float,      # Target threshold (if available)
+                'raw_progress': str,     # Original Progress JSON string
+                'raw_data': str          # Original Data JSON string
+            }
+        """
+        import json
+        
+        if not progress_obj:
+            return {}
+        
+        result = {
+            'status': progress_obj.get('status', 'Unknown'),
+            'raw_progress': progress_obj.get('progress', '{}'),
+            'raw_data': progress_obj.get('data', '{}')
+        }
+        
+        # Parse Progress JSON string: {"iteration": 83, "percentage": 100.0, "max_iterations": 10000}
+        try:
+            if isinstance(progress_obj.get('progress'), str):
+                progress_data = json.loads(progress_obj['progress'])
+                result['iteration'] = progress_data.get('iteration', 0)
+                result['percentage'] = progress_data.get('percentage', 0.0)
+                result['max_iterations'] = progress_data.get('max_iterations', 0)
+            elif isinstance(progress_obj.get('progress'), dict):
+                # Already parsed
+                result['iteration'] = progress_obj['progress'].get('iteration', 0)
+                result['percentage'] = progress_obj['progress'].get('percentage', 0.0)
+                result['max_iterations'] = progress_obj['progress'].get('max_iterations', 0)
+        except (json.JSONDecodeError, KeyError, TypeError):
+            pass
+        
+        # Parse Data JSON string: {"residual_norm": 9.74e-07, "residual_norm_threshold": 1e-06}
+        try:
+            if isinstance(progress_obj.get('data'), str):
+                data_obj = json.loads(progress_obj['data'])
+                result['residual_norm'] = data_obj.get('residual_norm')
+                result['threshold'] = data_obj.get('residual_norm_threshold')
+            elif isinstance(progress_obj.get('data'), dict):
+                # Already parsed
+                result['residual_norm'] = progress_obj['data'].get('residual_norm')
+                result['threshold'] = progress_obj['data'].get('residual_norm_threshold')
+        except (json.JSONDecodeError, KeyError, TypeError):
+            pass
+        
+        return result
+    
+    def get_command_status(self, command_id: str) -> Dict[str, Any]:
+        """
+        Get the current status of a command
+        
+        This method polls the command status to check its progress.
+        Always calls RayfosJobServer directly (regardless of local/cloud mode).
+        
+        Args:
+            command_id: Command UUID
+        
+        Returns:
+            CommandStatusDto dictionary with status, progress, and output files
+            Note: commandStatus is returned as integer from C#, use _parse_command_status() to convert
+        
+        Example:
+            >>> status = client.get_command_status("command-uuid")
+            >>> status_name = client._parse_command_status(status['commandStatus'])
+            >>> print(f"Status: {status_name}")
+            >>> print(f"Progress: {status.get('progressValue', 0)}%")
+            >>> if status['commandStatus'] == 10:  # Completed
+            ...     print(f"Output files: {status.get('outputFileIds', [])}")
+        """
+        # Always call RayfosJobServer directly for command status (user endpoint)
+        # Machine service is only for file operations, not command status
+        return self._get(f"/api/user/commands/{command_id}")
+    
+    def wait_for_command_completion(
+        self,
+        command_id: str,
+        poll_interval: float = 2.0,
+        timeout: Optional[float] = None,
+        progress_callback: Optional[callable] = None
+    ) -> Dict[str, Any]:
+        """
+        Wait for a command to complete (synchronous execution)
+        
+        This method polls the command status until it reaches a terminal state
+        (Completed, Failed, Cancelled). Useful for blocking until simulation finishes.
+        
+        Args:
+            command_id: Command UUID to wait for
+            poll_interval: Seconds between status checks (default: 2.0)
+            timeout: Maximum seconds to wait before raising TimeoutError (default: None - no timeout)
+            progress_callback: Optional callback(status_dict) called on each status check
+        
+        Returns:
+            Final CommandStatusDto dictionary when command completes
+        
+        Raises:
+            TimeoutError: If timeout is reached before completion
+            RayfosAPIError: If command fails or is cancelled
+        
+        Example:
+            >>> # Create command
+            >>> command = client.create_command(project_id, version_id, args_json)
+            >>> 
+            >>> # Wait for completion with progress updates
+            >>> def show_progress(status):
+            ...     print(f"Progress: {status.get('progressValue', 0)}% - {status.get('statusText', 'Running')}")
+            >>> 
+            >>> final_status = client.wait_for_command_completion(
+            ...     command['id'],
+            ...     progress_callback=show_progress,
+            ...     timeout=3600  # 1 hour timeout
+            ... )
+            >>> print(f"Command completed! Output files: {final_status.get('outputFileIds', [])}")
+        """
+        import time
+        
+        # CommandStatus enum values from C# (serialized as integers)
+        # New=0, Assigned=1, SentToMachine=2, etc.
+        COMMAND_STATUS = {
+            0: 'New',
+            1: 'Assigned', 
+            2: 'SentToMachine',
+            3: 'SendToMachineForceCancellation',
+            4: 'SendToMachineForceDeleteTask',
+            5: 'RequestedForceCancellationInMachine',
+            6: 'RequestedForceStopTaskInMachine',
+            7: 'Cancelled',
+            8: 'Deleted',
+            9: 'Running',
+            10: 'Completed',
+            11: 'Failed',
+            12: 'FailedRemovedFromMachine'
+        }
+        
+        # Terminal states (by integer value and name)
+        TERMINAL_STATUS_INTS = {7, 8, 10, 11, 12}  # Cancelled, Deleted, Completed, Failed, FailedRemovedFromMachine
+        TERMINAL_STATUS_NAMES = {'Cancelled', 'Deleted', 'Completed', 'Failed', 'FailedRemovedFromMachine'}
+        
+        start_time = time.time()
+        
+        while True:
+            # Check timeout
+            if timeout and (time.time() - start_time) > timeout:
+                raise TimeoutError(f"Command {command_id} did not complete within {timeout} seconds")
+            
+            # Get current status
+            status = self.get_command_status(command_id)
+            command_status_raw = status.get('commandStatus')
+            
+            # Handle both integer (from C# enum) and string formats
+            if isinstance(command_status_raw, int):
+                command_status = COMMAND_STATUS.get(command_status_raw, f'Unknown({command_status_raw})')
+                is_terminal = command_status_raw in TERMINAL_STATUS_INTS
+            else:
+                command_status = command_status_raw
+                is_terminal = command_status in TERMINAL_STATUS_NAMES
+            
+            # Call progress callback if provided
+            if progress_callback:
+                progress_callback(status)
+            
+            # Check if command reached terminal state
+            if is_terminal:
+                if command_status in ('Completed', 10):
+                    return status
+                elif command_status in ('Failed', 'FailedRemovedFromMachine', 11, 12):
+                    error_msg = status.get('statusText', 'Command failed')
+                    raise RayfosAPIError(f"Command {command_id} failed: {error_msg}")
+                elif command_status in ('Cancelled', 7):
+                    raise RayfosAPIError(f"Command {command_id} was cancelled")
+                elif command_status in ('Deleted', 8):
+                    raise RayfosAPIError(f"Command {command_id} was deleted")
+            
+            # Wait before next poll
+            time.sleep(poll_interval)
+    
+    def create_command_and_wait(
+        self,
+        project_id: str,
+        version_id: str,
+        local_machine_service_id: Optional[str] = None,
+        poll_interval: float = 2.0,
+        timeout: Optional[float] = None,
+        progress_callback: Optional[callable] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a command and wait for it to complete (synchronous execution)
+        
+        This is a convenience method that combines create_command() and 
+        wait_for_command_completion() into a single call.
+        
+        Args:
+            project_id: Project UUID
+            version_id: Version UUID
+            local_machine_service_id: Optional machine service ID for local execution
+            poll_interval: Seconds between status checks (default: 2.0)
+            timeout: Maximum seconds to wait (default: None - no timeout)
+            progress_callback: Optional callback(status_dict) for progress updates
+        
+        Returns:
+            Final CommandStatusDto dictionary when command completes
+        
+        Raises:
+            TimeoutError: If timeout is reached before completion
+            RayfosAPIError: If command fails or is cancelled
+        
+        Example:
+            >>> # First update properties
+            >>> client.update_project_properties(properties_id, wavesim_props)
+            >>> 
+            >>> # This will block until simulation completes
+            >>> result = client.create_command_and_wait(
+            ...     project_id="...",
+            ...     version_id="...",
+            ...     progress_callback=lambda s: print(f"Progress: {s.get('progressValue', 0)}%")
+            ... )
+            >>> 
+            >>> # Download output files
+            >>> for file_id in result.get('outputFileIds', []):
+            ...     client.download_file(project_id, version_id, file_id, f"output/{file_id}")
+        """
+        # Create the command (async)
+        command_status = self.create_command(project_id, version_id, local_machine_service_id)
+        command_id = command_status.get('id')
+        
+        if not command_id:
+            raise RayfosAPIError("Failed to create command: no command ID returned")
+        
+        # Wait for completion (sync)
+        return self.wait_for_command_completion(
+            command_id,
+            poll_interval=poll_interval,
+            timeout=timeout,
+            progress_callback=progress_callback
+        )
+    
+    def download_command_files(
+        self,
+        command_id: str,
+        output_dir: str,
+        file_pattern: Optional[str] = None
+    ) -> List[str]:
+        """
+        Download all output files from a completed command
+        
+        This method lists all files associated with a command and downloads them
+        to the specified directory. Only works with local machine service mode.
+        
+        Args:
+            command_id: Command UUID
+            output_dir: Directory where to save downloaded files
+            file_pattern: Optional glob pattern to filter files (e.g., "*.vtk")
+        
+        Returns:
+            List of paths to downloaded files
+        
+        Raises:
+            ConfigurationError: If machine service URL is not configured
+        
+        Example:
+            >>> # After command completes
+            >>> downloaded = client.download_command_files(
+            ...     command_id="...",
+            ...     output_dir="./results",
+            ...     file_pattern="*.vtk"  # Only download VTK files
+            ... )
+            >>> print(f"Downloaded {len(downloaded)} files")
+        """
+        if not self.config.machine_service_url:
+            raise ConfigurationError(
+                "download_command_files() only works with machine service URL configured"
+            )
+        
+        import fnmatch
+        from pathlib import Path
+        
+        output_path = Path(output_dir)
+        output_path.mkdir(parents=True, exist_ok=True)
+        
+        # List all files for this command
+        endpoint = f"/api/files/commands/{command_id}/files"
+        url = self.config.get_machine_service_url(endpoint)
+        headers = dict(self.session.headers)
+        logger.info(f"GET {url} [Machine Service]")
+        
+        response = requests.get(
+            url,
+            headers=headers,
+            timeout=self.config.timeout,
+            verify=self.config.verify_ssl_machine_service,
+        )
+        
+        files = self._handle_response(response)
+        
+        if not files:
+            return []
+        
+        # Filter files by pattern if provided
+        if file_pattern:
+            files = [f for f in files if fnmatch.fnmatch(f.get('fileName', ''), file_pattern)]
+        
+        # Download each file
+        downloaded_paths = []
+        for file_info in files:
+            file_id = file_info.get('blobName')
+            file_name = file_info.get('fileName', file_id)
+            
+            if not file_id:
+                continue
+            
+            # Download file by ID using the local files endpoint (requires commandId)
+            download_endpoint = f"/api/files/commands/{command_id}/files/{file_id}/download"
+            download_url = self.config.get_machine_service_url(download_endpoint)
+            logger.info(f"GET {download_url} [Machine Service] - Downloading {file_name}")
+            
+            download_response = requests.get(
+                download_url,
+                headers=headers,
+                stream=True,
+                timeout=self.config.timeout * 10,
+                verify=self.config.verify_ssl_machine_service,
+            )
+            
+            if download_response.status_code == 200:
+                file_path = output_path / file_name
+                # Use larger chunk size (1MB) for better performance
+                chunk_size = 1024 * 1024  # 1MB chunks
+                with open(file_path, 'wb', buffering=8*1024*1024) as f:  # 8MB buffer
+                    for chunk in download_response.iter_content(chunk_size=chunk_size):
+                        if chunk:
+                            f.write(chunk)
+                
+                downloaded_paths.append(str(file_path))
+        
+        return downloaded_paths
+    
+    # ========================================================================
+    # UTILITY METHODS
+    # ========================================================================
+    
+    def test_connection(self) -> bool:
+        """
+        Test the connection to the server
+        
+        Returns:
+            True if connection is successful
+        
+        Raises:
+            RayfosAPIError: If connection fails
+        """
+        try:
+            # Try to fetch projects as a connection test
+            self.get_projects()
+            return True
+        except Exception as e:
+            raise RayfosAPIError(f"Connection test failed: {str(e)}")
+    
+    def get_server_info(self) -> Dict[str, Any]:
+        """
+        Get server information
+        
+        Returns:
+            Server information dictionary
+        """
+        return {
+            "server_url": self.config.server_url,
+            "machine_service_url": self.config.machine_service_url,
+            "uses_machine_service": self.config.machine_service_url is not None,
+        }
+    
+    def get_file_preview(
+        self, project_id: str, version_id: str, file_id: str
+    ) -> Dict[str, Any]:
+        """
+        Get file preview/metadata for a file in a project version.
+
+        Used in cloud mode to look up file details (e.g., originalFileName)
+        when searching for output.bin among outputFileIds.
+
+        Args:
+            project_id: Project UUID
+            version_id: Version UUID
+            file_id: File UUID
+
+        Returns:
+            dict: File metadata including originalFileName, blobName, etc.
+        """
+        return self._get(
+            f"/api/Projects/{project_id}/versions/{version_id}/preview/{file_id}"
+        )
+
+    def list_command_files(self, command_id: str) -> List[Dict[str, Any]]:
+        """
+        List files produced by a command (machine service mode).
+
+        Args:
+            command_id: Command UUID
+
+        Returns:
+            list: File metadata dicts with fileName, blobName, etc.
+        """
+        if not self.config.machine_service_url:
+            raise ConfigurationError(
+                "machine_service_url is required for list_command_files"
+            )
+        url = f"{self.config.machine_service_url}/api/files/commands/{command_id}/files"
+        logger.info(f"GET {url} [Machine Service]")
+        response = self.session.get(
+            url,
+            timeout=self.config.timeout,
+            verify=self.config.verify_ssl_machine_service,
+        )
+        return self._handle_response(response)
+
+    def parse_command_status(self, status_value: int) -> str:
+        """
+        Parse commandStatus from C# enum (integer) to string name
+        
+        Args:
+            status_value: Integer status code from CommandStatusDto
+        
+        Returns:
+            Human-readable status name
+        
+        CommandStatus enum values from C# RayfosCommandModels:
+            0 = New
+            1 = Assigned
+            2 = SentToMachine
+            3 = SendToMachineForceCancellation
+            4 = SendToMachineForceDeleteTask
+            5 = RequestedForceCancellationInMachine
+            6 = RequestedForceStopTaskInMachine
+            7 = Cancelled
+            8 = Deleted
+            9 = Running
+            10 = Completed
+            11 = Failed
+            12 = FailedRemovedFromMachine
+        """
+        status_map = {
+            0: "New",
+            1: "Assigned",
+            2: "SentToMachine",
+            3: "SendToMachineForceCancellation",
+            4: "SendToMachineForceDeleteTask",
+            5: "RequestedForceCancellationInMachine",
+            6: "RequestedForceStopTaskInMachine",
+            7: "Cancelled",
+            8: "Deleted",
+            9: "Running",
+            10: "Completed",
+            11: "Failed",
+            12: "FailedRemovedFromMachine",
+        }
+        
+        return status_map.get(status_value, f"Unknown({status_value})")
+