voltsdk 2.2.2__tar.gz → 2.2.4__tar.gz

{voltsdk-2.2.2 → voltsdk-2.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voltsdk
-Version: 2.2.2
+Version: 2.2.4
 Summary: Python SDK for the Volt scientific computing platform
 License-Expression: MIT
 Requires-Python: >=3.10
@@ -65,6 +65,68 @@ client = VoltClient(
 )
 ```
 
+## Open In Volt
+
+Use the Volt web canvas as the viewer for local GLBs, GLB sequences, or
+existing Volt resources:
+
+```python
+from voltsdk import open_in_volt
+
+open_in_volt('out/frame.glb')
+open_in_volt({
+    0: 'out/frame-0000.glb',
+    5000: 'out/frame-5000.glb',
+    10000: 'out/frame-10000.glb',
+})
+```
+
+Resource helpers open the exact canvas route:
+
+```python
+trajectory.open_in_volt(timestep=5000)
+frame.open_in_volt()
+analysis.open_in_volt(timestep=5000)
+exposure.open_in_volt(5000)
+run.open_in_volt('dislocations')
+```
+
+For plugin runs, `open_in_volt(...)` auto-assembles supported `.json` and
+`.msgpack` exporter payloads into a sibling `.glb` when needed.
+
+For local files, VoltSDK serves them directly to `/canvas/glb` without creating
+fake analyses. In a Volt notebook it uses the Jupyter proxy; on a local machine
+it starts a tiny background file server. The browser still needs an authenticated
+Volt session. By default the viewer opens against `https://app.voltcloud.dev`;
+override it with `volt_url=...` or `VOLT_APP_URL` if needed.
+
+## SpatialAssembler
+
+Volt exporter payloads can also be rendered locally from Python:
+
+```python
+from voltsdk import SpatialAssembler, open_in_volt
+
+assembler = SpatialAssembler()
+glb_path = assembler.dislocations_glb(
+    'output/ptm-dxa_dislocations.json',
+    output_path='output/ptm-dxa_dislocations.glb',
+)
+
+open_in_volt(glb_path)
+```
+
+The Python API accepts either the full artifact file (`.json` or `.msgpack`) or
+the raw nested payload from `export.AtomisticExporter`, `export.MeshExporter`,
+or `export.DislocationExporter`.
+
+You can also let a `PluginRun` do the conversion directly:
+
+```python
+viewer_url = dxa_run.open_in_volt('dislocations', open_browser=False)
+mesh_glb = dxa_run.glb('defect_mesh')
+```
+
 ## Plugin hub
 
 VoltSDK ships a Hugging Face-style plugin hub. Plugins live in a static
@@ -80,10 +142,10 @@ ptm = hub.get("voltlabs@polyhedral-template-matching")
 result = ptm.run(
     "frame.dump",
     output_base="out/frame",
-    crystalStructure="FCC",
+    crystal_structure="FCC",
     rmsd=0.1,
 )
-print(result.artifact("annotatedDump"))
+print(result.path("annotated.dump"))
 ```
 
 The same hub is exposed on an authenticated client via `client.plugins`.
@@ -129,13 +191,12 @@ The hub expects a static index plus per-platform bundles:
         "publisher": "voltlabs",
         "latest": "1.0.0",
         "versions": {
-          "1.0.0": {
-            "linux-x86_64": {
-              "url": "opendxa/1.0.0/linux-x86_64.tar.zst",
-              "sha256": "..."
+            "1.0.0": {
+              "linux-x86_64": {
+                "url": "opendxa/1.0.0/linux-x86_64.tar.zst"
+              }
             }
           }
-        }
       }
     }
   }

{voltsdk-2.2.2 → voltsdk-2.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "voltsdk"
-version = "2.2.2"
+version = "2.2.4"
 description = "Python SDK for the Volt scientific computing platform"
 readme = "voltsdk/README.md"
 requires-python = ">=3.10"

voltsdk-2.2.4/tests/test_registry.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import json
+import tarfile
+import tempfile
+import unittest
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from voltsdk.plugins.registry import PluginRegistry
+
+
+def _write_bundle(path: Path) -> None:
+    with tempfile.TemporaryDirectory() as bundle_tmp:
+        root = Path(bundle_tmp)
+        bin_dir = root / 'bin'
+        bin_dir.mkdir(parents=True, exist_ok=True)
+        executable = bin_dir / 'demo-plugin'
+        executable.write_text('#!/bin/sh\nexit 0\n', encoding='utf-8')
+        with tarfile.open(path, 'w:gz') as archive:
+            archive.add(bin_dir, arcname='bin')
+
+
+class PluginRegistryTests(unittest.TestCase):
+    def test_install_ignores_sha256_metadata(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            bundle_path = root / 'demo-plugin-1.0.0-linux-x86_64.tgz'
+            _write_bundle(bundle_path)
+
+            index = {
+                'plugins': {
+                    'voltlabs': {
+                        'demo-plugin': {
+                            'publisher': 'voltlabs',
+                            'latest': '1.0.0',
+                            'versions': {
+                                '1.0.0': {
+                                    'linux-x86_64': {
+                                        'url': bundle_path.name,
+                                        'sha256': 'definitely-wrong',
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            }
+            index_path = root / 'index.json'
+            index_path.write_text(json.dumps(index), encoding='utf-8')
+
+            registry = PluginRegistry(
+                url=index_path.as_uri(),
+                cache_dir=root / 'cache',
+                platform_tag='linux-x86_64',
+            )
+
+            installed = registry.install('voltlabs@demo-plugin')
+
+            self.assertTrue(installed.is_dir())
+            self.assertTrue((installed / 'bin' / 'demo-plugin').is_file())
+
+
+if __name__ == '__main__':
+    unittest.main()

voltsdk-2.2.4/tests/test_spatial.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import json
+import tempfile
+import unittest
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from voltsdk.plugins.plugin import PluginRun
+from voltsdk.spatial import SpatialAssembler
+
+
+def _sample_dislocation_payload() -> dict:
+    return {
+        'export': {
+            'DislocationExporter': {
+                'segments': [
+                    {
+                        'points': [
+                            [0.0, 0.0, 0.0],
+                            [1.0, 0.0, 0.0],
+                            [1.0, 1.0, 0.0],
+                        ],
+                        'burgers': {
+                            'vector': [0.5, 0.5, 0.5],
+                        },
+                    },
+                ],
+            },
+        },
+    }
+
+
+class SpatialAssemblerTests(unittest.TestCase):
+    def test_glb_infers_dislocation_export_from_json(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            payload_path = root / 'dislocations.json'
+            output_path = root / 'dislocations.glb'
+            payload_path.write_text(json.dumps(_sample_dislocation_payload()), encoding='utf-8')
+
+            result = SpatialAssembler().glb(payload_path, output_path=output_path)
+
+            self.assertEqual(result, output_path)
+            self.assertTrue(output_path.is_file())
+            self.assertEqual(output_path.read_bytes()[:4], b'glTF')
+
+    def test_plugin_run_glb_writes_sibling_glb(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            payload_path = root / 'output_dislocations.json'
+            payload_path.write_text(json.dumps(_sample_dislocation_payload()), encoding='utf-8')
+
+            run = PluginRun(
+                command=[],
+                returncode=0,
+                stdout='',
+                stderr='',
+                output_base=root / 'output',
+                artifacts={
+                    'dislocations': payload_path,
+                    'dislocations.json': payload_path,
+                },
+            )
+
+            result = run.glb('dislocations')
+
+            self.assertEqual(result, root / 'output_dislocations.glb')
+            self.assertTrue(result.is_file())
+            self.assertEqual(result.read_bytes()[:4], b'glTF')
+
+
+if __name__ == '__main__':
+    unittest.main()

{voltsdk-2.2.2 → voltsdk-2.2.4}/voltsdk/README.md

@@ -41,6 +41,68 @@ client = VoltClient(
 )
 ```
 
+## Open In Volt
+
+Use the Volt web canvas as the viewer for local GLBs, GLB sequences, or
+existing Volt resources:
+
+```python
+from voltsdk import open_in_volt
+
+open_in_volt('out/frame.glb')
+open_in_volt({
+    0: 'out/frame-0000.glb',
+    5000: 'out/frame-5000.glb',
+    10000: 'out/frame-10000.glb',
+})
+```
+
+Resource helpers open the exact canvas route:
+
+```python
+trajectory.open_in_volt(timestep=5000)
+frame.open_in_volt()
+analysis.open_in_volt(timestep=5000)
+exposure.open_in_volt(5000)
+run.open_in_volt('dislocations')
+```
+
+For plugin runs, `open_in_volt(...)` auto-assembles supported `.json` and
+`.msgpack` exporter payloads into a sibling `.glb` when needed.
+
+For local files, VoltSDK serves them directly to `/canvas/glb` without creating
+fake analyses. In a Volt notebook it uses the Jupyter proxy; on a local machine
+it starts a tiny background file server. The browser still needs an authenticated
+Volt session. By default the viewer opens against `https://app.voltcloud.dev`;
+override it with `volt_url=...` or `VOLT_APP_URL` if needed.
+
+## SpatialAssembler
+
+Volt exporter payloads can also be rendered locally from Python:
+
+```python
+from voltsdk import SpatialAssembler, open_in_volt
+
+assembler = SpatialAssembler()
+glb_path = assembler.dislocations_glb(
+    'output/ptm-dxa_dislocations.json',
+    output_path='output/ptm-dxa_dislocations.glb',
+)
+
+open_in_volt(glb_path)
+```
+
+The Python API accepts either the full artifact file (`.json` or `.msgpack`) or
+the raw nested payload from `export.AtomisticExporter`, `export.MeshExporter`,
+or `export.DislocationExporter`.
+
+You can also let a `PluginRun` do the conversion directly:
+
+```python
+viewer_url = dxa_run.open_in_volt('dislocations', open_browser=False)
+mesh_glb = dxa_run.glb('defect_mesh')
+```
+
 ## Plugin hub
 
 VoltSDK ships a Hugging Face-style plugin hub. Plugins live in a static
@@ -56,10 +118,10 @@ ptm = hub.get("voltlabs@polyhedral-template-matching")
 result = ptm.run(
     "frame.dump",
     output_base="out/frame",
-    crystalStructure="FCC",
+    crystal_structure="FCC",
     rmsd=0.1,
 )
-print(result.artifact("annotatedDump"))
+print(result.path("annotated.dump"))
 ```
 
 The same hub is exposed on an authenticated client via `client.plugins`.
@@ -105,13 +167,12 @@ The hub expects a static index plus per-platform bundles:
         "publisher": "voltlabs",
         "latest": "1.0.0",
         "versions": {
-          "1.0.0": {
-            "linux-x86_64": {
-              "url": "opendxa/1.0.0/linux-x86_64.tar.zst",
-              "sha256": "..."
+            "1.0.0": {
+              "linux-x86_64": {
+                "url": "opendxa/1.0.0/linux-x86_64.tar.zst"
+              }
             }
           }
-        }
       }
     }
   }

{voltsdk-2.2.2 → voltsdk-2.2.4}/voltsdk/__init__.py

@@ -35,7 +35,7 @@ from .plugins import (
 )
 from .native import root as native_root
 
-__version__ = "2.2.2"
+__version__ = "2.2.4"
 
 __all__ = [
     "VoltClient",
@@ -47,6 +47,8 @@ __all__ = [
     "VoltPermissionError",
     "VoltTimeoutError",
     "msgpack_as_df",
+    "open_in_volt",
+    "SpatialAssembler",
     "view_glb",
     "Plugin",
     "PluginError",
@@ -69,6 +71,16 @@ def __getattr__(name: str):
 
         globals()[name] = msgpack_as_df
         return msgpack_as_df
+    if name == "open_in_volt":
+        from .viewer import open_in_volt
+
+        globals()[name] = open_in_volt
+        return open_in_volt
+    if name == "SpatialAssembler":
+        from .spatial import SpatialAssembler
+
+        globals()[name] = SpatialAssembler
+        return SpatialAssembler
     if name == "view_glb":
         from .integrations.glb import view_glb
 

{voltsdk-2.2.2 → voltsdk-2.2.4}/voltsdk/plugins/errors.py

@@ -10,4 +10,4 @@ class PluginNotFoundError(PluginError):
 
 
 class PluginVerificationError(PluginError):
-    """Raised when a downloaded bundle fails sha256 verification."""
+    """Reserved for plugin bundle validation failures."""

{voltsdk-2.2.2 → voltsdk-2.2.4}/voltsdk/plugins/plugin.py

@@ -34,6 +34,57 @@ class PluginRun:
                 return artifact
         return None
 
+    def path(self, name: str) -> Path:
+        artifact = self.artifact(name)
+        if artifact is not None:
+            return artifact
+        available = ', '.join(sorted(self.artifacts)) or '<none>'
+        raise PluginError(f'Artifact {name!r} not found. Available artifacts: {available}.')
+
+    def df(self, name: str, key: str | None = None):
+        path = self.path(name)
+        suffix = path.suffix.lower()
+        if suffix == '.msgpack':
+            from ..io.msgpack import msgpack_as_df
+
+            return msgpack_as_df(str(path), key)
+        if suffix == '.json':
+            return _json_df(path, key)
+        raise PluginError(f'Artifact {path.name!r} is not a supported dataframe source.')
+
+    def glb(
+        self,
+        name: str,
+        *,
+        output_path: str | os.PathLike[str] | None = None,
+        exporter: str | None = None,
+        **options: Any,
+    ) -> Path:
+        from ..spatial import SpatialAssembler
+
+        path = self.path(name)
+        if _is_glb_artifact(path):
+            return path
+
+        target = Path(output_path).expanduser().resolve() if output_path else _default_glb_output_path(path)
+        result = SpatialAssembler().glb(path, output_path=target, exporter=exporter, **options)
+        if not isinstance(result, Path):
+            raise PluginError('SpatialAssembler did not return a file path.')
+        return result
+
+    def open_in_volt(
+        self,
+        name: str,
+        *,
+        volt_url: str | None = None,
+        open_browser: bool = True,
+    ) -> str:
+        from ..viewer import open_in_volt
+
+        path = self.path(name)
+        source = path if _is_glb_artifact(path) else self.glb(name)
+        return open_in_volt(source, volt_url=volt_url, open_browser=open_browser)
+
 
 class Plugin:
     """A single plugin instance backed by a downloaded bundle.
@@ -75,7 +126,7 @@ class Plugin:
     ) -> PluginRun:
         config = _prepare_config({**self.options, **options})
         input_path = Path(input_file).expanduser().resolve()
-        output = Path(output_base).expanduser() if output_base else input_path.with_suffix("")
+        output = Path(output_base).expanduser().resolve() if output_base else input_path.with_suffix("")
         output.parent.mkdir(parents=True, exist_ok=True)
 
         command, completed = self._run_subprocess(
@@ -271,6 +322,51 @@ def _canonical_artifact_name(prefix: str, filename: str) -> str:
     return filename
 
 
+def _is_glb_artifact(path: Path) -> bool:
+    suffix = path.suffix.lower()
+    return suffix in {'.glb', '.gltf'} or path.name.lower().endswith('.glb.zst')
+
+
+def _default_glb_output_path(path: Path) -> Path:
+    suffix = path.suffix.lower()
+    if suffix:
+        return path.with_suffix('.glb')
+    return path.with_name(f'{path.name}.glb')
+
+
+def _json_df(path: Path, key: str | None):
+    import pandas as pd
+
+    from ..io.msgpack import get_nested_value
+
+    with path.open('r', encoding='utf-8') as fh:
+        data = get_nested_value(json.load(fh), key)
+    return _data_as_df(data, pd)
+
+
+def _data_as_df(data: Any, pd):
+    if data is None:
+        return pd.DataFrame()
+    if isinstance(data, list):
+        return pd.DataFrame(data)
+    if _is_columnar_dict(data):
+        return pd.DataFrame(data)
+    if isinstance(data, dict):
+        return pd.DataFrame([data])
+    return pd.DataFrame([{'value': data}])
+
+
+def _is_columnar_dict(value: Any) -> bool:
+    if not isinstance(value, dict) or not value:
+        return False
+    lengths: list[int] = []
+    for item in value.values():
+        if not isinstance(item, list):
+            return False
+        lengths.append(len(item))
+    return len(set(lengths)) == 1
+
+
 def _env(root: Path) -> dict[str, str]:
     env = os.environ.copy()
     plugin_bin_dir = root / "bin"

{voltsdk-2.2.2 → voltsdk-2.2.4}/voltsdk/plugins/registry.py

@@ -11,8 +11,7 @@ Index format (``GET <registry>/index.json``)::
             "versions": {
               "1.0.0": {
                 "linux-x86_64": {
-                  "url": "opendxa/1.0.0/linux-x86_64.tar.zst",
-                  "sha256": "..."
+                  "url": "opendxa/1.0.0/linux-x86_64.tar.zst"
                 }
               }
             }
@@ -32,7 +31,6 @@ Layout inside a bundle (after extraction)::
 
 from __future__ import annotations
 
-import hashlib
 import os
 import platform
 import shutil
@@ -43,7 +41,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
-from .errors import PluginNotFoundError, PluginVerificationError
+from .errors import PluginNotFoundError
 
 DEFAULT_REGISTRY_URL = "https://server.voltcloud.dev/plugin-registry"
 INDEX_PATH = "index.json"
@@ -56,7 +54,6 @@ class BundleRef:
     version: str
     platform: str
     url: str
-    sha256: str
 
 
 class PluginRegistry:
@@ -121,7 +118,6 @@ class PluginRegistry:
             version=version,
             platform=self.platform_tag,
             url=str(platform_entry["url"]),
-            sha256=str(platform_entry.get("sha256", "")),
         )
 
     # ------------------------------------------------------------------
@@ -135,14 +131,6 @@ class PluginRegistry:
             return target
 
         archive = self._fetch(ref.url, f"{ref.key}-{ref.version}-{ref.platform}")
-        if ref.sha256:
-            actual = _sha256(archive)
-            if actual != ref.sha256:
-                archive.unlink(missing_ok=True)
-                raise PluginVerificationError(
-                    f"sha256 mismatch for {ref.key}@{ref.version}: expected {ref.sha256}, got {actual}."
-                )
-
         if target.exists():
             shutil.rmtree(target)
         target.mkdir(parents=True, exist_ok=True)
@@ -239,14 +227,6 @@ def _is_absolute(url: str) -> bool:
     return urllib.parse.urlparse(url).scheme in {"http", "https", "file"}
 
 
-def _sha256(path: Path) -> str:
-    hasher = hashlib.sha256()
-    with path.open("rb") as fh:
-        for chunk in iter(lambda: fh.read(1 << 20), b""):
-            hasher.update(chunk)
-    return hasher.hexdigest()
-
-
 def _extract(archive: Path, target: Path) -> None:
     if archive.suffixes[-2:] == [".tar", ".zst"]:
         import zstandard

{voltsdk-2.2.2 → voltsdk-2.2.4}/voltsdk/resources/analyses.py

@@ -101,6 +101,23 @@ class Analysis(BaseResource):
             return self._client.unzip_recursive(zip_path)
         return zip_path
 
+    def open_in_volt(
+        self,
+        *,
+        timestep: int | None = None,
+        volt_url: str | None = None,
+        open_browser: bool = True,
+    ) -> str:
+        from voltsdk.viewer import open_canvas_view
+
+        return open_canvas_view(
+            trajectory_id=self.trajectory_id,
+            analysis_id=self.id,
+            timestep=timestep,
+            volt_url=volt_url,
+            open_browser=open_browser,
+        )
+
 
 class AnalysisCollection(BaseCollection['Analysis']):
     """Paginated collection of analyses.

{voltsdk-2.2.2 → voltsdk-2.2.4}/voltsdk/resources/exposures.py

@@ -101,6 +101,28 @@ class Exposure(BaseResource):
             dest=dest,
         )
 
+    def open_in_volt(
+        self,
+        timestep: int,
+        *,
+        volt_url: str | None = None,
+        open_browser: bool = True,
+    ) -> str:
+        from voltsdk.viewer import open_canvas_view
+
+        trajectory_id = self._get('trajectory', '')
+        if not trajectory_id:
+            raise ValueError('Exposure does not include a trajectory ID.')
+
+        return open_canvas_view(
+            trajectory_id=trajectory_id,
+            analysis_id=self.analysis_id,
+            exposure_id=self.id,
+            timestep=timestep,
+            volt_url=volt_url,
+            open_browser=open_browser,
+        )
+
 
 class ExposureCollection(BaseCollection['Exposure']):
     """Paginated collection of exposures for an analysis."""

{voltsdk-2.2.2 → voltsdk-2.2.4}/voltsdk/resources/frames.py

@@ -105,6 +105,23 @@ class Frame:
             dest=dest,
         )
 
+    def open_in_volt(
+        self,
+        analysis_id: str = 'default',
+        *,
+        volt_url: str | None = None,
+        open_browser: bool = True,
+    ) -> str:
+        from voltsdk.viewer import open_canvas_view
+
+        return open_canvas_view(
+            trajectory_id=self._trajectory_id,
+            analysis_id=analysis_id,
+            timestep=self.timestep,
+            volt_url=volt_url,
+            open_browser=open_browser,
+        )
+
     # ------------------------------------------------------------------
     # OVITO integration
     # ------------------------------------------------------------------

{voltsdk-2.2.2 → voltsdk-2.2.4}/voltsdk/resources/trajectories.py

@@ -95,6 +95,24 @@ class Trajectory(BaseResource):
             dest=dest,
         )
 
+    def open_in_volt(
+        self,
+        *,
+        analysis_id: str | None = None,
+        timestep: int | None = None,
+        volt_url: str | None = None,
+        open_browser: bool = True,
+    ) -> str:
+        from voltsdk.viewer import open_canvas_view
+
+        return open_canvas_view(
+            trajectory_id=self.id,
+            analysis_id=analysis_id,
+            timestep=timestep,
+            volt_url=volt_url,
+            open_browser=open_browser,
+        )
+
     # ------------------------------------------------------------------
     # Plotting
     # ------------------------------------------------------------------