scale-nucleus 0.1.22__py3-none-any.whl → 0.6.4__py3-none-any.whl

nucleus/__init__.py

@@ -1,19 +1,45 @@
-"""
-Nucleus Python Library.
-
-For full documentation see: https://dashboard.scale.com/nucleus/docs/api?language=python
-"""
-import asyncio
-import json
-import logging
+"""Nucleus Python SDK. """
+
+__all__ = [
+    "AsyncJob",
+    "BoxAnnotation",
+    "BoxPrediction",
+    "CameraParams",
+    "CategoryAnnotation",
+    "CategoryPrediction",
+    "CuboidAnnotation",
+    "CuboidPrediction",
+    "Dataset",
+    "DatasetInfo",
+    "DatasetItem",
+    "DatasetItemRetrievalError",
+    "Frame",
+    "Frame",
+    "LidarScene",
+    "LidarScene",
+    "Model",
+    "ModelCreationError",
+    # "MultiCategoryAnnotation", # coming soon!
+    "NotFoundError",
+    "NucleusAPIError",
+    "NucleusClient",
+    "Point",
+    "Point3D",
+    "PolygonAnnotation",
+    "PolygonPrediction",
+    "Quaternion",
+    "Segment",
+    "SegmentationAnnotation",
+    "SegmentationPrediction",
+    "Slice",
+]
+
 import os
-import urllib.request
-from asyncio.tasks import Task
-from typing import Any, Dict, List, Optional, Union
+import warnings
+from typing import Dict, List, Optional, Sequence, Union
 
-import aiohttp
-import nest_asyncio
 import pkg_resources
+import pydantic
 import requests
 import tqdm
 import tqdm.notebook as tqdm_notebook
@@ -22,34 +48,38 @@ from nucleus.url_utils import sanitize_string_args
 
 from .annotation import (
     BoxAnnotation,
+    CategoryAnnotation,
     CuboidAnnotation,
+    MultiCategoryAnnotation,
     Point,
     Point3D,
     PolygonAnnotation,
     Segment,
     SegmentationAnnotation,
 )
+from .connection import Connection
 from .constants import (
     ANNOTATION_METADATA_SCHEMA_KEY,
     ANNOTATIONS_IGNORED_KEY,
     ANNOTATIONS_PROCESSED_KEY,
     AUTOTAGS_KEY,
     DATASET_ID_KEY,
+    DATASET_IS_SCENE_KEY,
     DEFAULT_NETWORK_TIMEOUT_SEC,
     EMBEDDING_DIMENSION_KEY,
     EMBEDDINGS_URL_KEY,
     ERROR_ITEMS,
     ERROR_PAYLOAD,
     ERRORS_KEY,
-    JOB_ID_KEY,
-    JOB_LAST_KNOWN_STATUS_KEY,
-    JOB_TYPE_KEY,
-    JOB_CREATION_TIME_KEY,
     IMAGE_KEY,
     IMAGE_URL_KEY,
     INDEX_CONTINUOUS_ENABLE_KEY,
     ITEM_METADATA_SCHEMA_KEY,
     ITEMS_KEY,
+    JOB_CREATION_TIME_KEY,
+    JOB_ID_KEY,
+    JOB_LAST_KNOWN_STATUS_KEY,
+    JOB_TYPE_KEY,
     KEEP_HISTORY_KEY,
     MESSAGE_KEY,
     MODEL_RUN_ID_KEY,
@@ -62,16 +92,21 @@ from .constants import (
     STATUS_CODE_KEY,
     UPDATE_KEY,
 )
+from .data_transfer_object.dataset_details import DatasetDetails
+from .data_transfer_object.dataset_info import DatasetInfo
 from .dataset import Dataset
-from .dataset_item import DatasetItem, CameraParams, Quaternion
+from .dataset_item import CameraParams, DatasetItem, Quaternion
+from .deprecation_warning import deprecated
 from .errors import (
     DatasetItemRetrievalError,
     ModelCreationError,
     ModelRunCreationError,
+    NoAPIKey,
     NotFoundError,
     NucleusAPIError,
 )
 from .job import AsyncJob
+from .logger import logger
 from .model import Model
 from .model_run import ModelRun
 from .payload_constructor import (
@@ -83,13 +118,16 @@ from .payload_constructor import (
 )
 from .prediction import (
     BoxPrediction,
+    CategoryPrediction,
     CuboidPrediction,
     PolygonPrediction,
     SegmentationPrediction,
 )
+from .retry_strategy import RetryStrategy
+from .scene import Frame, LidarScene
 from .slice import Slice
 from .upload_response import UploadResponse
-from .scene import Frame, LidarScene
+from .validate import Validate
 
 # pylint: disable=E1101
 # TODO: refactor to reduce this file to under 1000 lines.
@@ -98,25 +136,25 @@ from .scene import Frame, LidarScene
 
 __version__ = pkg_resources.get_distribution("scale-nucleus").version
 
-logger = logging.getLogger(__name__)
-logging.basicConfig()
-logging.getLogger(requests.packages.urllib3.__package__).setLevel(
-    logging.ERROR
-)
-
 
 class NucleusClient:
-    """
-    Nucleus client.
+    """Client to interact with the Nucleus API via Python SDK.
+
+    Parameters:
+        api_key: Follow `this guide <https://scale.com/docs/account#section-api-keys>`_
+          to retrieve your API keys.
+        use_notebook: Whether the client is being used in a notebook (toggles tqdm
+          style). Default is ``False``.
+        endpoint: Base URL of the API. Default is Nucleus's current production API.
     """
 
     def __init__(
         self,
-        api_key: str,
+        api_key: Optional[str] = None,
         use_notebook: bool = False,
         endpoint: str = None,
     ):
-        self.api_key = api_key
+        self.api_key = self._set_api_key(api_key)
         self.tqdm_bar = tqdm.tqdm
         if endpoint is None:
             self.endpoint = os.environ.get(
@@ -127,6 +165,8 @@ class NucleusClient:
         self._use_notebook = use_notebook
         if use_notebook:
             self.tqdm_bar = tqdm_notebook.tqdm
+        self._connection = Connection(self.api_key, self.endpoint)
+        self.validate = Validate(self.api_key, self.endpoint)
 
     def __repr__(self):
         return f"NucleusClient(api_key='{self.api_key}', use_notebook={self._use_notebook}, endpoint='{self.endpoint}')"
@@ -137,10 +177,26 @@ class NucleusClient:
                 return True
         return False
 
-    def list_models(self) -> List[Model]:
+    @property
+    def datasets(self) -> List[Dataset]:
+        """List all Datasets
+
+        Returns:
+            List of all datasets accessible to user
         """
-        Lists available models in your repo.
-        :return: model_ids
+        response = self.make_request({}, "dataset/details", requests.get)
+        dataset_details = pydantic.parse_obj_as(List[DatasetDetails], response)
+        return [
+            Dataset(d.id, client=self, name=d.name) for d in dataset_details
+        ]
+
+    @property
+    def models(self) -> List[Model]:
+        # TODO: implement for Dataset, scoped just to associated models
+        """Fetches all of your Nucleus models.
+
+        Returns:
+            List[:class:`Model`]: List of models associated with the client API key.
         """
         model_objects = self.make_request({}, "models/", requests.get)
 
@@ -155,20 +211,41 @@ class NucleusClient:
             for model in model_objects["models"]
         ]
 
-    def list_datasets(self) -> Dict[str, Union[str, List[str]]]:
-        """
-        Lists available datasets in your repo.
-        :return: { datasets_ids }
+    @property
+    def jobs(
+        self,
+    ) -> List[AsyncJob]:
+        """Lists all jobs, see NucleusClinet.list_jobs(...) for advanced options
+
+        Returns:
+            List of all AsyncJobs
         """
+        return self.list_jobs()
+
+    @deprecated(msg="Use the NucleusClient.models property in the future.")
+    def list_models(self) -> List[Model]:
+        return self.models
+
+    @deprecated(msg="Use the NucleusClient.datasets property in the future.")
+    def list_datasets(self) -> Dict[str, Union[str, List[str]]]:
         return self.make_request({}, "dataset/", requests.get)
 
     def list_jobs(
         self, show_completed=None, date_limit=None
     ) -> List[AsyncJob]:
+        """Fetches all of your running jobs in Nucleus.
+
+        Parameters:
+            show_completed: Whether to fetch completed and errored jobs or just
+              running jobs. Default behavior is False.
+            date_limit: Only fetch jobs that were started after this date. Default
+              behavior is 2 weeks prior to the current date.
+
+        Returns:
+            List[:class:`AsyncJob`]: List of running asynchronous jobs
+            associated with the client API key.
         """
-        Lists jobs for user.
-        :return: jobs
-        """
+        # TODO: What type is date_limit? Use pydantic ...
         payload = {show_completed: show_completed, date_limit: date_limit}
         job_objects = self.make_request(payload, "jobs/", requests.get)
         return [
@@ -182,42 +259,47 @@ class NucleusClient:
             for job in job_objects
         ]
 
+    @deprecated(msg="Prefer using Dataset.items")
     def get_dataset_items(self, dataset_id) -> List[DatasetItem]:
-        """
-        Gets all the dataset items inside your repo as a json blob.
-        :return [ DatasetItem ]
-        """
-        response = self.make_request(
-            {}, f"dataset/{dataset_id}/datasetItems", requests.get
-        )
-        dataset_items = response.get("dataset_items", None)
-        error = response.get("error", None)
-        constructed_dataset_items = []
-        if dataset_items:
-            for item in dataset_items:
-                image_url = item.get("original_image_url")
-                metadata = item.get("metadata", None)
-                ref_id = item.get("ref_id", None)
-                dataset_item = DatasetItem(image_url, ref_id, metadata)
-                constructed_dataset_items.append(dataset_item)
-        elif error:
-            raise DatasetItemRetrievalError(message=error)
-
-        return constructed_dataset_items
+        dataset = self.get_dataset(dataset_id)
+        return dataset.items
 
     def get_dataset(self, dataset_id: str) -> Dataset:
-        """
-        Fetches a dataset for given id
-        :param dataset_id: internally controlled dataset_id
-        :return: dataset
+        """Fetches a dataset by its ID.
+
+        Parameters:
+            dataset_id: The ID of the dataset to fetch.
+
+        Returns:
+            :class:`Dataset`: The Nucleus dataset as an object.
         """
         return Dataset(dataset_id, self)
 
-    def get_model(self, model_id: str) -> Model:
+    def get_job(self, job_id: str) -> AsyncJob:
+        """Fetches a dataset by its ID.
+
+        Parameters:
+            job_id: The ID of the dataset to fetch.
+
+        Returns:
+            :class:`AsyncJob`: The Nucleus async job as an object.
         """
-        Fetched a model for a given id
-        :param model_id: internally controlled dataset_id
-        :return: model
+        payload = self.make_request(
+            payload={},
+            route=f"job/{job_id}/info",
+            requests_command=requests.get,
+        )
+        return AsyncJob.from_json(payload=payload, client=self)
+
+    def get_model(self, model_id: str) -> Model:
+        """Fetches a model by its ID.
+
+        Parameters:
+            model_id: Nucleus-generated model ID (starts with ``prj_``). This can
+              be retrieved via :meth:`list_models` or a Nucleus dashboard URL.
+
+        Returns:
+            :class:`Model`: The Nucleus model as an object.
         """
         payload = self.make_request(
             payload={},
@@ -226,22 +308,16 @@ class NucleusClient:
         )
         return Model.from_json(payload=payload, client=self)
 
+    @deprecated(
+        "Model runs have been deprecated and will be removed. Use a Model instead"
+    )
     def get_model_run(self, model_run_id: str, dataset_id: str) -> ModelRun:
-        """
-        Fetches a model_run for given id
-        :param model_run_id: internally controlled model_run_id
-        :param dataset_id: the dataset id which may determine the prediction schema
-            for this model run if present on the dataset.
-        :return: model_run
-        """
         return ModelRun(model_run_id, dataset_id, self)
 
+    @deprecated(
+        "Model runs have been deprecated and will be removed. Use a Model instead"
+    )
     def delete_model_run(self, model_run_id: str):
-        """
-        Fetches a model_run for given id
-        :param model_run_id: internally controlled model_run_id
-        :return: model_run
-        """
         return self.make_request(
             {}, f"modelRun/{model_run_id}", requests.delete
         )
@@ -249,12 +325,26 @@ class NucleusClient:
     def create_dataset_from_project(
         self, project_id: str, last_n_tasks: int = None, name: str = None
     ) -> Dataset:
-        """
-        Creates a new dataset based on payload params:
-        name -- A human-readable name of the dataset.
-        Returns a response with internal id and name for a new dataset.
-        :param payload: { "name": str }
-        :return: new Dataset object
+        """Create a new dataset from an existing Scale or Rapid project.
+
+        If you already have Annotation, SegmentAnnotation, VideoAnnotation,
+        Categorization, PolygonAnnotation, ImageAnnotation, DocumentTranscription,
+        LidarLinking, LidarAnnotation, or VideoboxAnnotation projects with Scale,
+        use this endpoint to import your project directly into Nucleus.
+
+        This endpoint is asynchronous because there can be delays when the
+        number of tasks is larger than 1000. As a result, the endpoint returns
+        an instance of :class:`AsyncJob`.
+
+        Parameters:
+            project_id: The ID of the Scale/Rapid project (retrievable from URL).
+            last_n_tasks: If supplied, only pull in this number of the most recent
+              tasks. By default the endpoint will pull in all eligible tasks.
+            name: The name for your new Nucleus dataset. By default the endpoint
+              will use the project's name.
+
+        Returns:
+            :class:`Dataset`: The newly created Nucleus dataset as an object.
         """
         payload = {"project_id": project_id}
         if last_n_tasks:
@@ -267,20 +357,51 @@ class NucleusClient:
     def create_dataset(
         self,
         name: str,
+        is_scene: Optional[bool] = None,
         item_metadata_schema: Optional[Dict] = None,
         annotation_metadata_schema: Optional[Dict] = None,
     ) -> Dataset:
         """
-        Creates a new dataset:
-        Returns a response with internal id and name for a new dataset.
-        :param name -- A human-readable name of the dataset.
-        :param item_metadata_schema -- optional dictionary to define item metadata schema
-        :param annotation_metadata_schema -- optional dictionary to define annotation metadata schema
-        :return: new Dataset object
-        """
+        Creates a new, empty dataset.
+
+        Make sure that the dataset is created for the data type you would like to support.
+        Be sure to set the ``is_scene`` parameter correctly.
+
+        Parameters:
+            name: A human-readable name for the dataset.
+            is_scene: Whether the dataset contains strictly :class:`scenes
+              <LidarScene>` or :class:`items <DatasetItem>`. This value is immutable.
+              Default is False (dataset of items).
+            item_metadata_schema: Dict defining item-level metadata schema. See below.
+            annotation_metadata_schema: Dict defining annotation-level metadata schema.
+
+                Metadata schemas must be structured as follows::
+
+                    {
+                        "field_name": {
+                            "type": "category" | "number" | "text"
+                            "choices": List[str] | None
+                            "description": str | None
+                        },
+                        ...
+                    }
+
+        Returns:
+            :class:`Dataset`: The newly created Nucleus dataset as an object.
+        """
+        if is_scene is None:
+            warnings.warn(
+                "The default create_dataset('dataset_name', ...) method without the is_scene parameter will be "
+                "deprecated soon in favor of providing the is_scene parameter explicitly. "
+                "Please make sure to create a dataset with either create_dataset('dataset_name', is_scene=False, ...) "
+                "to upload DatasetItems or create_dataset('dataset_name', is_scene=True, ...) to upload LidarScenes.",
+                DeprecationWarning,
+            )
+            is_scene = False
         response = self.make_request(
             {
                 NAME_KEY: name,
+                DATASET_IS_SCENE_KEY: is_scene,
                 ANNOTATION_METADATA_SCHEMA_KEY: annotation_metadata_schema,
                 ITEM_METADATA_SCHEMA_KEY: item_metadata_schema,
             },
@@ -290,293 +411,55 @@ class NucleusClient:
 
     def delete_dataset(self, dataset_id: str) -> dict:
         """
-        Deletes a private dataset based on datasetId.
-        Returns an empty payload where response status `200` indicates
-        the dataset has been successfully deleted.
-        :param payload: { "name": str }
-        :return: { "dataset_id": str, "name": str }
+        Deletes a dataset by ID.
+
+        All items, annotations, and predictions associated with the dataset will
+        be deleted as well.
+
+        Parameters:
+            dataset_id: The ID of the dataset to delete.
+
+        Returns:
+            Payload to indicate deletion invocation.
         """
         return self.make_request({}, f"dataset/{dataset_id}", requests.delete)
 
-    @sanitize_string_args
+    @deprecated("Use Dataset.delete_item instead.")
     def delete_dataset_item(self, dataset_id: str, reference_id) -> dict:
-        """
-        Deletes a private dataset based on datasetId.
-        Returns an empty payload where response status `200` indicates
-        the dataset has been successfully deleted.
-        :param payload: { "name": str }
-        :return: { "dataset_id": str, "name": str }
-        """
-        return self.make_request(
-            {},
-            f"dataset/{dataset_id}/refloc/{reference_id}",
-            requests.delete,
-        )
+        dataset = self.get_dataset(dataset_id)
+        return dataset.delete_item(reference_id)
 
+    @deprecated("Use Dataset.append instead.")
     def populate_dataset(
         self,
         dataset_id: str,
         dataset_items: List[DatasetItem],
-        batch_size: int = 100,
+        batch_size: int = 20,
         update: bool = False,
     ):
-        """
-        Appends images to a dataset with given dataset_id.
-        Overwrites images on collision if updated.
-        :param dataset_id: id of a dataset
-        :param payload: { "items": List[DatasetItem], "update": bool }
-        :param local: flag if images are stored locally
-        :param batch_size: size of the batch for long payload
-        :return:
-        {
-            "dataset_id: str,
-            "new_items": int,
-            "updated_items": int,
-            "ignored_items": int,
-            "upload_errors": int
-        }
-        """
-        local_items = []
-        remote_items = []
-
-        # Check local files exist before sending requests
-        for item in dataset_items:
-            if item.local:
-                if not item.local_file_exists():
-                    raise NotFoundError()
-                local_items.append(item)
-            else:
-                remote_items.append(item)
-
-        local_batches = [
-            local_items[i : i + batch_size]
-            for i in range(0, len(local_items), batch_size)
-        ]
-
-        remote_batches = [
-            remote_items[i : i + batch_size]
-            for i in range(0, len(remote_items), batch_size)
-        ]
-
-        agg_response = UploadResponse(json={DATASET_ID_KEY: dataset_id})
-
-        async_responses: List[Any] = []
-
-        if local_batches:
-            tqdm_local_batches = self.tqdm_bar(
-                local_batches, desc="Local file batches"
-            )
-
-            for batch in tqdm_local_batches:
-                payload = construct_append_payload(batch, update)
-                responses = self._process_append_requests_local(
-                    dataset_id, payload, update
-                )
-                async_responses.extend(responses)
-
-        if remote_batches:
-            tqdm_remote_batches = self.tqdm_bar(
-                remote_batches, desc="Remote file batches"
-            )
-            for batch in tqdm_remote_batches:
-                payload = construct_append_payload(batch, update)
-                responses = self._process_append_requests(
-                    dataset_id=dataset_id,
-                    payload=payload,
-                    update=update,
-                    batch_size=batch_size,
-                )
-                async_responses.extend(responses)
-
-        for response in async_responses:
-            agg_response.update_response(response)
-
-        return agg_response
-
-    def _process_append_requests_local(
-        self,
-        dataset_id: str,
-        payload: dict,
-        update: bool,  # TODO: understand how to pass this in.
-        local_batch_size: int = 10,
-    ):
-        def get_files(batch):
-            for item in batch:
-                item[UPDATE_KEY] = update
-            request_payload = [
-                (
-                    ITEMS_KEY,
-                    (
-                        None,
-                        json.dumps(batch, allow_nan=False),
-                        "application/json",
-                    ),
-                )
-            ]
-            for item in batch:
-                image = open(  # pylint: disable=R1732
-                    item.get(IMAGE_URL_KEY), "rb"  # pylint: disable=R1732
-                )  # pylint: disable=R1732
-                img_name = os.path.basename(image.name)
-                img_type = (
-                    f"image/{os.path.splitext(image.name)[1].strip('.')}"
-                )
-                request_payload.append(
-                    (IMAGE_KEY, (img_name, image, img_type))
-                )
-            return request_payload
-
-        items = payload[ITEMS_KEY]
-        responses: List[Any] = []
-        files_per_request = []
-        payload_items = []
-        for i in range(0, len(items), local_batch_size):
-            batch = items[i : i + local_batch_size]
-            files_per_request.append(get_files(batch))
-            payload_items.append(batch)
-
-        future = self.make_many_files_requests_asynchronously(
-            files_per_request,
-            f"dataset/{dataset_id}/append",
+        dataset = self.get_dataset(dataset_id)
+        return dataset.append(
+            dataset_items, batch_size=batch_size, update=update
         )
 
-        try:
-            loop = asyncio.get_event_loop()
-        except RuntimeError:  # no event loop running:
-            loop = asyncio.new_event_loop()
-            responses = loop.run_until_complete(future)
-        else:
-            nest_asyncio.apply(loop)
-            return loop.run_until_complete(future)
-
-        def close_files(request_items):
-            for item in request_items:
-                # file buffer in location [1][1]
-                if item[0] == IMAGE_KEY:
-                    item[1][1].close()
-
-        # don't forget to close all open files
-        for p in files_per_request:
-            close_files(p)
-
-        return responses
-
-    async def make_many_files_requests_asynchronously(
-        self, files_per_request, route
-    ):
-        """
-        Makes an async post request with files to a Nucleus endpoint.
-
-        :param files_per_request: A list of lists of tuples (name, (filename, file_pointer, content_type))
-           name will become the name by which the multer can build an array.
-        :param route: route for the request
-        :return: awaitable list(response)
-        """
-        async with aiohttp.ClientSession() as session:
-            tasks = [
-                asyncio.ensure_future(
-                    self._make_files_request(
-                        files=files, route=route, session=session
-                    )
-                )
-                for files in files_per_request
-            ]
-            return await asyncio.gather(*tasks)
-
-    async def _make_files_request(
-        self,
-        files,
-        route: str,
-        session: aiohttp.ClientSession,
-    ):
-        """
-        Makes an async post request with files to a Nucleus endpoint.
-
-        :param files: A list of tuples (name, (filename, file_pointer, file_type))
-        :param route: route for the request
-        :param session: Session to use for post.
-        :return: response
-        """
-        endpoint = f"{self.endpoint}/{route}"
-
-        logger.info("Posting to %s", endpoint)
-
-        form = aiohttp.FormData()
-
-        for file in files:
-            form.add_field(
-                name=file[0],
-                filename=file[1][0],
-                value=file[1][1],
-                content_type=file[1][2],
-            )
-
-        async with session.post(
-            endpoint,
-            data=form,
-            auth=aiohttp.BasicAuth(self.api_key, ""),
-            timeout=DEFAULT_NETWORK_TIMEOUT_SEC,
-        ) as response:
-            logger.info("API request has response code %s", response.status)
-
-            try:
-                data = await response.json()
-            except aiohttp.client_exceptions.ContentTypeError:
-                # In case of 404, the server returns text
-                data = await response.text()
-
-            if not response.ok:
-                self.handle_bad_response(
-                    endpoint,
-                    session.post,
-                    aiohttp_response=(response.status, response.reason, data),
-                )
-
-            return data
-
-    def _process_append_requests(
-        self,
-        dataset_id: str,
-        payload: dict,
-        update: bool,
-        batch_size: int = 20,
-    ):
-        items = payload[ITEMS_KEY]
-        payloads = [
-            # batch_size images per request
-            {ITEMS_KEY: items[i : i + batch_size], UPDATE_KEY: update}
-            for i in range(0, len(items), batch_size)
-        ]
-
-        return [
-            self.make_request(
-                payload,
-                f"dataset/{dataset_id}/append",
-            )
-            for payload in payloads
-        ]
-
     def annotate_dataset(
         self,
         dataset_id: str,
-        annotations: List[
+        annotations: Sequence[
             Union[
                 BoxAnnotation,
                 PolygonAnnotation,
                 CuboidAnnotation,
+                CategoryAnnotation,
+                MultiCategoryAnnotation,
                 SegmentationAnnotation,
             ]
         ],
         update: bool,
         batch_size: int = 5000,
-    ):
-        """
-        Uploads ground truth annotations for a given dataset.
-        :param dataset_id: id of the dataset
-        :param annotations: List[Union[BoxAnnotation, PolygonAnnotation, CuboidAnnotation, SegmentationAnnotation]]
-        :param update: whether to update or ignore conflicting annotations
-        :return: {"dataset_id: str, "annotations_processed": int}
-        """
+    ) -> Dict[str, object]:
+        # TODO: deprecate in favor of Dataset.annotate invocation
+
         # Split payload into segmentations and Box/Polygon
         segmentations = [
             ann
@@ -603,6 +486,7 @@ class NucleusClient:
             DATASET_ID_KEY: dataset_id,
             ANNOTATIONS_PROCESSED_KEY: 0,
             ANNOTATIONS_IGNORED_KEY: 0,
+            ERRORS_KEY: [],
         }
 
         total_batches = len(batches) + len(semseg_batches)
@@ -625,6 +509,7 @@ class NucleusClient:
                     agg_response[ANNOTATIONS_IGNORED_KEY] += response[
                         ANNOTATIONS_IGNORED_KEY
                     ]
+                    agg_response[ERRORS_KEY] += response[ERRORS_KEY]
 
             for s_batch in semseg_batches:
                 payload = construct_segmentation_payload(s_batch, update)
@@ -644,29 +529,33 @@ class NucleusClient:
 
         return agg_response
 
+    @deprecated(msg="Use Dataset.ingest_tasks instead")
     def ingest_tasks(self, dataset_id: str, payload: dict):
-        """
-        If you already submitted tasks to Scale for annotation this endpoint ingests your completed tasks
-        annotated by Scale into your Nucleus Dataset.
-        Right now we support ingestion from Videobox Annotation and 2D Box Annotation projects.
-        :param payload: {"tasks" : List[task_ids]}
-        :param dataset_id: id of the dataset
-        :return: {"ingested_tasks": int, "ignored_tasks": int, "pending_tasks": int}
-        """
-        return self.make_request(payload, f"dataset/{dataset_id}/ingest_tasks")
+        dataset = self.get_dataset(dataset_id)
+        return dataset.ingest_tasks(payload["tasks"])
 
+    @deprecated(msg="Use client.create_model instead.")
     def add_model(
         self, name: str, reference_id: str, metadata: Optional[Dict] = None
     ) -> Model:
-        """
-        Adds a model info to your repo based on payload params:
-        name -- A human-readable name of the model project.
-        reference_id -- An optional user-specified identifier to reference this given model.
-        metadata -- An arbitrary metadata blob for the model.
-        :param name: A human-readable name of the model project.
-        :param reference_id: An user-specified identifier to reference this given model.
-        :param metadata: An optional arbitrary metadata blob for the model.
-        :return: { "model_id": str }
+        return self.create_model(name, reference_id, metadata)
+
+    def create_model(
+        self, name: str, reference_id: str, metadata: Optional[Dict] = None
+    ) -> Model:
+        """Adds a :class:`Model` to Nucleus.
+
+        Parameters:
+            name: A human-readable name for the model.
+            reference_id: Unique, user-controlled ID for the model. This can be
+              used, for example, to link to an external storage of models which
+              may have its own id scheme.
+            metadata: An arbitrary dictionary of additional data about this model
+              that can be stored and retrieved. For example, you can store information
+              about the hyperparameters used in training this model.
+
+        Returns:
+            :class:`Model`: The newly created model as an object.
         """
         response = self.make_request(
             construct_model_creation_payload(name, reference_id, metadata),
@@ -678,31 +567,10 @@ class NucleusClient:
 
         return Model(model_id, name, reference_id, metadata, self)
 
+    @deprecated(
+        "Model runs have been deprecated and will be removed. Use a Model instead"
+    )
     def create_model_run(self, dataset_id: str, payload: dict) -> ModelRun:
-        """
-        Creates model run for dataset_id based on the given parameters specified in the payload:
-
-        'reference_id' -- The user-specified reference identifier to associate with the model.
-                        The 'model_id' field should be empty if this field is populated.
-
-        'model_id' -- The internally-controlled identifier of the model.
-                    The 'reference_id' field should be empty if this field is populated.
-
-        'name' -- An optional name for the model run.
-
-        'metadata' -- An arbitrary metadata blob for the current run.
-
-        :param
-        dataset_id: id of the dataset
-        payload:
-        {
-            "reference_id": str,
-            "model_id": str,
-            "name": Optional[str],
-            "metadata": Optional[Dict[str, Any]],
-        }
-        :return: new ModelRun object
-        """
         response = self.make_request(
             payload, f"dataset/{dataset_id}/modelRun/create"
         )
@@ -713,32 +581,34 @@ class NucleusClient:
             response[MODEL_RUN_ID_KEY], dataset_id=dataset_id, client=self
         )
 
+    @deprecated("Use Dataset.upload_predictions instead.")
     def predict(
         self,
-        model_run_id: str,
         annotations: List[
             Union[
                 BoxPrediction,
                 PolygonPrediction,
                 CuboidPrediction,
                 SegmentationPrediction,
+                CategoryPrediction,
             ]
         ],
-        update: bool,
+        model_run_id: Optional[str] = None,
+        model_id: Optional[str] = None,
+        dataset_id: Optional[str] = None,
+        update: bool = False,
         batch_size: int = 5000,
     ):
-        """
-        Uploads model outputs as predictions for a model_run. Returns info about the upload.
-        :param annotations: List[Union[BoxPrediction, PolygonPrediction, CuboidPrediction, SegmentationPrediction]],
-        :param update: bool
-        :return:
-        {
-            "dataset_id": str,
-            "model_run_id": str,
-            "predictions_processed": int,
-            "predictions_ignored": int,
-        }
-        """
+        if model_run_id is not None:
+            assert model_id is None and dataset_id is None
+            endpoint = f"modelRun/{model_run_id}/predict"
+        else:
+            assert (
+                model_id is not None and dataset_id is not None
+            ), "Model ID and dataset ID are required if not using model run id."
+            endpoint = (
+                f"dataset/{dataset_id}/model/{model_id}/uploadPredictions"
+            )
         segmentations = [
             ann
             for ann in annotations
@@ -761,11 +631,9 @@ class NucleusClient:
             for i in range(0, len(other_predictions), batch_size)
         ]
 
-        agg_response = {
-            MODEL_RUN_ID_KEY: model_run_id,
-            PREDICTIONS_PROCESSED_KEY: 0,
-            PREDICTIONS_IGNORED_KEY: 0,
-        }
+        errors = []
+        predictions_processed = 0
+        predictions_ignored = 0
 
         tqdm_batches = self.tqdm_bar(batches)
 
@@ -774,230 +642,129 @@ class NucleusClient:
                 batch,
                 update,
             )
-            response = self.make_request(
-                batch_payload, f"modelRun/{model_run_id}/predict"
-            )
+            response = self.make_request(batch_payload, endpoint)
             if STATUS_CODE_KEY in response:
-                agg_response[ERRORS_KEY] = response
+                errors.append(response)
             else:
-                agg_response[PREDICTIONS_PROCESSED_KEY] += response[
-                    PREDICTIONS_PROCESSED_KEY
-                ]
-                agg_response[PREDICTIONS_IGNORED_KEY] += response[
-                    PREDICTIONS_IGNORED_KEY
-                ]
+                predictions_processed += response[PREDICTIONS_PROCESSED_KEY]
+                predictions_ignored += response[PREDICTIONS_IGNORED_KEY]
+                if ERRORS_KEY in response:
+                    errors += response[ERRORS_KEY]
 
         for s_batch in s_batches:
             payload = construct_segmentation_payload(s_batch, update)
-            response = self.make_request(
-                payload, f"modelRun/{model_run_id}/predict_segmentation"
-            )
+            response = self.make_request(payload, endpoint)
             # pbar.update(1)
             if STATUS_CODE_KEY in response:
-                agg_response[ERRORS_KEY] = response
+                errors.append(response)
             else:
-                agg_response[PREDICTIONS_PROCESSED_KEY] += response[
-                    PREDICTIONS_PROCESSED_KEY
-                ]
-                agg_response[PREDICTIONS_IGNORED_KEY] += response[
-                    PREDICTIONS_IGNORED_KEY
-                ]
+                predictions_processed += response[PREDICTIONS_PROCESSED_KEY]
+                predictions_ignored += response[PREDICTIONS_IGNORED_KEY]
 
-        return agg_response
+        return {
+            MODEL_RUN_ID_KEY: model_run_id,
+            PREDICTIONS_PROCESSED_KEY: predictions_processed,
+            PREDICTIONS_IGNORED_KEY: predictions_ignored,
+            ERRORS_KEY: errors,
+        }
 
+    @deprecated(
+        "Model runs have been deprecated and will be removed. Use a Model instead."
+    )
     def commit_model_run(
         self, model_run_id: str, payload: Optional[dict] = None
     ):
-        """
-        Commits the model run. Starts matching algorithm defined by payload.
-        class_agnostic -- A flag to specify if matching algorithm should be class-agnostic or not.
-                          Default value: True
-
-        allowed_label_matches -- An optional list of AllowedMatch objects to specify allowed matches
-                                 for ground truth and model predictions.
-                                 If specified, 'class_agnostic' flag is assumed to be False
-
-        Type 'AllowedMatch':
-        {
-            ground_truth_label: string,       # A label for ground truth annotation.
-            model_prediction_label: string,   # A label for model prediction that can be matched with
-                                              # corresponding ground truth label.
-        }
-
-        payload:
-        {
-            "class_agnostic": boolean,
-            "allowed_label_matches": List[AllowedMatch],
-        }
-
-        :return: {"model_run_id": str}
-        """
+        # TODO: deprecate ModelRun. this should be renamed to calculate_evaluation_metrics
+        #   or completely removed in favor of Model class methods
         if payload is None:
             payload = {}
         return self.make_request(payload, f"modelRun/{model_run_id}/commit")
 
+    @deprecated(msg="Prefer calling Dataset.info() directly.")
     def dataset_info(self, dataset_id: str):
-        """
-        Returns information about existing dataset
-        :param dataset_id: dataset id
-        :return: dictionary of the form
-            {
-                'name': str,
-                'length': int,
-                'model_run_ids': List[str],
-                'slice_ids': List[str]
-            }
-        """
-        return self.make_request(
-            {}, f"dataset/{dataset_id}/info", requests.get
-        )
+        dataset = self.get_dataset(dataset_id)
+        return dataset.info()
 
+    @deprecated(
+        "Model runs have been deprecated and will be removed. Use a Model instead."
+    )
     def model_run_info(self, model_run_id: str):
-        """
-        provides information about a Model Run with given model_run_id:
-        model_id -- Model Id corresponding to the run
-        name -- A human-readable name of the model project.
-        status -- Status of the Model Run.
-        metadata -- An arbitrary metadata blob specified for the run.
-        :return:
-        {
-            "model_id": str,
-            "name": str,
-            "status": str,
-            "metadata": Dict[str, Any],
-        }
-        """
+        # TODO: deprecate ModelRun
         return self.make_request(
             {}, f"modelRun/{model_run_id}/info", requests.get
         )
 
+    @deprecated("Prefer calling Dataset.refloc instead.")
     @sanitize_string_args
     def dataitem_ref_id(self, dataset_id: str, reference_id: str):
-        """
-        :param dataset_id: internally controlled dataset id
-        :param reference_id: reference_id of a dataset_item
-        :return:
-        """
+        # TODO: deprecate in favor of Dataset.refloc invocation
         return self.make_request(
             {}, f"dataset/{dataset_id}/refloc/{reference_id}", requests.get
         )
 
+    @deprecated("Prefer calling Dataset.predictions_refloc instead.")
     @sanitize_string_args
-    def predictions_ref_id(self, model_run_id: str, ref_id: str):
-        """
-        Returns Model Run info For Dataset Item by model_run_id and item reference_id.
-        :param model_run_id: id of the model run.
-        :param reference_id: reference_id of a dataset item.
-        :return:
-        {
-            "annotations": List[Union[BoxPrediction, PolygonPrediction, CuboidPrediction, SegmentationPrediction]],
-        }
-        """
-        return self.make_request(
-            {}, f"modelRun/{model_run_id}/refloc/{ref_id}", requests.get
-        )
+    def predictions_ref_id(
+        self, model_run_id: str, ref_id: str, dataset_id: Optional[str] = None
+    ):
+        if dataset_id:
+            raise RuntimeError(
+                "Need to pass a dataset id. Or use Dataset.predictions_refloc."
+            )
+        # TODO: deprecate ModelRun
+        m_run = self.get_model_run(model_run_id, dataset_id)
+        return m_run.refloc(ref_id)
 
+    @deprecated("Prefer calling Dataset.iloc instead.")
     def dataitem_iloc(self, dataset_id: str, i: int):
-        """
-        Returns Dataset Item info by dataset_id and absolute number of the dataset item.
-        :param dataset_id:  internally controlled dataset id
-        :param i: absolute number of the dataset_item
-        :return:
-        """
+        # TODO: deprecate in favor of Dataset.iloc invocation
         return self.make_request(
             {}, f"dataset/{dataset_id}/iloc/{i}", requests.get
         )
 
+    @deprecated("Prefer calling Dataset.predictions_iloc instead.")
     def predictions_iloc(self, model_run_id: str, i: int):
-        """
-        Returns Model Run Info For Dataset Item by model_run_id and absolute number of an item.
-        :param model_run_id: id of the model run.
-        :param i: absolute number of Dataset Item for a dataset corresponding to the model run.
-        :return:
-        {
-            "annotations": List[Union[BoxPrediction, PolygonPrediction, CuboidPrediction, SegmentationPrediction]],
-        }
-        """
+        # TODO: deprecate ModelRun
         return self.make_request(
             {}, f"modelRun/{model_run_id}/iloc/{i}", requests.get
         )
 
+    @deprecated("Prefer calling Dataset.loc instead.")
     def dataitem_loc(self, dataset_id: str, dataset_item_id: str):
-        """
-        Returns Dataset Item Info By dataset_item_id and dataset_id
-        :param dataset_id: internally controlled id for the dataset.
-        :param dataset_item_id: internally controlled id for the dataset item.
-        :return:
-        {
-            "item": DatasetItem,
-            "annotations": List[Box2DAnnotation],
-        }
-        """
+        # TODO: deprecate in favor of Dataset.loc invocation
         return self.make_request(
             {}, f"dataset/{dataset_id}/loc/{dataset_item_id}", requests.get
         )
 
+    @deprecated("Prefer calling Dataset.predictions_loc instead.")
     def predictions_loc(self, model_run_id: str, dataset_item_id: str):
-        """
-        Returns Model Run Info For Dataset Item by its id.
-        :param model_run_id: id of the model run.
-        :param dataset_item_id: dataset_item_id of a dataset item.
-        :return:
-        {
-            "annotations": List[Union[BoxPrediction, PolygonPrediction, CuboidPrediction, SegmentationPrediction]],
-        }
-        """
+        # TODO: deprecate ModelRun
         return self.make_request(
             {}, f"modelRun/{model_run_id}/loc/{dataset_item_id}", requests.get
         )
 
+    @deprecated("Prefer calling Dataset.create_slice instead.")
     def create_slice(self, dataset_id: str, payload: dict) -> Slice:
-        """
-        Creates a slice from items already present in a dataset.
-        The caller must exclusively use either datasetItemIds or reference_ids
-        as a means of identifying items in the dataset.
-
-        "name" -- The human-readable name of the slice.
-        "reference_ids" -- An optional list of user-specified identifier for the items in the slice
-
-        :param
-        dataset_id: id of the dataset
-        payload:
-        {
-            "name": str,
-            "reference_ids": List[str],
-        }
-        :return: new Slice object
-        """
-        response = self.make_request(
-            payload, f"dataset/{dataset_id}/create_slice"
-        )
-        return Slice(response[SLICE_ID_KEY], self)
+        # TODO: deprecate in favor of Dataset.create_slice
+        dataset = self.get_dataset(dataset_id)
+        return dataset.create_slice(payload["name"], payload["reference_ids"])
 
     def get_slice(self, slice_id: str) -> Slice:
-        """
-        Returns a slice object by specified id.
+        # TODO: migrate to Dataset method and deprecate
+        """Returns a slice object by Nucleus-generated ID.
+
+        Parameters:
+            slice_id: Nucleus-generated dataset ID (starts with ``slc_``). This can
+              be retrieved via :meth:`Dataset.slices` or a Nucleus dashboard URL.
 
-        :param
-        slice_id: id of the slice
-        :return: a Slice object
+        Returns:
+            :class:`Slice`: The Nucleus slice as an object.
         """
         return Slice(slice_id, self)
 
+    @deprecated("Prefer calling Slice.info instead.")
     def slice_info(self, slice_id: str) -> dict:
-        """
-        This endpoint provides information about specified slice.
-
-        :param
-        slice_id: id of the slice
-
-        :return:
-        {
-            "name": str,
-            "dataset_id": str,
-            "reference_ids": List[str],
-        }
-        """
+        # TODO: deprecate in favor of Slice.info
         response = self.make_request(
             {},
             f"slice/{slice_id}",
@@ -1006,14 +773,15 @@ class NucleusClient:
         return response
 
     def delete_slice(self, slice_id: str) -> dict:
-        """
-        This endpoint deletes specified slice.
+        # TODO: migrate to Dataset method and deprecate
+        """Deletes slice from Nucleus.
 
-        :param
-        slice_id: id of the slice
+        Parameters:
+            slice_id: Nucleus-generated dataset ID (starts with ``slc_``). This can
+              be retrieved via :meth:`Dataset.slices` or a Nucleus dashboard URL.
 
-        :return:
-        {}
+        Returns:
+            Empty payload response.
         """
         response = self.make_request(
             {},
@@ -1022,45 +790,29 @@ class NucleusClient:
         )
         return response
 
+    @deprecated("Prefer calling Dataset.delete_annotations instead.")
     def delete_annotations(
         self, dataset_id: str, reference_ids: list = None, keep_history=False
-    ) -> dict:
-        """
-        This endpoint deletes annotations.
-
-        :param
-        slice_id: id of the slice
-
-        :return:
-        {}
-        """
-        payload = {KEEP_HISTORY_KEY: keep_history}
-        if reference_ids:
-            payload[REFERENCE_IDS_KEY] = reference_ids
-        response = self.make_request(
-            payload,
-            f"annotation/{dataset_id}",
-            requests_command=requests.delete,
-        )
-        return response
+    ) -> AsyncJob:
+        dataset = self.get_dataset(dataset_id)
+        return dataset.delete_annotations(reference_ids, keep_history)
 
     def append_to_slice(
         self,
         slice_id: str,
         reference_ids: List[str],
     ) -> dict:
-        """
-        Appends to a slice from items already present in a dataset.
-        The caller must exclusively use either datasetItemIds or reference_ids
-        as a means of identifying items in the dataset.
+        # TODO: migrate to Slice method and deprecate
+        """Appends dataset items to an existing slice.
 
-        :param
-        reference_ids: List[str],
+        Parameters:
+            slice_id: Nucleus-generated dataset ID (starts with ``slc_``). This can
+              be retrieved via :meth:`Dataset.slices` or a Nucleus dashboard URL.
+            reference_ids: List of user-defined reference IDs of the dataset items
+              to append to the slice.
 
-        :return:
-        {
-            "slice_id": str,
-        }
+        Returns:
+            Empty payload response.
         """
 
         response = self.make_request(
@@ -1068,12 +820,8 @@ class NucleusClient:
         )
         return response
 
-    def list_autotags(self, dataset_id: str) -> List[str]:
-        """
-        Fetches a list of autotags for a given dataset id
-        :param dataset_id: internally controlled dataset_id
-        :return: List[str] representing autotag_ids
-        """
+    def list_autotags(self, dataset_id: str) -> List[dict]:
+        # TODO: deprecate in favor of Dataset.list_autotags invocation
         response = self.make_request(
             {},
             f"{dataset_id}/list_autotags",
@@ -1082,25 +830,27 @@ class NucleusClient:
         return response[AUTOTAGS_KEY] if AUTOTAGS_KEY in response else response
 
     def delete_autotag(self, autotag_id: str) -> dict:
-        """
-        Deletes an autotag based on autotagId.
-        Returns an empty payload where response status `200` indicates
-        the autotag has been successfully deleted.
-        :param autotag_id: id of the autotag to delete.
-        :return: {}
+        # TODO: migrate to Dataset method (use autotag name, not id) and deprecate
+        """Deletes an autotag by ID.
+
+        Parameters:
+            autotag_id: Nucleus-generated autotag ID (starts with ``tag_``). This can
+              be retrieved via :meth:`list_autotags` or a Nucleus dashboard URL.
+
+        Returns:
+            Empty payload response.
         """
         return self.make_request({}, f"autotag/{autotag_id}", requests.delete)
 
     def delete_model(self, model_id: str) -> dict:
-        """
-        This endpoint deletes the specified model, along with all
-        associated model_runs.
+        """Deletes a model by ID.
 
-        :param
-        model_id: id of the model_run to delete.
+        Parameters:
+            model_id: Nucleus-generated model ID (starts with ``prj_``). This can
+              be retrieved via :meth:`list_models` or a Nucleus dashboard URL.
 
-        :return:
-        {}
+        Returns:
+            Empty payload response.
         """
         response = self.make_request(
             {},
@@ -1109,101 +859,95 @@ class NucleusClient:
         )
         return response
 
+    @deprecated("Prefer calling Dataset.create_custom_index instead.")
     def create_custom_index(
         self, dataset_id: str, embeddings_urls: list, embedding_dim: int
     ):
-        """
-        Creates a custom index for a given dataset, which will then be used
-        for autotag and similarity search.
-
-        :param
-        dataset_id: id of dataset that the custom index is being added to.
-        embeddings_urls: list of urls, each of which being a json mapping reference_id -> embedding vector
-        embedding_dim: the dimension of the embedding vectors, must be consistent for all embedding vectors in the index.
-        """
-        return self.make_request(
-            {
-                EMBEDDINGS_URL_KEY: embeddings_urls,
-                EMBEDDING_DIMENSION_KEY: embedding_dim,
-            },
-            f"indexing/{dataset_id}",
-            requests_command=requests.post,
-        )
-
-    def check_index_status(self, job_id: str):
-        return self.make_request(
-            {},
-            f"indexing/{job_id}",
-            requests_command=requests.get,
+        # TODO: deprecate in favor of Dataset.create_custom_index invocation
+        dataset = self.get_dataset(dataset_id)
+        return dataset.create_custom_index(
+            embeddings_urls=embeddings_urls, embedding_dim=embedding_dim
         )
 
+    @deprecated("Prefer calling Dataset.delete_custom_index instead.")
     def delete_custom_index(self, dataset_id: str):
+        # TODO: deprecate in favor of Dataset.delete_custom_index invocation
         return self.make_request(
             {},
             f"indexing/{dataset_id}",
             requests_command=requests.delete,
         )
 
+    @deprecated("Prefer calling Dataset.set_continuous_indexing instead.")
     def set_continuous_indexing(self, dataset_id: str, enable: bool = True):
-        """
-        Sets continuous indexing for a given dataset, which will automatically generate embeddings whenever
-        new images are uploaded. This endpoint is currently only enabled for enterprise customers.
-        Please reach out to nucleus@scale.com if you wish to learn more.
-
-        :param
-        dataset_id: id of dataset that continuous indexing is being toggled for
-        enable: boolean, sets whether we are enabling or disabling continuous indexing. The default behavior is to enable.
-        """
+        # TODO: deprecate in favor of Dataset.set_continuous_indexing invocation
         return self.make_request(
             {INDEX_CONTINUOUS_ENABLE_KEY: enable},
             f"indexing/{dataset_id}/setContinuous",
             requests_command=requests.post,
         )
 
+    @deprecated("Prefer calling Dataset.create_image_index instead.")
     def create_image_index(self, dataset_id: str):
-        """
-        Starts generating embeddings for images that don't have embeddings in a given dataset. These embeddings will
-        be used for autotag and similarity search. This endpoint is currently only enabled for enterprise customers.
-        Please reach out to nucleus@scale.com if you wish to learn more.
-
-        :param
-        dataset_id: id of dataset for generating embeddings on.
-        """
+        # TODO: deprecate in favor of Dataset.create_image_index invocation
         return self.make_request(
             {},
             f"indexing/{dataset_id}/internal/image",
             requests_command=requests.post,
         )
 
-    def make_request(
-        self, payload: dict, route: str, requests_command=requests.post
-    ) -> dict:
-        """
-        Makes a request to Nucleus endpoint and logs a warning if not
-        successful.
+    @deprecated("Prefer calling Dataset.create_object_index instead.")
+    def create_object_index(
+        self, dataset_id: str, model_run_id: str, gt_only: bool
+    ):
+        # TODO: deprecate in favor of Dataset.create_object_index invocation
+        payload: Dict[str, Union[str, bool]] = {}
+        if model_run_id:
+            payload["model_run_id"] = model_run_id
+        elif gt_only:
+            payload["ingest_gt_only"] = True
+        return self.make_request(
+            payload,
+            f"indexing/{dataset_id}/internal/object",
+            requests_command=requests.post,
+        )
 
-        :param payload: given payload
-        :param route: route for the request
-        :param requests_command: requests.post, requests.get, requests.delete
-        :return: response JSON
-        """
-        endpoint = f"{self.endpoint}/{route}"
+    def delete(self, route: str):
+        return self._connection.delete(route)
 
-        logger.info("Posting to %s", endpoint)
+    def get(self, route: str):
+        return self._connection.get(route)
 
-        response = requests_command(
-            endpoint,
-            json=payload,
-            headers={"Content-Type": "application/json"},
-            auth=(self.api_key, ""),
-            timeout=DEFAULT_NETWORK_TIMEOUT_SEC,
-        )
-        logger.info("API request has response code %s", response.status_code)
+    def post(self, payload: dict, route: str):
+        return self._connection.post(payload, route)
+
+    def put(self, payload: dict, route: str):
+        return self._connection.put(payload, route)
 
-        if not response.ok:
-            self.handle_bad_response(endpoint, requests_command, response)
+    # TODO: Fix return type, can be a list as well. Brings on a lot of mypy errors ...
+    def make_request(
+        self,
+        payload: Optional[dict],
+        route: str,
+        requests_command=requests.post,
+    ) -> dict:
+        """Makes a request to a Nucleus API endpoint.
 
-        return response.json()
+        Logs a warning if not successful.
+
+        Parameters:
+            payload: Given request payload.
+            route: Route for the request.
+            Requests command: ``requests.post``, ``requests.get``, or ``requests.delete``.
+
+        Returns:
+            Response payload as JSON dict.
+        """
+        if payload is None:
+            payload = {}
+        if requests_command is requests.get:
+            payload = None
+        return self._connection.make_request(payload, route, requests_command)  # type: ignore
 
     def handle_bad_response(
         self,
@@ -1212,6 +956,16 @@ class NucleusClient:
         requests_response=None,
         aiohttp_response=None,
     ):
-        raise NucleusAPIError(
+        self._connection.handle_bad_response(
             endpoint, requests_command, requests_response, aiohttp_response
         )
+
+    def _set_api_key(self, api_key):
+        """Fetch API key from environment variable NUCLEUS_API_KEY if not set"""
+        api_key = (
+            api_key if api_key else os.environ.get("NUCLEUS_API_KEY", None)
+        )
+        if api_key is None:
+            raise NoAPIKey()
+
+        return api_key