voltsdk 0.1.0__tar.gz

voltsdk-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: voltsdk
+Version: 0.1.0
+Summary: Volt API SDK for scripting and notebooks
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: msgpack>=1.0.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: visualization
+Requires-Dist: vtk>=9.2.0; extra == "visualization"
+Provides-Extra: notebook
+Requires-Dist: vtk>=9.2.0; extra == "notebook"
+Requires-Dist: k3d>=2.16.0; extra == "notebook"
+
+# voltsdk
+
+Python SDK for interacting with the Volt API.
+
+## Installation
+
+```bash
+pip install voltsdk
+```
+
+Install visualization support with:
+
+```bash
+pip install "voltsdk[visualization]"
+```
+
+Install notebook support with:
+
+```bash
+pip install "voltsdk[notebook]"
+```
+
+## Usage
+
+```python
+from voltsdk import VoltClient
+
+client = VoltClient(
+    secret_key="your-secret-key",
+    base_url="https://api.example.com"
+)
+```
+

voltsdk-0.1.0/README.md

@@ -0,0 +1,33 @@
+# voltsdk
+
+Python SDK for interacting with the Volt API.
+
+## Installation
+
+```bash
+pip install voltsdk
+```
+
+Install visualization support with:
+
+```bash
+pip install "voltsdk[visualization]"
+```
+
+Install notebook support with:
+
+```bash
+pip install "voltsdk[notebook]"
+```
+
+## Usage
+
+```python
+from voltsdk import VoltClient
+
+client = VoltClient(
+    secret_key="your-secret-key",
+    base_url="https://api.example.com"
+)
+```
+

voltsdk-0.1.0/__init__.py

@@ -0,0 +1,4 @@
+from .client import VoltClient
+from .utils import msgpack_as_df, view_glb
+
+__all__ = ["VoltClient", "view_glb", "msgpack_as_df"]

voltsdk-0.1.0/client.py

@@ -0,0 +1,269 @@
+from typing import Any, Dict, Optional
+import os
+import requests
+import zipfile
+
+
+class VoltClient:
+    def __init__(
+        self,
+        secret_key: str,
+        base_url: Optional[str] = None,
+        timeout: int = 30
+    ) -> None:
+        if not secret_key:
+            raise ValueError('secret_key is required')
+
+        if not base_url:
+            raise ValueError('base_url is required')
+
+        self.secret_key = secret_key
+        self.base_url = base_url
+        self.timeout = timeout
+
+        self._secret_key_info: Optional[Dict[str, Any]] = None
+        self._team_id: Optional[str] = None
+
+        self.session = requests.Session()
+        self.session.headers.update({
+            'Authorization': f'Bearer {secret_key}',
+            'Accept': 'application/json'
+        })
+
+        self._setup_client()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None
+    ) -> Any:
+        response = self._send(
+            method,
+            path,
+            params=params
+        )
+
+        payload = response.json()
+        if payload.get('status') != 'success':
+            raise RuntimeError(payload.get('message') or 'Volt API request faield')
+
+        return payload.get('data')
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        stream: bool = False
+    ) -> requests.Response:
+        url = f"{self.base_url.rstrip('/')}/{path.lstrip('/')}"
+        response = self.session.request(
+            method=method,
+            url=url,
+            params=params,
+            timeout=self.timeout,
+            stream=stream
+        )
+
+        if response.status_code >= 400:
+            try:
+                payload = response.json()
+                message = payload.get('message') or response.text
+            except Exception:
+                message = response.text or response.reason
+
+            raise requests.HTTPError(
+                f'{response.status_code} {response.reason}: {message} ({response.url})',
+                response=response
+            )
+
+        return response
+
+    def _setup_client(self) -> Dict[str, Any]:
+        data = self._request('GET', '/team/secret-keys/me')
+
+        self._secret_key_info = data
+        self._team_id = data.get('team')
+        return data
+
+    def _resolve_download_filename(
+        self,
+        response: requests.Response,
+        fallback_name: str
+    ) -> str:
+        content_disposition = response.headers.get('Content-Disposition', '')
+        if 'filename=' not in content_disposition:
+            return fallback_name
+
+        filename = content_disposition.split('filename=')[-1].strip().strip('"').strip("'")
+        if not filename:
+            return fallback_name
+
+        return os.path.basename(filename)
+
+    def _download_stream(
+        self,
+        path: str,
+        fallback_name: str
+    ) -> str:
+        with self._send('GET', path, stream=True) as response:
+            downloads_dir = './downloads'
+            os.makedirs(downloads_dir, exist_ok=True)
+
+            filename = self._resolve_download_filename(response, fallback_name)
+            file_path = os.path.join(downloads_dir, filename)
+            total_bytes = int(response.headers.get('Content-Length', 0) or 0)
+            downloaded_bytes = 0
+
+            with open(file_path, 'wb') as file:
+                for chunk in response.iter_content(chunk_size=8192):
+                    if not chunk:
+                        continue
+
+                    file.write(chunk)
+                    downloaded_bytes += len(chunk)
+
+                    if total_bytes > 0:
+                        percent = (downloaded_bytes * 100) / total_bytes
+                        print(
+                            f'\rDownloading {filename}: {percent:.2f}% ({downloaded_bytes}/{total_bytes} bytes)',
+                            end='',
+                            flush=True
+                        )
+                    else:
+                        print(
+                            f'\rDownloading {filename}: {downloaded_bytes} bytes',
+                            end='',
+                            flush=True
+                        )
+
+            print()
+
+        return file_path
+
+    def _extract_zip_file(self, zip_path: str) -> str:
+        extract_dir = zip_path[:-4]
+        os.makedirs(extract_dir, exist_ok=True)
+
+        with zipfile.ZipFile(zip_path, 'r') as zip_ref:
+            zip_ref.extractall(extract_dir)
+
+        os.remove(zip_path)
+        return extract_dir
+
+    def _unzip_recursive(self, zip_path: str) -> str:
+        if not zip_path.lower().endswith('.zip'):
+            return zip_path
+
+        root_dir = self._extract_zip_file(zip_path)
+        while True:
+            zip_files = []
+            for current_root, _, files in os.walk(root_dir):
+                for file_name in files:
+                    if file_name.lower().endswith('.zip'):
+                        zip_files.append(os.path.join(current_root, file_name))
+
+            if not zip_files:
+                break
+
+            total_zip_files = len(zip_files)
+            for index, current_zip_path in enumerate(zip_files, start=1):
+                print(
+                    f'Extracting nested zip {index}/{total_zip_files}: {os.path.basename(current_zip_path)}',
+                    flush=True
+                )
+                self._extract_zip_file(current_zip_path)
+
+        return root_dir
+
+    def list_analyses(
+        self,
+        trajectory_id: str,
+        page: int = 1,
+        limit: int = 1000
+    ) -> Dict[str, Any]:
+        response = self._request(
+            'GET',
+            f'/analysis/{self._team_id}/trajectory/{trajectory_id}',
+            params={'page': page, 'limit': limit}
+        )
+
+        return response.get('data')
+
+    def list_analysis_results(
+        self,
+        analysis_id: str,
+        page: int = 1,
+        limit: int = 1000
+    ):
+        response = self._request(
+            'GET',
+            f'/plugin/{self._team_id}/listing/analysis/{analysis_id}',
+            params={'page': page, 'limit': limit}
+        )
+
+        return response.get('data')
+
+    def find_analysis_by_id(self, analysis_id: str):
+        return self._request(
+            'GET',
+            f'/analysis/{self._team_id}/{analysis_id}'
+        )
+
+    def _resolve_trajectory_id(self, analysis_id: str) -> str:
+        analysis = self.find_analysis_by_id(analysis_id)
+        trajectory_id = analysis.get('trajectory')
+        if not trajectory_id:
+            raise RuntimeError('analysis trajectory not found')
+
+        return trajectory_id
+
+    def download_analysis_artifacts(
+        self,
+        analysis_id: str,
+        unzip: bool = True
+    ):
+        zip_path = self._download_stream(
+            f'/plugin/{self._team_id}/exposure/export/analysis/{analysis_id}',
+            f'analysis-{analysis_id}-artifacts.zip'
+        )
+
+        if unzip:
+            return self._unzip_recursive(zip_path)
+
+        return zip_path
+
+    def download_plugin_results_file(
+        self,
+        analysis_id: str,
+        unzip: bool = True
+    ):
+        return self.download_analysis_artifacts(analysis_id, unzip=unzip)
+
+    def download_frame_glb(
+        self,
+        analysis_id: str,
+        timestep: int
+    ):
+        trajectory_id = self._resolve_trajectory_id(analysis_id)
+
+        return self._download_stream(
+            f'/trajectory/{self._team_id}/{trajectory_id}/{timestep}/{analysis_id}',
+            f'frame-{analysis_id}-{timestep}.glb'
+        )
+
+    def download_plugin_exported_glb(
+        self,
+        analysis_id: str,
+        exposure_id: str,
+        timestep: int
+    ):
+        trajectory_id = self._resolve_trajectory_id(analysis_id)
+
+        return self._download_stream(
+            f'/plugin/{self._team_id}/exposure/glb/{trajectory_id}/{analysis_id}/{exposure_id}/{timestep}',
+            f'plugin-glb-{analysis_id}-{exposure_id}-{timestep}.glb'
+        )

voltsdk-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "voltsdk"
+version = "0.1.0"
+description = "Volt API SDK for scripting and notebooks"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+  "msgpack>=1.0.0",
+  "pandas>=2.0.0",
+  "requests>=2.31.0"
+]
+
+[project.optional-dependencies]
+visualization = [
+  "vtk>=9.2.0"
+]
+notebook = [
+  "vtk>=9.2.0",
+  "k3d>=2.16.0"
+]
+
+[tool.setuptools]
+packages = ["voltsdk"]
+
+[tool.setuptools.package-dir]
+voltsdk = "."

voltsdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

voltsdk-0.1.0/utils.py

@@ -0,0 +1,154 @@
+from typing import Any, Optional
+import msgpack
+import os
+import pandas as pd
+
+
+def get_nested_value(data: Any, path: Optional[str]) -> Any:
+    if not path:
+        return data
+
+    current = data
+    for key in path.split('.'):
+        if not isinstance(current, dict):
+            return None
+
+        if key not in current:
+            return None
+
+        current = current[key]
+
+    return current
+
+
+def merged_chunked_value(target: Any, incoming: Any) -> Any:
+    if incoming is None:
+        return target
+
+    if target is None:
+        return incoming
+
+    if isinstance(target, list) and isinstance(incoming, list):
+        target.extend(incoming)
+        return target
+
+    if isinstance(target, dict) and isinstance(incoming, dict):
+        for key, incoming_value in incoming.items():
+            target_value = target.get(key)
+
+            if isinstance(target_value, list) and isinstance(incoming_value, list):
+                target_value.extend(incoming_value)
+            elif isinstance(target_value, dict) and isinstance(incoming_value, dict):
+                target[key] = merged_chunked_value(target_value, incoming_value)
+            else:
+                target[key] = incoming_value
+        return target
+
+    return incoming
+
+
+def is_columnar_dict(value: Any) -> bool:
+    if not isinstance(value, dict) or not value:
+        return False
+
+    lengths = []
+    for item in value.values():
+        if not isinstance(item, list):
+            return False
+        lengths.append(len(item))
+    return len(set(lengths)) == 1
+
+
+def msgpack_as_df(file_path: str, iterable_key: Optional[str] = None):
+    if not os.path.exists(file_path):
+        raise RuntimeError(f'file not found: {file_path}')
+
+    data = None
+    with open(file_path, 'rb') as file:
+        unpacker = msgpack.Unpacker(file, raw=False)
+        for message in unpacker:
+            chunk = get_nested_value(message, iterable_key)
+            data = merged_chunked_value(data, chunk)
+
+        if data is None:
+            return pd.DataFrame()
+
+        if isinstance(data, list) or is_columnar_dict(data):
+            return pd.DataFrame(data)
+
+        if isinstance(data, dict):
+            return pd.DataFrame([data])
+
+        return pd.DataFrame([{'value': data}])
+
+
+def view_glb(file_path: str):
+    if not os.path.exists(file_path):
+        raise RuntimeError(f'file not found: {file_path}')
+
+    try:
+        import vtk
+    except Exception as error:
+        raise RuntimeError(
+            'vtk is required to view GLB files. Install with: pip install "voltsdk[visualization]"'
+        ) from error
+
+    reader = vtk.vtkGLTFReader()
+    reader.SetFileName(file_path)
+    reader.Update()
+
+    in_notebook = False
+    try:
+        from IPython import get_ipython
+        shell = get_ipython()
+        in_notebook = shell is not None and shell.__class__.__name__ == 'ZMQInteractiveShell'
+    except Exception:
+        in_notebook = False
+
+    if in_notebook:
+        try:
+            import k3d
+        except Exception as error:
+            raise RuntimeError('k3d is required in notebook mode. Install with: pip install k3d') from error
+
+        plot = k3d.plot()
+        multi_block = reader.GetOutput()
+        iterator = multi_block.NewIterator()
+        iterator.InitTraversal()
+        while not iterator.IsDoneWithTraversal():
+            item = iterator.GetCurrentDataObject()
+            if item is not None:
+                plot += k3d.vtk_poly_data(item, color=0x222222)
+            iterator.GoToNextItem()
+
+        try:
+            from IPython.display import display as ipython_display
+            ipython_display(plot)
+        except Exception:
+            pass
+
+        return plot
+
+    mapper = vtk.vtkCompositePolyDataMapper2()
+    mapper.SetInputDataObject(reader.GetOutput())
+
+    actor = vtk.vtkActor()
+    actor.SetMapper(mapper)
+
+    renderer = vtk.vtkRenderer()
+    renderer.AddActor(actor)
+    renderer.SetBackground(0.07, 0.07, 0.07)
+
+    render_window = vtk.vtkRenderWindow()
+    render_window.AddRenderer(renderer)
+    render_window.SetSize(1200, 800)
+    render_window.SetWindowName(os.path.basename(file_path))
+
+    interactor = vtk.vtkRenderWindowInteractor()
+    interactor.SetRenderWindow(render_window)
+
+    render_window.Render()
+    interactor.Initialize()
+    interactor.Start()
+
+    return interactor

voltsdk-0.1.0/voltsdk.egg-info/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: voltsdk
+Version: 0.1.0
+Summary: Volt API SDK for scripting and notebooks
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: msgpack>=1.0.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: visualization
+Requires-Dist: vtk>=9.2.0; extra == "visualization"
+Provides-Extra: notebook
+Requires-Dist: vtk>=9.2.0; extra == "notebook"
+Requires-Dist: k3d>=2.16.0; extra == "notebook"
+
+# voltsdk
+
+Python SDK for interacting with the Volt API.
+
+## Installation
+
+```bash
+pip install voltsdk
+```
+
+Install visualization support with:
+
+```bash
+pip install "voltsdk[visualization]"
+```
+
+Install notebook support with:
+
+```bash
+pip install "voltsdk[notebook]"
+```
+
+## Usage
+
+```python
+from voltsdk import VoltClient
+
+client = VoltClient(
+    secret_key="your-secret-key",
+    base_url="https://api.example.com"
+)
+```
+

voltsdk-0.1.0/voltsdk.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+__init__.py
+client.py
+pyproject.toml
+utils.py
+./__init__.py
+./client.py
+./utils.py
+voltsdk.egg-info/PKG-INFO
+voltsdk.egg-info/SOURCES.txt
+voltsdk.egg-info/dependency_links.txt
+voltsdk.egg-info/requires.txt
+voltsdk.egg-info/top_level.txt

voltsdk-0.1.0/voltsdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

voltsdk-0.1.0/voltsdk.egg-info/requires.txt

@@ -0,0 +1,10 @@
+msgpack>=1.0.0
+pandas>=2.0.0
+requests>=2.31.0
+
+[notebook]
+vtk>=9.2.0
+k3d>=2.16.0
+
+[visualization]
+vtk>=9.2.0

voltsdk-0.1.0/voltsdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+voltsdk