marpledata 3.6.0.dev1__tar.gz → 3.6.0.dev2__tar.gz

{marpledata-3.6.0.dev1 → marpledata-3.6.0.dev2}/CHANGELOG.md

@@ -10,10 +10,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Exact signal names in `get_data` / `get_signal` / `get_signals` resolve via the dataset cache or `GET /datapool/{pool}/signal/{name}/id` instead of downloading the full datapool `signal_map`. Regex patterns still use the map.
+- Optional `plugin_args` on `DataStream.push_file` (and the deprecated `DB.push_file` wrapper).
 
 ### Added
 
+- Processing Pipeline
+  - `DB.create_script` / `get_scripts` / `get_script` / `delete_script`
+  - `Script.update` / `duplicate` / `delete`, to manage stored `process(dataset)` scripts.
+  - `Dataset.run` / `DB.run_script` to execute a stored processing script against a dataset via a server-side sandbox job.
+  - `DataStream.scripts`, `DataStream.update`, and `DataStream.rerun_processing` (`DB.rerun_processing`) to edit a stream and set the script pipeline
+  - `Dataset.rerun_processing` and `Dataset.get_debug_messages`.
 - `DB.delete_signals`, `Dataset.delete_signal` / `Dataset.delete_signals`, and `Signal.delete` to remove signals from a dataset.
+- `Dataset.reingest` to reingest a dataset from its original uploaded file, with optional `plugin_args`.
 
 ### Fixed
 

{marpledata-3.6.0.dev1 → marpledata-3.6.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: marpledata
-Version: 3.6.0.dev1
+Version: 3.6.0.dev2
 Summary: Marple SDK for Python
 Project-URL: Homepage, https://www.marpledata.com/
 Project-URL: Documentation, https://marpledata.gitlab.io/marple-sdk/
@@ -124,6 +124,41 @@ samples = pd.DataFrame({"time": [t0, t0 + 1_000_000_000], "value": [1.0, 2.0]})
 dataset.add_signal("car.custom", samples)
 ```
 
+#### Processing scripts
+
+Write a `process(dataset)` function, store it, and try it on any imported dataset. This runs on the server and writes to that dataset.
+
+```python
+source = """
+from marple.db import Dataset
+
+def process(dataset: Dataset) -> None:
+    speed = dataset.get_signal("car.speed").get_data()
+    dataset.add_signal("car.speed_kmh", speed * 3.6, metadata={"unit": "km/h"})
+"""
+
+script = db.create_script("speed_kmh", source)
+dataset = stream.get_dataset(path="lap.csv")
+# or: dataset = stream.push_file("lap.csv").wait_for_import()
+dataset.run(script)
+```
+
+Pass a `.py` path or `pathlib.Path` to `create_script` / `script.update` instead of source text. Iterate with `script.update(script=...)` then `dataset.run(script)` again (or `dataset.run(script, source=...)` to save and run in one step). New signals written by the script may need `signal.wait_until_available(...)` before you read them.
+
+When the script looks right, attach it to the stream with `stream.update(scripts=...)`. That **replaces** the pipeline (pass `[]` to detach all). New uploads then run those scripts after ingest.
+
+```python
+stream = stream.update(scripts=[script.id])
+```
+
+For files already imported, rerun aliasing and the stream's script pipeline:
+
+```python
+dataset = dataset.rerun_processing().wait_for_import()
+```
+
+Use `script.update(...)` to change source or metadata, and `dataset.get_debug_messages()` for the latest ingestion's debug log (not the sandbox job log from `dataset.run`).
+
 #### Upload large files
 
 `stream.push_file(...)` starts an ingestion and lets the Marple DB API choose the best upload mode. Depending on the deployment and file size, the SDK can upload through the API server, upload directly to Azure Blob Storage, use a single presigned URL, or split the file into multipart uploads.
@@ -221,6 +256,11 @@ if len(datasets) > 0:
 - **Delete a stream**: `stream.delete()` or `db.delete_stream(stream_key)`
 - **Delete a dataset**: `dataset.delete()` or `db.delete_dataset(dataset_id, dataset_path)`
 - **Delete signals**: `signal.delete()`, `dataset.delete_signal(signal_id)` / `dataset.delete_signals(signal_ids)`, or `db.delete_signals(dataset_id, dataset_path, signal_ids)`
+- **Run a processing script**: `dataset.run(script)` or `db.run_script(dataset_id, script)`
+- **Create a processing script**: `db.create_script(name, script)`
+- **Set script pipeline** (replaces the full list): `stream.update(scripts=[script.id])`
+- **Rerun aliasing + scripts**: `dataset.rerun_processing().wait_for_import()` or `stream.rerun_processing([dataset.id])`
+- **Read ingest debug logs**: `dataset.get_debug_messages()`
 
 For live streams:
 

{marpledata-3.6.0.dev1 → marpledata-3.6.0.dev2}/README.md

@@ -89,6 +89,41 @@ samples = pd.DataFrame({"time": [t0, t0 + 1_000_000_000], "value": [1.0, 2.0]})
 dataset.add_signal("car.custom", samples)
 ```
 
+#### Processing scripts
+
+Write a `process(dataset)` function, store it, and try it on any imported dataset. This runs on the server and writes to that dataset.
+
+```python
+source = """
+from marple.db import Dataset
+
+def process(dataset: Dataset) -> None:
+    speed = dataset.get_signal("car.speed").get_data()
+    dataset.add_signal("car.speed_kmh", speed * 3.6, metadata={"unit": "km/h"})
+"""
+
+script = db.create_script("speed_kmh", source)
+dataset = stream.get_dataset(path="lap.csv")
+# or: dataset = stream.push_file("lap.csv").wait_for_import()
+dataset.run(script)
+```
+
+Pass a `.py` path or `pathlib.Path` to `create_script` / `script.update` instead of source text. Iterate with `script.update(script=...)` then `dataset.run(script)` again (or `dataset.run(script, source=...)` to save and run in one step). New signals written by the script may need `signal.wait_until_available(...)` before you read them.
+
+When the script looks right, attach it to the stream with `stream.update(scripts=...)`. That **replaces** the pipeline (pass `[]` to detach all). New uploads then run those scripts after ingest.
+
+```python
+stream = stream.update(scripts=[script.id])
+```
+
+For files already imported, rerun aliasing and the stream's script pipeline:
+
+```python
+dataset = dataset.rerun_processing().wait_for_import()
+```
+
+Use `script.update(...)` to change source or metadata, and `dataset.get_debug_messages()` for the latest ingestion's debug log (not the sandbox job log from `dataset.run`).
+
 #### Upload large files
 
 `stream.push_file(...)` starts an ingestion and lets the Marple DB API choose the best upload mode. Depending on the deployment and file size, the SDK can upload through the API server, upload directly to Azure Blob Storage, use a single presigned URL, or split the file into multipart uploads.
@@ -186,6 +221,11 @@ if len(datasets) > 0:
 - **Delete a stream**: `stream.delete()` or `db.delete_stream(stream_key)`
 - **Delete a dataset**: `dataset.delete()` or `db.delete_dataset(dataset_id, dataset_path)`
 - **Delete signals**: `signal.delete()`, `dataset.delete_signal(signal_id)` / `dataset.delete_signals(signal_ids)`, or `db.delete_signals(dataset_id, dataset_path, signal_ids)`
+- **Run a processing script**: `dataset.run(script)` or `db.run_script(dataset_id, script)`
+- **Create a processing script**: `db.create_script(name, script)`
+- **Set script pipeline** (replaces the full list): `stream.update(scripts=[script.id])`
+- **Rerun aliasing + scripts**: `dataset.rerun_processing().wait_for_import()` or `stream.rerun_processing([dataset.id])`
+- **Read ingest debug logs**: `dataset.get_debug_messages()`
 
 For live streams:
 

{marpledata-3.6.0.dev1 → marpledata-3.6.0.dev2}/docs/api/db.rst

@@ -14,6 +14,10 @@ See :doc:`../tutorials` for upload examples.
    marple.db.DataStream
    marple.db.Dataset
    marple.db.DatasetList
+   marple.db.SandboxJob
+   marple.db.SandboxJobStatus
+   marple.db.Script
+   marple.db.ScriptVersion
    marple.db.Signal
    marple.db.SignalUpload
    marple.db.SignalsAlreadyExistError

{marpledata-3.6.0.dev1 → marpledata-3.6.0.dev2}/docs/api/marple.db.DB.rst

@@ -16,17 +16,21 @@
       ~DB.add_dataset
       ~DB.check_connection
       ~DB.connect_trino
+      ~DB.create_script
       ~DB.create_stream
       ~DB.dataset_append
       ~DB.dataset_cool
       ~DB.delete
       ~DB.delete_dataset
+      ~DB.delete_script
       ~DB.delete_stream
       ~DB.download_original
       ~DB.download_signal
       ~DB.get
       ~DB.get_dataset
       ~DB.get_datasets
+      ~DB.get_script
+      ~DB.get_scripts
       ~DB.get_signal
       ~DB.get_signals
       ~DB.get_status
@@ -36,7 +40,10 @@
       ~DB.post
       ~DB.push_file
       ~DB.query
+      ~DB.rerun_processing
+      ~DB.run_script
       ~DB.update_metadata
+      ~DB.update_stream
       ~DB.upsert_signals
    
    

{marpledata-3.6.0.dev1 → marpledata-3.6.0.dev2}/docs/api/marple.db.DataStream.rst

@@ -15,9 +15,13 @@
    
       ~DataStream.add_dataset
       ~DataStream.delete
+      ~DataStream.fetch
       ~DataStream.get_dataset
       ~DataStream.get_datasets
       ~DataStream.push_file
+      ~DataStream.refresh
+      ~DataStream.rerun_processing
+      ~DataStream.update
    
    
 
@@ -46,5 +50,6 @@
       ~DataStream.plugin
       ~DataStream.plugin_args
       ~DataStream.signal_reduction
+      ~DataStream.scripts
    
    

{marpledata-3.6.0.dev1 → marpledata-3.6.0.dev2}/docs/api/marple.db.Dataset.rst

@@ -21,8 +21,12 @@
       ~Dataset.download
       ~Dataset.fetch
       ~Dataset.get_data
+      ~Dataset.get_debug_messages
       ~Dataset.get_signal
       ~Dataset.get_signals
+      ~Dataset.reingest
+      ~Dataset.rerun_processing
+      ~Dataset.run
       ~Dataset.update_metadata
       ~Dataset.upsert_signals
       ~Dataset.wait_for_import

marpledata-3.6.0.dev2/docs/api/marple.db.SandboxJob.rst

@@ -0,0 +1,43 @@
+marple.db.SandboxJob
+====================
+
+.. currentmodule:: marple.db
+
+.. autoclass:: SandboxJob
+
+   
+   .. automethod:: __init__
+   
+
+   
+   .. rubric:: Methods
+
+   .. autosummary::
+   
+      ~SandboxJob.fetch
+   
+   
+
+   
+   
+   .. rubric:: Attributes
+
+   .. autosummary::
+   
+      ~SandboxJob.id
+      ~SandboxJob.dataset_id
+      ~SandboxJob.stream_id
+      ~SandboxJob.script_id
+      ~SandboxJob.script_version
+      ~SandboxJob.script_index
+      ~SandboxJob.ingestion_id
+      ~SandboxJob.status
+      ~SandboxJob.batch_job_id
+      ~SandboxJob.token_id
+      ~SandboxJob.log
+      ~SandboxJob.created_by
+      ~SandboxJob.created_at
+      ~SandboxJob.started_at
+      ~SandboxJob.finished_at
+   
+   

marpledata-3.6.0.dev2/docs/api/marple.db.SandboxJobStatus.rst

@@ -0,0 +1,28 @@
+marple.db.SandboxJobStatus
+==========================
+
+.. currentmodule:: marple.db
+
+.. autoclass:: SandboxJobStatus
+
+   
+   .. rubric:: Methods
+
+   .. autosummary::
+   
+      ~SandboxJobStatus.is_terminal
+   
+   
+
+   
+   
+   .. rubric:: Members
+
+   .. autosummary::
+   
+      ~SandboxJobStatus.QUEUED
+      ~SandboxJobStatus.RUNNING
+      ~SandboxJobStatus.SUCCEEDED
+      ~SandboxJobStatus.FAILED
+   
+   

marpledata-3.6.0.dev2/docs/api/marple.db.Script.rst

@@ -0,0 +1,41 @@
+marple.db.Script
+================
+
+.. currentmodule:: marple.db
+
+.. autoclass:: Script
+
+   
+   .. automethod:: __init__
+
+   
+   .. rubric:: Methods
+
+   .. autosummary::
+   
+      ~Script.delete
+      ~Script.duplicate
+      ~Script.fetch
+      ~Script.refresh
+      ~Script.update
+   
+   
+
+   
+   
+   .. rubric:: Attributes
+
+   .. autosummary::
+   
+      ~Script.id
+      ~Script.name
+      ~Script.description
+      ~Script.created_at
+      ~Script.created_by
+      ~Script.updated_at
+      ~Script.updated_by
+      ~Script.streams
+      ~Script.versions
+      ~Script.source
+   
+   

marpledata-3.6.0.dev2/docs/api/marple.db.ScriptVersion.rst

@@ -0,0 +1,21 @@
+marple.db.ScriptVersion
+=======================
+
+.. currentmodule:: marple.db
+
+.. autoclass:: ScriptVersion
+
+   
+   .. automethod:: __init__
+
+   
+   .. rubric:: Attributes
+
+   .. autosummary::
+   
+      ~ScriptVersion.id
+      ~ScriptVersion.script
+      ~ScriptVersion.updated_at
+      ~ScriptVersion.updated_by
+   
+   

{marpledata-3.6.0.dev1 → marpledata-3.6.0.dev2}/docs/tutorials.rst

@@ -78,6 +78,44 @@ For batches, ``add_signals`` returns signal IDs without waiting:
        for signal in dataset.get_signals(signal_ids=ids, refresh=True)
    ]
 
+Processing scripts
+------------------
+
+Write a ``process(dataset)`` function, store it, and try it on any imported dataset.
+This runs on the server and writes to that dataset.
+
+.. code-block:: python
+
+   source = """
+   from marple.db import Dataset
+
+   def process(dataset: Dataset) -> None:
+       speed = dataset.get_signal("car.speed").get_data()
+       dataset.add_signal("car.speed_kmh", speed * 3.6, metadata={"unit": "km/h"})
+   """
+
+   script = db.create_script("speed_kmh", source)
+   dataset = stream.get_dataset(path="lap.csv")
+   dataset.run(script)
+
+Pass a ``.py`` path instead of source text. Iterate with
+``script.update(script=...)`` then ``dataset.run(script)`` (or
+``dataset.run(script, source=...)`` to save and run in one step).
+
+When the script looks right, attach it to the stream with
+``stream.update(scripts=...)``. That **replaces** the pipeline
+(pass ``[]`` to detach all). New uploads then run those scripts after ingest.
+
+.. code-block:: python
+
+   stream = stream.update(scripts=[script.id])
+
+For files already imported, rerun aliasing and the stream's script pipeline:
+
+.. code-block:: python
+
+   dataset = dataset.rerun_processing().wait_for_import()
+
 Filter datasets and get resampled data
 --------------------------------------
 

{marpledata-3.6.0.dev1 → marpledata-3.6.0.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "marpledata"
-version = "3.6.0.dev1"
+version = "3.6.0.dev2"
 description = "Marple SDK for Python"
 authors = [
   { name = "Matthias Baert", email = "support@marpledata.com" },

{marpledata-3.6.0.dev1 → marpledata-3.6.0.dev2}/src/marple/__init__.py

@@ -3,4 +3,4 @@ from .db import DB
 from .insight import Insight
 
 __all__ = ["DB", "Insight", "db"]
-__version__ = "3.6.0.dev1"
+__version__ = "3.6.0.dev2"

{marpledata-3.6.0.dev1 → marpledata-3.6.0.dev2}/src/marple/db/__init__.py

@@ -14,6 +14,7 @@ from marple.db.constants import SAAS_URL
 from marple.db.constants import SCHEMA as _SCHEMA
 from marple.db.dataset import Dataset, DatasetList
 from marple.db.datastream import DataStream
+from marple.db.script import SandboxJob, SandboxJobStatus, Script, ScriptVersion
 from marple.db.signal import Signal
 from marple.db.signal_upload import SignalsAlreadyExistError, SignalUpload
 from marple.utils import DBClient, validate_response
@@ -37,6 +38,10 @@ __all__ = [
     "DataStream",
     "Dataset",
     "DatasetList",
+    "SandboxJob",
+    "SandboxJobStatus",
+    "Script",
+    "ScriptVersion",
     "Signal",
     "SignalUpload",
     "SignalsAlreadyExistError",
@@ -237,6 +242,89 @@ class DB:
             f"Stream with name or id {stream_key} not found, available streams: {', '.join([s.name for s in self._streams.values()])}"
         )
 
+    def rerun_processing(self, stream_key: str | int, dataset_ids: Sequence[int] | None = None) -> None:
+        """
+        Rerun aliasing and processing scripts for a stream or selected datasets.
+
+        See :meth:`~marple.db.datastream.DataStream.rerun_processing`.
+        """
+        self.get_stream(stream_key).rerun_processing(dataset_ids)
+
+    def get_scripts(self) -> list[Script]:
+        """List processing scripts in this workspace (without source / version history)."""
+        r = self.get("/scripts")
+        return [
+            Script(client=self.client, **script)
+            for script in validate_response(r, "Get scripts failed")["scripts"]
+        ]
+
+    def get_script(self, script_id: int) -> Script:
+        """Get a processing script by ID, including recent versions and source."""
+        return Script.fetch(self.client, script_id)
+
+    def run_script(
+        self,
+        dataset_id: int,
+        script: Script | int,
+        *,
+        source: str | Path | None = None,
+        version: int | None = None,
+        timeout: float = 180,
+    ) -> Dataset:
+        """Run a stored processing script on a dataset.
+
+        See :meth:`~marple.db.dataset.Dataset.run`.
+
+        Args:
+            dataset_id: The ID of the dataset to run the script on.
+            script: A stored script or its ID.
+            source: Optional source text or ``.py`` path to save before running.
+            version: Script version ID to run. Defaults to the latest version.
+            timeout: Seconds to wait for the sandbox job to finish.
+
+        Warning:
+            This is not a dry-run. The script will be executed and the dataset will be modified.
+        """
+        return self.get_dataset(dataset_id).run(script, source=source, version=version, timeout=timeout)
+
+    def create_script(
+        self,
+        name: str,
+        script: str | Path,
+        *,
+        description: str | None = None,
+    ) -> Script:
+        """
+        Create a processing script.
+
+        Attach it to a stream with :meth:`~marple.db.datastream.DataStream.update`
+        (``scripts=`` replaces the full pipeline).
+
+        Args:
+            name: The name of the script.
+            script: Source text or a path to a file that must define ``process(dataset)``.
+            description: The description of the script.
+        """
+        r = self.post(
+            "/script",
+            json={
+                "name": name,
+                "description": description,
+                "script": Script.resolve_source(script),
+            },
+        )
+        return Script(client=self.client, **validate_response(r, "Create script failed"))
+
+    def delete_script(self, script_id: int) -> None:
+        """
+        Delete a processing script.
+
+        Warning:
+            This cannot be undone. The script is removed from every stream pipeline.
+        """
+        r = self.delete(f"/script/{script_id}")
+        validate_response(r, "Delete script failed")
+
     def _refresh_stream_cache(self, r: Response | None = None) -> None:
         if r is None:
             r = self.get("/streams")
@@ -354,6 +442,7 @@ class DB:
         metadata: dict | None = None,
         file_name: str | None = None,
         overwrite: bool = False,
+        plugin_args: str | None = None,
     ) -> int:
         """
         Push a file to a datastream.
@@ -362,12 +451,13 @@ class DB:
         - `metadata`: (optional) A dictionary of metadata to be associated with the file.
         - `file_name`: (optional) The name of the file to be stored in the stream.
         - `overwrite`: (optional) If true, existing dataset with the same name will be overwritten.
+        - `plugin_args`: (optional) Plugin arguments for this ingest.
 
         Note:
             This function is deprecated and it is encouraged to use the `push_file` method in the `DataStream` class directly.
         """
         stream = self.get_stream(stream_key)
-        return stream.push_file(file_path, metadata, file_name, overwrite=overwrite).id
+        return stream.push_file(file_path, metadata, file_name, overwrite=overwrite, plugin_args=plugin_args).id
 
     @deprecated
     def get_status(self, stream_key: str | int, dataset_id: int) -> dict:

{marpledata-3.6.0.dev1 → marpledata-3.6.0.dev2}/src/marple/db/dataset.py

@@ -23,11 +23,9 @@ from marple.db.constants import (
     MAX_SIGNALS_PER_ADD,
     SCHEMA,
 )
+from marple.db.script import SandboxJob, SandboxJobStatus, Script
 from marple.db.signal import Signal
-from marple.db.signal_upload import (
-    SignalUpload,
-    run_signal_uploads,
-)
+from marple.db.signal_upload import SignalUpload, run_signal_uploads
 from marple.utils import DBClient, validate_response
 
 
@@ -485,6 +483,25 @@ class Dataset(BaseModel):
         validate_response(r, "Cool dataset failed")
         return self.fetch(self._client, self.id)
 
+    def reingest(self, plugin_args: str | None = None) -> "Dataset":
+        """
+        Reingest this dataset from its original uploaded file.
+
+        Reingestion is started asynchronously on the server. Poll completion with
+        :meth:`wait_for_import`.
+
+        Args:
+            plugin_args: Optional plugin arguments for this reingest. If omitted, the
+                arguments from the previous ingestion are used.
+
+        Returns:
+            The current dataset state after the reingest was started.
+        """
+        kwargs = {} if plugin_args is None else {"json": {"plugin_args": plugin_args}}
+        r = self._client.post(f"/stream/{self.datastream_id}/dataset/{self.id}/reingest", **kwargs)
+        validate_response(r, "Reingest dataset failed")
+        return self.fetch(self._client, self.id)
+
     def wait_for_import(self, timeout: float = 60, force_fetch: bool = False) -> "Dataset":
         """
         Wait for the dataset import or cooling to complete.
@@ -545,6 +562,87 @@ class Dataset(BaseModel):
         r = self._client.post(f"/stream/{self.datastream_id}/dataset/{self.id}/delete")
         validate_response(r, "Delete dataset failed")
 
+    def rerun_processing(self) -> "Dataset":
+        """
+        Rerun aliasing and processing scripts for this dataset.
+
+        Returns the dataset after rerun processing has been queued.
+        Wait for completion with :meth:`wait_for_import`.
+        """
+        r = self._client.post(
+            f"/stream/{self.datastream_id}/processing/datasets",
+            json=[self.id],
+        )
+        validate_response(r, "Rerun processing failed")
+        return self.fetch(self._client, self.id)
+
+    def get_debug_messages(self) -> list[str]:
+        """Return debug messages for this dataset's latest ingestion (aliasing and pipeline runs).
+
+        Sandbox output from :meth:`run` is on the job log, not this list.
+        """
+        r = self._client.get(f"/stream/{self.datastream_id}/dataset/{self.id}/debug")
+        return validate_response(r, "Get debug messages failed")
+
+    def run(
+        self,
+        script: Script | int,
+        *,
+        source: str | Path | None = None,
+        version: int | None = None,
+        timeout: float = 180,
+    ) -> "Dataset":
+        """Run a stored processing script on this dataset.
+
+        Args:
+            script: A stored script or its ID.
+            source: Optional source text or ``.py`` path to save before running.
+            version: Script version ID to run. Defaults to the latest version.
+            timeout: Seconds to wait for the sandbox job to finish.
+
+        Warning:
+            This is not a dry-run. The script will be executed and the dataset will be modified.
+        """
+        if isinstance(script, (str, Path)):
+            raise TypeError(
+                "dataset.run() takes a stored Script (or script id). "
+                "Create one with db.create_script(name, source), then dataset.run(script)."
+            )
+        if source is not None and version is not None:
+            raise ValueError("Pass source or version, not both; saving creates a new version")
+
+        if source is not None:
+            stored = script if isinstance(script, Script) else Script.fetch(self._client, script)
+            stored = stored.update(script=source)
+            script_id = stored.id
+            version = None
+        else:
+            script_id = script.id if isinstance(script, Script) else script
+
+        payload: dict[str, Any] = {"script_id": script_id}
+        if version is not None:
+            payload["script_version"] = version
+
+        r = self._client.post(
+            f"/stream/{self.datastream_id}/dataset/{self.id}/sandbox-job",
+            json=payload,
+        )
+        job = SandboxJob.model_validate(validate_response(r, "Run script failed", check_envelope=False))
+
+        deadline = time.monotonic() + max(timeout, 0.1)
+        while not job.status.is_terminal():
+            if time.monotonic() >= deadline:
+                raise TimeoutError(
+                    f"Script did not finish after {timeout} seconds (job {job.id}, status={job.status})"
+                )
+            time.sleep(0.5)
+            job = SandboxJob.fetch(self._client, job.id)
+
+        if job.status == SandboxJobStatus.FAILED:
+            raise RuntimeError(f"Script failed (job {job.id}): {job.log or 'no log'}")
+
+        return self.fetch(self._client, self.id)
+
 
 class DatasetList(UserList[Dataset]):
     """