[DE-8270] Model weights upload & download (SDK side)

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to the [Nucleus Python Client](https://github.com/scaleapi/n
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.20.1](https://github.com/scaleapi/nucleus-python-client/releases/tag/v0.20.1) - 2026-08-13
+
+### Added
+- **Model weights.** Attach a raw weights artifact (any binary, no format constraints) to a model and fetch it back: `NucleusClient.upload_model_weights(model, path)`, `download_model_weights(model, path)`, `get_model_weights(model)`, and `delete_model_weights(model)`, plus `Model.upload_weights()` / `download_weights()` / `weights()` / `delete_weights()` and the new `ModelWeights` metadata type (`present`, `status`, `size_bytes`, `original_filename`, `content_type`, `download_url`). Artifacts up to 10 GB are supported; uploading requires edit access on the model, downloading is available to anyone who can see it.
+- Large artifacts are handled without any extra work on the caller's part: transfers stream directly to/from storage, show a `tqdm` progress bar by default (pass `progress=False` to silence it), and automatically retry transient storage failures (network blips, 429s, 5xx) with exponential backoff.
+
 ## [0.20.0](https://github.com/scaleapi/nucleus-python-client/releases/tag/v0.20.0) - 2026-08-11
 
 ### Added

nucleus/__init__.py

@@ -45,6 +45,7 @@
     "LinePrediction",
     "Model",
     "ModelCreationError",
+    "ModelWeights",
     # "MultiCategoryAnnotation", # coming soon!
     "NotFoundError",
     "NucleusAPIError",
@@ -121,6 +122,7 @@
     DATASET_IS_SCENE_KEY,
     DATASET_PRIVACY_MODE_KEY,
     DEFAULT_NETWORK_TIMEOUT_SEC,
+    DELETED_KEY,
     DESCRIPTION_KEY,
     EMBEDDING_DIMENSION_KEY,
     EMBEDDINGS_URL_KEY,
@@ -163,6 +165,8 @@
     STATUS_CODE_KEY,
     TOP_N_KEY,
     UPDATE_KEY,
+    UPLOAD_ID_KEY,
+    URL_KEY,
 )
 from .data_transfer_object.dataset_details import DatasetDetails
 from .data_transfer_object.dataset_info import DatasetInfo
@@ -213,6 +217,15 @@
 )
 from .model import Model
 from .model_run import ModelRun
+from .model_weights import (
+    MODEL_WEIGHTS_MAX_BYTES,
+    ModelWeights,
+    _finalize_payload,
+    _presign_payload,
+    _progress_to_bar,
+    _stream_weights_to_file,
+    _transfer_weights_to_storage,
+)
 from .payload_constructor import (
     construct_annotation_payload,
     construct_box_predictions_payload,
@@ -1685,6 +1698,192 @@ def delete_model(self, model_id: str) -> dict:
         )
         return response
 
+    def upload_model_weights(
+        self,
+        model: Union[Model, str],
+        path: str,
+        *,
+        content_type: Optional[str] = None,
+        original_filename: Optional[str] = None,
+        checksum_sha256: Optional[str] = None,
+        progress: bool = True,
+    ) -> ModelWeights:
+        """Attach a weights artifact to a model.
+
+        Any binary is accepted — there are no format constraints — up to 10 GB.
+        Requires edit access on the model.
+
+        ::
+
+            import nucleus
+
+            client = nucleus.NucleusClient(YOUR_SCALE_API_KEY)
+            model = client.get_model(reference_id="My-CNN")
+            client.upload_model_weights(model, "/path/to/weights.bin")
+
+        Parameters:
+            model: A :class:`Model` or a model id (``prj_*``).
+            path: Local path of the artifact to upload.
+            content_type: Content type to record for the artifact. Defaults to
+              ``application/octet-stream``.
+            original_filename: Filename to show for the artifact. Defaults to
+              the name of the file at ``path``.
+            checksum_sha256: Optional SHA-256 of the artifact.
+            progress: Whether to show a ``tqdm`` progress bar for the upload.
+
+        Returns:
+            :class:`ModelWeights`: Metadata for the uploaded artifact.
+        """
+        model_id = model.id if isinstance(model, Model) else model
+        path = os.path.expanduser(path)
+        filename = (
+            original_filename
+            if original_filename is not None
+            else os.path.basename(path)
+        )
+        total_bytes = os.path.getsize(path)
+        if total_bytes > MODEL_WEIGHTS_MAX_BYTES:
+            raise ValueError(
+                f"{path} is {total_bytes} bytes, which exceeds the "
+                f"{MODEL_WEIGHTS_MAX_BYTES // 1024 ** 3} GB model weights limit"
+            )
+
+        presign = self.make_request(
+            _presign_payload(
+                total_bytes, content_type, filename, checksum_sha256
+            ),
+            f"model/{model_id}/weights/presign",
+        )
+        upload_id = presign.get(UPLOAD_ID_KEY)
+        if not upload_id:
+            raise ValueError(
+                "Presign response did not include an uploadId; cannot upload"
+            )
+        progress_bar = (
+            self.tqdm_bar(
+                total=total_bytes,
+                unit="B",
+                unit_scale=True,
+                desc=f"Uploading {filename}",
+            )
+            if progress
+            else None
+        )
+        try:
+            on_progress = (
+                _progress_to_bar(progress_bar)
+                if progress_bar is not None
+                else None
+            )
+            parts = _transfer_weights_to_storage(
+                path, presign, total_bytes, on_progress
+            )
+            finalized = self.make_request(
+                _finalize_payload(upload_id, parts),
+                f"model/{model_id}/weights/finalize",
+            )
+        finally:
+            if progress_bar is not None:
+                progress_bar.close()
+        return ModelWeights.from_json(finalized)
+
+    def download_model_weights(
+        self,
+        model: Union[Model, str],
+        path: str,
+        *,
+        progress: bool = True,
+    ) -> str:
+        """Download a model's weights artifact to a local path.
+
+        Available to anyone who can see the model.
+
+        ::
+
+            import nucleus
+
+            client = nucleus.NucleusClient(YOUR_SCALE_API_KEY)
+            model = client.get_model(reference_id="My-CNN")
+            client.download_model_weights(model, "/path/to/save/weights.bin")
+
+        Parameters:
+            model: A :class:`Model` or a model id (``prj_*``).
+            path: Local path to write the artifact to. Parent directories are
+              created if needed.
+            progress: Whether to show a ``tqdm`` progress bar for the download.
+
+        Returns:
+            str: The path written.
+
+        Raises:
+            NotFoundError: If the model has no weights artifact to download.
+        """
+        model_id = model.id if isinstance(model, Model) else model
+        path = os.path.expanduser(path)
+        # Ask for the URL as JSON rather than following the redirect, so the
+        # API credentials aren't replayed to the download host.
+        signed = self.make_request(
+            {},
+            f"model/{model_id}/weights/download?json=1",
+            requests_command=requests.get,
+        )
+        url = signed.get(URL_KEY)
+        if not url:
+            raise NotFoundError(
+                f"Model {model_id} has no downloadable weights artifact"
+            )
+        if not progress:
+            return _stream_weights_to_file(url, path)
+        # The size isn't known until the GET responds, so the bar tracks bytes
+        # without a percentage.
+        progress_bar = self.tqdm_bar(
+            unit="B",
+            unit_scale=True,
+            desc=f"Downloading {os.path.basename(path)}",
+        )
+        try:
+            return _stream_weights_to_file(
+                url, path, _progress_to_bar(progress_bar)
+            )
+        finally:
+            progress_bar.close()
+
+    def get_model_weights(self, model: Union[Model, str]) -> ModelWeights:
+        """Fetch metadata for a model's weights artifact.
+
+        Parameters:
+            model: A :class:`Model` or a model id (``prj_*``).
+
+        Returns:
+            :class:`ModelWeights`: Metadata. ``present`` is ``False`` when the
+            model has no weights artifact available.
+        """
+        model_id = model.id if isinstance(model, Model) else model
+        return ModelWeights.from_json(
+            self.make_request(
+                {}, f"model/{model_id}/weights", requests_command=requests.get
+            )
+        )
+
+    def delete_model_weights(self, model: Union[Model, str]) -> bool:
+        """Delete a model's weights artifact.
+
+        Requires edit access on the model.
+
+        Parameters:
+            model: A :class:`Model` or a model id (``prj_*``).
+
+        Returns:
+            bool: Whether an artifact was deleted.
+        """
+        model_id = model.id if isinstance(model, Model) else model
+        response = self.make_request(
+            {},
+            f"model/{model_id}/weights",
+            requests_command=requests.delete,
+        )
+        return bool(response.get(DELETED_KEY, False))
+
     def download_pointcloud_task(
         self, task_id: str, frame_num: int
     ) -> List[Union[Point3D, LidarPoint]]:

nucleus/constants.py

@@ -236,3 +236,23 @@
 EXCLUSION_TYPE_BOX_AREA = "boxArea"
 EXCLUSION_TYPE_LABELS = "labels"
 EXCLUSION_TYPE_METADATA = "metadata"
+
+# Model weights payload keys. Unlike most of the keys above these are camelCase:
+# the weights routes serialize their DTOs straight through rather than
+# snake_casing them, so the wire format is camelCase in both directions.
+CHECKSUM_SHA256_KEY = "checksumSha256"
+CONTENT_TYPE_KEY = "contentType"
+DECLARED_SIZE_BYTES_KEY = "declaredSizeBytes"
+DELETED_KEY = "deleted"
+DOWNLOAD_URL_KEY = "downloadUrl"
+ETAG_KEY = "eTag"
+MODEL_PROJECT_ID_KEY = "modelProjectId"
+ORIGINAL_FILENAME_KEY = "originalFilename"
+PART_NUMBER_KEY = "partNumber"
+PART_SIZE_BYTES_KEY = "partSizeBytes"
+PARTS_KEY = "parts"
+PRESENT_KEY = "present"
+REQUIRED_HEADERS_KEY = "requiredHeaders"
+SIZE_BYTES_KEY = "sizeBytes"
+UPLOAD_ID_KEY = "uploadId"
+UPLOAD_URL_KEY = "uploadUrl"

nucleus/model.py

@@ -12,6 +12,7 @@
 )
 from .dataset import Dataset
 from .model_run import ModelRun
+from .model_weights import ModelWeights
 from .prediction import (
     BoxPrediction,
     CuboidPrediction,
@@ -343,3 +344,55 @@ def remove_trained_slice_ids(self, slide_ids: List[str]):
             )
 
         return response.json()
+
+    def upload_weights(
+        self,
+        path: str,
+        *,
+        content_type: Optional[str] = None,
+        original_filename: Optional[str] = None,
+        checksum_sha256: Optional[str] = None,
+        progress: bool = True,
+    ) -> ModelWeights:
+        """Attach a weights artifact to this model. ::
+
+            import nucleus
+            client = nucleus.NucleusClient("YOUR_SCALE_API_KEY")
+            model = client.get_model(reference_id="My-CNN")
+
+            model.upload_weights("/path/to/weights.bin")
+
+        See :meth:`NucleusClient.upload_model_weights` for the accepted keyword
+        arguments.
+        """
+        return self._client.upload_model_weights(
+            self,
+            path,
+            content_type=content_type,
+            original_filename=original_filename,
+            checksum_sha256=checksum_sha256,
+            progress=progress,
+        )
+
+    def download_weights(self, path: str, *, progress: bool = True) -> str:
+        """Download this model's weights artifact to ``path``.
+
+        See :meth:`NucleusClient.download_model_weights`.
+        """
+        return self._client.download_model_weights(
+            self, path, progress=progress
+        )
+
+    def weights(self) -> ModelWeights:
+        """Fetch metadata for this model's weights artifact.
+
+        See :meth:`NucleusClient.get_model_weights`.
+        """
+        return self._client.get_model_weights(self)
+
+    def delete_weights(self) -> bool:
+        """Delete this model's weights artifact.
+
+        See :meth:`NucleusClient.delete_model_weights`.
+        """
+        return self._client.delete_model_weights(self)