sharedots 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,107 @@
1
+ Metadata-Version: 2.4
2
+ Name: sharedots
3
+ Version: 0.1.0
4
+ Summary: Universal Distributed Compute Network — Python SDK & Remote Execution
5
+ Author: Sharedots Team
6
+ License: MIT
7
+ Classifier: Programming Language :: Python :: 3
8
+ Classifier: Topic :: System :: Distributed Computing
9
+ Requires-Python: >=3.9
10
+ Description-Content-Type: text/markdown
11
+ Provides-Extra: dev
12
+ Requires-Dist: cloudpickle>=3.0.0; extra == "dev"
13
+ Requires-Dist: numpy>=1.24.0; extra == "dev"
14
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
15
+ Requires-Dist: pytest-xdist>=3.5.0; extra == "dev"
16
+ Dynamic: requires-python
17
+
18
+ # Sharedots Python SDK (`sharedots`)
19
+
20
+ Universal Distributed Compute Network — Python SDK & Remote Execution Engine.
21
+
22
+ The Sharedots Python SDK provides an intuitive, high-performance distributed computing interface with zero-boilerplate remote function execution. It seamlessly connects with the native Sharedots Coordinator and Rust worker daemons over Tailscale mesh networks or local subnets.
23
+
24
+ ---
25
+
26
+ ## 🚀 Quickstart
27
+
28
+ ### 1. Connect to a Compute Room
29
+
30
+ ```python
31
+ import sharedots as sd
32
+
33
+ # Connect to an existing room (e.g. over Tailscale or localhost)
34
+ client = sd.Client(
35
+ coordinator="http://100.82.14.30:4000",
36
+ room_id="room-alpha-123",
37
+ token="secret-token-xyz"
38
+ )
39
+
40
+ # Or create a new room directly:
41
+ room = client.create_room(name="my-mesh-room")
42
+ ```
43
+
44
+ ### 2. Distribute Functions with `@client.remote`
45
+
46
+ Decorate any Python function to execute across remote cluster nodes:
47
+
48
+ ```python
49
+ import numpy as np
50
+ import sharedots as sd
51
+
52
+ client = sd.Client(coordinator="http://localhost:4000", room_id="room-1", token="secret")
53
+
54
+ @client.remote(cpu=2, memory="1GB", gpu=True)
55
+ def matrix_dot(a, b):
56
+ # Runs remotely on a cluster worker node
57
+ return np.dot(a, b)
58
+
59
+ # Dispatches task across the cluster and immediately returns a Future
60
+ future = matrix_dot(np.eye(100), np.eye(100))
61
+
62
+ # Await result
63
+ result = future.result(timeout=30)
64
+ print("Computed result:", result)
65
+ ```
66
+
67
+ ### 3. Parallel Sharded Batch Processing with `.map()`
68
+
69
+ Distribute array slices or parameter sweeps across all available worker nodes in a single job:
70
+
71
+ ```python
72
+ @client.remote(cpu=1, memory="512MB")
73
+ def evaluate_trial(trial_id, parameter):
74
+ import time
75
+ # Simulate simulation / training trial
76
+ return {"trial": trial_id, "score": parameter ** 2}
77
+
78
+ # Automatically shards tasks across all cluster workers in parallel:
79
+ trials = [(i, i * 0.1) for i in range(20)]
80
+ results = evaluate_trial.map(trials)
81
+
82
+ print("All trials completed:", results)
83
+ ```
84
+
85
+ ### 4. Gather Multiple Futures
86
+
87
+ ```python
88
+ futures = [matrix_dot(A_i, B) for A_i in slices]
89
+ results = sd.gather(futures)
90
+ ```
91
+
92
+ ### 5. Local Debugging with `.local()`
93
+
94
+ Test functions locally in your process without sending them to the network:
95
+
96
+ ```python
97
+ local_result = matrix_dot.local(np.eye(10), np.eye(10))
98
+ ```
99
+
100
+ ---
101
+
102
+ ## 🔒 Security & Sandboxing
103
+
104
+ Unlike naive pickle RPC scripts, Sharedots executes remote functions inside:
105
+ 1. Signed manifests verified by the Coordinator using **HMAC-SHA256**.
106
+ 2. Sandboxed worker processes supervised by the **Rust Daemon** (`sharedots-daemon`) with scrubbed environment variables and process-tree watchdogs.
107
+ 3. Content-addressed, SHA-256 verified chunked HTTP Range artifact caching.
@@ -0,0 +1,90 @@
1
+ # Sharedots Python SDK (`sharedots`)
2
+
3
+ Universal Distributed Compute Network — Python SDK & Remote Execution Engine.
4
+
5
+ The Sharedots Python SDK provides an intuitive, high-performance distributed computing interface with zero-boilerplate remote function execution. It seamlessly connects with the native Sharedots Coordinator and Rust worker daemons over Tailscale mesh networks or local subnets.
6
+
7
+ ---
8
+
9
+ ## 🚀 Quickstart
10
+
11
+ ### 1. Connect to a Compute Room
12
+
13
+ ```python
14
+ import sharedots as sd
15
+
16
+ # Connect to an existing room (e.g. over Tailscale or localhost)
17
+ client = sd.Client(
18
+ coordinator="http://100.82.14.30:4000",
19
+ room_id="room-alpha-123",
20
+ token="secret-token-xyz"
21
+ )
22
+
23
+ # Or create a new room directly:
24
+ room = client.create_room(name="my-mesh-room")
25
+ ```
26
+
27
+ ### 2. Distribute Functions with `@client.remote`
28
+
29
+ Decorate any Python function to execute across remote cluster nodes:
30
+
31
+ ```python
32
+ import numpy as np
33
+ import sharedots as sd
34
+
35
+ client = sd.Client(coordinator="http://localhost:4000", room_id="room-1", token="secret")
36
+
37
+ @client.remote(cpu=2, memory="1GB", gpu=True)
38
+ def matrix_dot(a, b):
39
+ # Runs remotely on a cluster worker node
40
+ return np.dot(a, b)
41
+
42
+ # Dispatches task across the cluster and immediately returns a Future
43
+ future = matrix_dot(np.eye(100), np.eye(100))
44
+
45
+ # Await result
46
+ result = future.result(timeout=30)
47
+ print("Computed result:", result)
48
+ ```
49
+
50
+ ### 3. Parallel Sharded Batch Processing with `.map()`
51
+
52
+ Distribute array slices or parameter sweeps across all available worker nodes in a single job:
53
+
54
+ ```python
55
+ @client.remote(cpu=1, memory="512MB")
56
+ def evaluate_trial(trial_id, parameter):
57
+ import time
58
+ # Simulate simulation / training trial
59
+ return {"trial": trial_id, "score": parameter ** 2}
60
+
61
+ # Automatically shards tasks across all cluster workers in parallel:
62
+ trials = [(i, i * 0.1) for i in range(20)]
63
+ results = evaluate_trial.map(trials)
64
+
65
+ print("All trials completed:", results)
66
+ ```
67
+
68
+ ### 4. Gather Multiple Futures
69
+
70
+ ```python
71
+ futures = [matrix_dot(A_i, B) for A_i in slices]
72
+ results = sd.gather(futures)
73
+ ```
74
+
75
+ ### 5. Local Debugging with `.local()`
76
+
77
+ Test functions locally in your process without sending them to the network:
78
+
79
+ ```python
80
+ local_result = matrix_dot.local(np.eye(10), np.eye(10))
81
+ ```
82
+
83
+ ---
84
+
85
+ ## 🔒 Security & Sandboxing
86
+
87
+ Unlike naive pickle RPC scripts, Sharedots executes remote functions inside:
88
+ 1. Signed manifests verified by the Coordinator using **HMAC-SHA256**.
89
+ 2. Sandboxed worker processes supervised by the **Rust Daemon** (`sharedots-daemon`) with scrubbed environment variables and process-tree watchdogs.
90
+ 3. Content-addressed, SHA-256 verified chunked HTTP Range artifact caching.
@@ -0,0 +1,33 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "sharedots"
7
+ version = "0.1.0"
8
+ description = "Universal Distributed Compute Network — Python SDK & Remote Execution"
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = { text = "MIT" }
12
+ authors = [{ name = "Sharedots Team" }]
13
+ classifiers = [
14
+ "Programming Language :: Python :: 3",
15
+ "Topic :: System :: Distributed Computing",
16
+ ]
17
+ dependencies = []
18
+
19
+ [project.optional-dependencies]
20
+ dev = [
21
+ "cloudpickle>=3.0.0",
22
+ "numpy>=1.24.0",
23
+ "pytest>=7.0.0",
24
+ "pytest-xdist>=3.5.0",
25
+ ]
26
+
27
+ [tool.pytest.ini_options]
28
+ testpaths = ["tests"]
29
+ pythonpath = ["."]
30
+ addopts = "--import-mode=importlib -ra -q"
31
+
32
+ [project.scripts]
33
+ sharedots-runner = "sharedots.runner:main"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,8 @@
1
+ from setuptools import setup, find_packages
2
+
3
+ setup(
4
+ name="sharedots",
5
+ version="0.1.0",
6
+ packages=find_packages(),
7
+ python_requires=">=3.9",
8
+ )
@@ -0,0 +1,30 @@
1
+ """Sharedots Python SDK — Universal Distributed Compute & Remote Execution."""
2
+
3
+ from .client import Client, connect
4
+ from .exceptions import (
5
+ ArtifactError,
6
+ AuthenticationError,
7
+ JobTimeoutError,
8
+ RemoteExecutionError,
9
+ SharedotsError,
10
+ )
11
+ from .future import SharedotsFuture, gather
12
+ from .remote import RemoteFunction, remote
13
+ from .room import Room
14
+
15
+ __version__ = "0.1.0"
16
+
17
+ __all__ = [
18
+ "Client",
19
+ "connect",
20
+ "Room",
21
+ "remote",
22
+ "RemoteFunction",
23
+ "SharedotsFuture",
24
+ "gather",
25
+ "SharedotsError",
26
+ "RemoteExecutionError",
27
+ "AuthenticationError",
28
+ "JobTimeoutError",
29
+ "ArtifactError",
30
+ ]
@@ -0,0 +1,155 @@
1
+ """Top-level Sharedots Client for managing rooms and remote compute decorators."""
2
+
3
+ import json
4
+ from typing import Any, Callable, Dict, Optional, Union
5
+ import urllib.error
6
+ import urllib.parse
7
+ import urllib.request
8
+
9
+ from .exceptions import AuthenticationError, SharedotsError
10
+ from .remote import RemoteFunction
11
+ from .room import Room
12
+
13
+
14
+ class Client:
15
+ """Entry point for connecting to a Sharedots coordinator cluster."""
16
+
17
+ def __init__(
18
+ self,
19
+ coordinator: str = "http://127.0.0.1:4000",
20
+ room_id: Optional[str] = None,
21
+ token: Optional[str] = None,
22
+ ):
23
+ self.coordinator_url = coordinator.rstrip("/")
24
+ self.token = token
25
+ self.active_room: Optional[Room] = None
26
+
27
+ if room_id and token:
28
+ self.active_room = Room(self.coordinator_url, room_id, token)
29
+
30
+ def _check_render_notice(self, reason: Any) -> str:
31
+ if "onrender.com" in self.coordinator_url:
32
+ return (
33
+ f"\n💡 [Render Free Tier Notice] The coordinator at {self.coordinator_url} appears to be sleeping.\n"
34
+ " Render's free tier spins down after 15 min of inactivity. Please give it ~30-50 seconds to wake up and retry!"
35
+ )
36
+ return ""
37
+
38
+ def health(self) -> Dict[str, Any]:
39
+ """Queries coordinator health status and protocol version."""
40
+ url = f"{self.coordinator_url}/api/health"
41
+ req = urllib.request.Request(url, method="GET")
42
+ try:
43
+ with urllib.request.urlopen(req) as resp:
44
+ return json.loads(resp.read().decode("utf-8"))
45
+ except urllib.error.URLError as e:
46
+ notice = self._check_render_notice(e.reason)
47
+ raise SharedotsError(f"Failed to reach coordinator at {self.coordinator_url}: {e.reason}{notice}")
48
+
49
+ def overview(self) -> Dict[str, Any]:
50
+ """Queries overall cluster telemetry (total workers, cores, memory)."""
51
+ url = f"{self.coordinator_url}/api/overview"
52
+ req = urllib.request.Request(url, method="GET")
53
+ try:
54
+ with urllib.request.urlopen(req) as resp:
55
+ return json.loads(resp.read().decode("utf-8"))
56
+ except urllib.error.URLError as e:
57
+ notice = self._check_render_notice(e.reason)
58
+ raise SharedotsError(f"Failed to reach coordinator at {self.coordinator_url}: {e.reason}{notice}")
59
+
60
+ def create_room(self, name: Optional[str] = None) -> Room:
61
+ """Creates a new authenticated room on the coordinator."""
62
+ url = f"{self.coordinator_url}/api/rooms"
63
+ payload = json.dumps({"name": name or "mesh-room"}).encode("utf-8")
64
+ headers = {"content-type": "application/json"}
65
+ req = urllib.request.Request(url, data=payload, headers=headers, method="POST")
66
+
67
+ try:
68
+ with urllib.request.urlopen(req) as resp:
69
+ data = json.loads(resp.read().decode("utf-8"))
70
+ except urllib.error.URLError as e:
71
+ raise SharedotsError(f"Failed to reach coordinator at {self.coordinator_url}: {e.reason}")
72
+
73
+ room = Room(
74
+ coordinator_url=self.coordinator_url,
75
+ room_id=data["roomId"],
76
+ token=data["secret"],
77
+ )
78
+ self.active_room = room
79
+ if not self.token:
80
+ self.token = data["secret"]
81
+ return room
82
+
83
+ def connect(self, room_id: str, token: Optional[str] = None) -> Room:
84
+ """Connects to an existing room using its room ID and authentication token."""
85
+ effective_token = token or self.token
86
+ if not effective_token:
87
+ raise AuthenticationError("A room token (secret) is required to connect to a room")
88
+
89
+ # Verify room exists on coordinator
90
+ url = f"{self.coordinator_url}/api/rooms/{urllib.parse.quote(room_id)}"
91
+ try:
92
+ req = urllib.request.Request(url, method="GET")
93
+ with urllib.request.urlopen(req) as resp:
94
+ if resp.status != 200:
95
+ raise SharedotsError(f"Room {room_id} not found on coordinator")
96
+ except urllib.error.HTTPError as e:
97
+ if e.code == 404:
98
+ raise SharedotsError(f"Room {room_id} not found on coordinator")
99
+ raise
100
+
101
+ room = Room(self.coordinator_url, room_id, effective_token)
102
+ self.active_room = room
103
+ return room
104
+
105
+ def remote(
106
+ self,
107
+ fn: Optional[Callable[..., Any]] = None,
108
+ *,
109
+ cpu: float = 1.0,
110
+ memory: str = "512MB",
111
+ gpu: bool = False,
112
+ timeout_sec: int = 600,
113
+ max_attempts: int = 3,
114
+ name: Optional[str] = None,
115
+ ) -> Union[RemoteFunction, Callable[[Callable[..., Any]], RemoteFunction]]:
116
+ """Decorator binding a function to this Client's active room for distributed execution.
117
+
118
+ Usage:
119
+ client = sd.Client(coordinator="...", room_id="...", token="...")
120
+
121
+ @client.remote(cpu=2, memory="1GB", gpu=True)
122
+ def process_tensor(data):
123
+ return data * 2
124
+
125
+ future = process_tensor(my_data)
126
+ result = future.result()
127
+ """
128
+ def decorator(target_fn: Callable[..., Any]) -> RemoteFunction:
129
+ if not self.active_room:
130
+ raise SharedotsError(
131
+ "No active room connected. Call client.create_room() or client.connect(...) first."
132
+ )
133
+ return RemoteFunction(
134
+ fn=target_fn,
135
+ room=self.active_room,
136
+ cpu=cpu,
137
+ memory=memory,
138
+ gpu=gpu,
139
+ timeout_sec=timeout_sec,
140
+ max_attempts=max_attempts,
141
+ name=name,
142
+ )
143
+
144
+ if fn is not None:
145
+ return decorator(fn)
146
+ return decorator
147
+
148
+
149
+ def connect(
150
+ room: str,
151
+ token: str,
152
+ coordinator: str = "http://127.0.0.1:4000",
153
+ ) -> Client:
154
+ """Connects directly to an existing room and returns an authenticated Client instance."""
155
+ return Client(coordinator=coordinator, room_id=room, token=token)
@@ -0,0 +1,44 @@
1
+ """Cryptographic and HMAC authentication utilities matching @sharedots/protocol."""
2
+
3
+ import hashlib
4
+ import hmac
5
+ import time
6
+ from typing import Dict, Union
7
+
8
+
9
+ def compute_request_signature(
10
+ room_secret: str,
11
+ method: str,
12
+ path: str,
13
+ timestamp_sec: Union[int, str],
14
+ room_id: str,
15
+ ) -> str:
16
+ """Computes HMAC-SHA256 signature for authenticating HTTP requests to Coordinator."""
17
+ canonical = f"{method.upper()}\n{path}\n{str(timestamp_sec)}\n{room_id}"
18
+ return hmac.new(
19
+ room_secret.encode("utf-8"),
20
+ canonical.encode("utf-8"),
21
+ hashlib.sha256,
22
+ ).hexdigest()
23
+
24
+
25
+ def auth_headers(
26
+ room_secret: str,
27
+ room_id: str,
28
+ method: str,
29
+ path: str,
30
+ timestamp_sec: Union[int, None] = None,
31
+ ) -> Dict[str, str]:
32
+ """Generates standard Sharedots room authentication HTTP headers."""
33
+ ts = timestamp_sec if timestamp_sec is not None else int(time.time())
34
+ sig = compute_request_signature(room_secret, method, path, ts, room_id)
35
+ return {
36
+ "x-sharedots-room": room_id,
37
+ "x-sharedots-ts": str(ts),
38
+ "x-sharedots-sig": sig,
39
+ }
40
+
41
+
42
+ def sha256_bytes(data: bytes) -> str:
43
+ """Computes hexadecimal SHA-256 digest of binary payload."""
44
+ return hashlib.sha256(data).hexdigest()
@@ -0,0 +1,48 @@
1
+ """Sharedots Python SDK Exceptions."""
2
+
3
+ from typing import Optional
4
+
5
+
6
+ class SharedotsError(Exception):
7
+ """Base exception for all Sharedots errors."""
8
+ pass
9
+
10
+
11
+ class AuthenticationError(SharedotsError):
12
+ """Raised when authentication with the Coordinator fails."""
13
+ pass
14
+
15
+
16
+ class ArtifactError(SharedotsError):
17
+ """Raised when artifact upload, download, or verification fails."""
18
+ pass
19
+
20
+
21
+ class JobTimeoutError(SharedotsError):
22
+ """Raised when waiting for a job or task times out."""
23
+ pass
24
+
25
+
26
+ class RemoteExecutionError(SharedotsError):
27
+ """Raised when a remote worker task raises an unhandled exception.
28
+
29
+ Attributes:
30
+ error_type: Name of the remote exception class.
31
+ error_message: String message of the exception.
32
+ remote_traceback: Full traceback captured on the remote worker node.
33
+ """
34
+
35
+ def __init__(
36
+ self,
37
+ error_message: str,
38
+ error_type: Optional[str] = None,
39
+ remote_traceback: Optional[str] = None,
40
+ ):
41
+ self.error_type = error_type or "Exception"
42
+ self.error_message = error_message
43
+ self.remote_traceback = remote_traceback
44
+
45
+ formatted = f"Remote task failed with {self.error_type}: {self.error_message}"
46
+ if self.remote_traceback:
47
+ formatted += f"\n--- Remote Worker Traceback ---\n{self.remote_traceback}"
48
+ super().__init__(formatted)
@@ -0,0 +1,156 @@
1
+ """Future and asynchronous completion abstractions for Sharedots remote executions."""
2
+
3
+ import time
4
+ from typing import Any, List, Optional
5
+
6
+ try:
7
+ import cloudpickle as serializer
8
+ except ImportError:
9
+ import pickle as serializer
10
+
11
+ from .exceptions import JobTimeoutError, RemoteExecutionError, SharedotsError
12
+ from .room import Room
13
+
14
+
15
+ class SharedotsFuture:
16
+ """A Future representing the eventual result of a distributed compute task."""
17
+
18
+ def __init__(
19
+ self,
20
+ room: Room,
21
+ job_id: str,
22
+ task_index: int = 0,
23
+ task_id: Optional[str] = None,
24
+ ):
25
+ self.room = room
26
+ self.job_id = job_id
27
+ self.task_index = task_index
28
+ self.task_id = task_id
29
+ self._cached_result: Optional[Any] = None
30
+ self._is_resolved = False
31
+ self._last_snapshot: Optional[dict] = None
32
+
33
+ def done(self) -> bool:
34
+ """Returns True if the remote task has completed, failed, or was cancelled."""
35
+ if self._is_resolved:
36
+ return True
37
+ detail = self.room.get_job(self.job_id)
38
+ self._last_snapshot = detail
39
+ status = detail.get("status")
40
+ return status in ("completed", "failed", "cancelled")
41
+
42
+ @property
43
+ def status(self) -> str:
44
+ """Returns the current execution status (queued, running, completed, failed, cancelled)."""
45
+ if self._is_resolved:
46
+ return "completed"
47
+ if not self._last_snapshot:
48
+ self._last_snapshot = self.room.get_job(self.job_id)
49
+ return self._last_snapshot.get("status", "unknown")
50
+
51
+ @property
52
+ def progress(self) -> float:
53
+ """Returns execution progress percentage (0.0 to 100.0)."""
54
+ if self._is_resolved:
55
+ return 100.0
56
+ if not self._last_snapshot:
57
+ self._last_snapshot = self.room.get_job(self.job_id)
58
+ prog = self._last_snapshot.get("progress", {})
59
+ return float(prog.get("percent", 0.0))
60
+
61
+ def result(self, timeout: Optional[float] = None, poll_interval: float = 0.2) -> Any:
62
+ """Waits for task completion and returns the unpickled result.
63
+
64
+ Raises:
65
+ JobTimeoutError: If the task exceeds timeout seconds.
66
+ RemoteExecutionError: If the remote task raised an exception on the worker.
67
+ SharedotsError: If the job was cancelled or encountered a system fault.
68
+ """
69
+ if self._is_resolved:
70
+ return self._cached_result
71
+
72
+ start_time = time.time()
73
+ while True:
74
+ detail = self.room.get_job(self.job_id)
75
+ self._last_snapshot = detail
76
+ status = detail.get("status")
77
+
78
+ if status == "completed":
79
+ break
80
+ elif status == "failed":
81
+ err_msg = detail.get("errorMessage") or "Job execution failed"
82
+ err_code = detail.get("errorCode") or "EXECUTION_FAILED"
83
+ raise RemoteExecutionError(f"{err_code}: {err_msg}")
84
+ elif status == "cancelled":
85
+ raise SharedotsError(f"Job {self.job_id} was cancelled")
86
+
87
+ if timeout is not None and (time.time() - start_time) > timeout:
88
+ raise JobTimeoutError(f"Job {self.job_id} timed out after {timeout} seconds")
89
+
90
+ time.sleep(poll_interval)
91
+
92
+ # Job completed — resolve the specific task output artifact
93
+ tasks = detail.get("tasks", [])
94
+ output_artifact_id = None
95
+
96
+ task_info = None
97
+ if self.task_id:
98
+ task_info = next((t for t in tasks if t.get("taskId") == self.task_id), None)
99
+ if not task_info:
100
+ task_info = next((t for t in tasks if t.get("taskIndex") == self.task_index), None)
101
+ if not task_info and self.task_index < len(tasks):
102
+ task_info = tasks[self.task_index]
103
+
104
+ if task_info:
105
+ out = task_info.get("output")
106
+ if out and isinstance(out, dict):
107
+ output_artifact_id = out.get("artifactId")
108
+
109
+ # Fallback to result artifact if tasks list output was empty
110
+ if not output_artifact_id:
111
+ res_obj = detail.get("result") or {}
112
+ output_artifact_id = res_obj.get("resultArtifactId")
113
+
114
+ if not output_artifact_id:
115
+ raise SharedotsError(f"Job {self.job_id} task {self.task_index} completed without an output artifact")
116
+
117
+ # Download artifact and unpickle
118
+ artifact_bytes = self.room.download_artifact(output_artifact_id)
119
+ out_data = serializer.loads(artifact_bytes)
120
+
121
+ if not isinstance(out_data, dict) or "success" not in out_data:
122
+ # Direct raw return
123
+ self._cached_result = out_data
124
+ self._is_resolved = True
125
+ return out_data
126
+
127
+ if not out_data.get("success"):
128
+ err = out_data.get("error") or {}
129
+ raise RemoteExecutionError(
130
+ error_message=err.get("message", "Remote task execution failed"),
131
+ error_type=err.get("type"),
132
+ remote_traceback=err.get("traceback"),
133
+ )
134
+
135
+ self._cached_result = out_data.get("result")
136
+ self._is_resolved = True
137
+ return self._cached_result
138
+
139
+ def cancel(self, reason: str = "Cancelled by client") -> dict:
140
+ """Cancels this job on the coordinator."""
141
+ return self.room.cancel_job(self.job_id, reason=reason)
142
+
143
+
144
+ def gather(futures: List[SharedotsFuture], timeout: Optional[float] = None) -> List[Any]:
145
+ """Waits for a list of SharedotsFutures and returns their results in order."""
146
+ start_time = time.time()
147
+ results = []
148
+ for f in futures:
149
+ remaining_timeout = None
150
+ if timeout is not None:
151
+ elapsed = time.time() - start_time
152
+ if elapsed >= timeout:
153
+ raise JobTimeoutError(f"gather() timed out after {timeout} seconds")
154
+ remaining_timeout = timeout - elapsed
155
+ results.append(f.result(timeout=remaining_timeout))
156
+ return results