Nucleus

https://dashboard.scale.com/nucleus

Aggregate metrics in ML are not good enough. To improve production ML, you need to understand their qualitative failure modes, fix them by gathering more data, and curate diverse scenarios.

Scale Nucleus helps you:

  • Visualize your data
  • Curate interesting slices within your dataset
  • Review and manage annotations
  • Measure and debug your model performance

Nucleus is a new way—the right way—to develop ML models, helping us move away from the concept of one dataset and towards a paradigm of collections of scenarios.

Installation

$ pip install scale-nucleus

CLI installation

We recommend installing the CLI via pipx (https://pypa.github.io/pipx/installation/). This makes sure that the CLI does not interfere with you system packages and is accessible from your favorite terminal.

For MacOS:

brew install pipx
pipx ensurepath
pipx install scale-nucleus
# Optional installation of shell completion (for bash, zsh or fish)
nu install-completions

Otherwise, install via pip (requires pip 19.0 or later):

python3 -m pip install --user pipx
python3 -m pipx ensurepath
python3 -m pipx install scale-nucleus
# Optional installation of shell completion (for bash, zsh or fish)
nu install-completions

Common issues/FAQ

Outdated Client

Nucleus is iterating rapidly and as a result we do not always perfectly preserve backwards compatibility with older versions of the client. If you run into any unexpected error, it's a good idea to upgrade your version of the client by running

pip install --upgrade scale-nucleus

Usage

For the most up to date documentation, reference: https://dashboard.scale.com/nucleus/docs/api?language=python.

For Developers

Clone from github and install as editable

git clone git@github.com:scaleapi/nucleus-python-client.git
cd nucleus-python-client
pip3 install poetry
poetry install

Please install the pre-commit hooks by running the following command:

poetry run pre-commit install

When releasing a new version please add release notes to the changelog in CHANGELOG.md.

Best practices for testing: (1). Please run pytest from the root directory of the repo, i.e.

poetry run pytest tests/test_dataset.py

(2) To skip slow integration tests that have to wait for an async job to start.

poetry run pytest -n auto -m "not integration"

Note: "-n auto" is used for pytest-xdist parallelization

Pydantic Models

Prefer using Pydantic models rather than creating raw dictionaries or dataclasses to send or receive over the wire as JSONs. Pydantic is created with data validation in mind and provides very clear error messages when it encounters a problem with the payload.

The Pydantic model(s) should mirror the payload to send. To represent a JSON payload that looks like this:

{
  "example_json_with_info": {
    "metadata": {
      "frame": 0
    },
    "reference_id": "frame0",
    "url": "s3://example/scale_nucleus/2021/lidar/0038711321865000.json",
    "type": "pointcloud"
  },
  "example_image_with_info": {
    "metadata": {
      "author": "Picasso"
    },
    "reference_id": "frame0",
    "url": "s3://bucket/0038711321865000.jpg",
    "type": "image"
  }
}

Could be represented as the following structure. Note that the field names map to the JSON keys and the usage of field validators (@validator).

import os.path
from pydantic import BaseModel, validator
from typing import Literal


class JsonWithInfo(BaseModel):
    metadata: dict  # any dict is valid
    reference_id: str
    url: str
    type: Literal["pointcloud", "recipe"]

    @validator("url")
    def has_json_extension(cls, v):
        if not v.endswith(".json"):
            raise ValueError(f"Expected '.json' extension got {v}")
        return v


class ImageWithInfo(BaseModel):
    metadata: dict  # any dict is valid
    reference_id: str
    url: str
    type: Literal["image", "mask"]

    @validator("url")
    def has_valid_extension(cls, v):
        valid_extensions = {".jpg", ".jpeg", ".png", ".tiff"}
        _, extension = os.path.splitext(v)
        if extension not in valid_extensions:
            raise ValueError(f"Expected extension in {valid_extensions} got {v}")
        return v


class ExampleNestedModel(BaseModel):
    example_json_with_info: JsonWithInfo
    example_image_with_info: ImageWithInfo

# Usage:
import requests
payload = requests.get("/example")
parsed_model = ExampleNestedModel.parse_obj(payload.json())
requests.post("example/post_to", json=parsed_model.dict())

Migrating to Pydantic

  • When migrating an interface from a dictionary use nucleus.pydantic_base.DictCompatibleModel. That allows you to get the benefits of Pydantic but maintaints backwards compatibility with a Python dictionary by delegating __getitem__ to fields.
  • When migrating a frozen dataclass use nucleus.pydantic_base.ImmutableModel. That is a base class set up to be immutable after initialization.

Updating documentation: We use Sphinx to autogenerate our API Reference from docstrings.

To test your local docstring changes, run the following commands from the repository's root directory:

poetry shell
cd docs
sphinx-autobuild . ./_build/html --watch ../nucleus

sphinx-autobuild will spin up a server on localhost (port 8000 by default) that will watch for and automatically rebuild a version of the API reference based on your local docstring changes.

Custom Metrics using Shapely in scale-validate

Certain metrics use Shapely and rasterio which is added as optional dependencies.

pip install scale-nucleus[metrics]

Note that you might need to install a local GEOS package since Shapely doesn't provide binaries bundled with GEOS for every platform.

#Mac OS
brew install geos
# Ubuntu/Debian flavors
apt-get install libgeos-dev

To develop it locally use

poetry install --extras metrics

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for NucleusTeam from gravatar.com NucleusTeam

Credits

Author: Scale AI Nucleus Team

License

MIT License (MIT)

Requires

Python <4.0, >=3.10

Provides Extra

launch metrics

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

scale_nucleus-0.20.0.tar.gz (165.2 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

scale_nucleus-0.20.0-cp314-cp314-win_amd64.whl (212.2 kB view details)

Uploaded CPython 3.14Windows x86-64

scale_nucleus-0.20.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (226.1 kB view details)

Uploaded CPython 3.14manylinux: glibc 2.28+ x86-64manylinux: glibc 2.5+ x86-64

scale_nucleus-0.20.0-cp314-cp314-macosx_11_0_arm64.whl (209.7 kB view details)

Uploaded CPython 3.14macOS 11.0+ ARM64

scale_nucleus-0.20.0-cp313-cp313-win_amd64.whl (212.3 kB view details)

Uploaded CPython 3.13Windows x86-64

scale_nucleus-0.20.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (226.0 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.28+ x86-64manylinux: glibc 2.5+ x86-64

scale_nucleus-0.20.0-cp313-cp313-macosx_11_0_arm64.whl (209.6 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

scale_nucleus-0.20.0-cp312-cp312-win_amd64.whl (212.3 kB view details)

Uploaded CPython 3.12Windows x86-64

scale_nucleus-0.20.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (226.0 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.28+ x86-64manylinux: glibc 2.5+ x86-64

scale_nucleus-0.20.0-cp312-cp312-macosx_11_0_arm64.whl (209.6 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

scale_nucleus-0.20.0-cp311-cp311-win_amd64.whl (212.3 kB view details)

Uploaded CPython 3.11Windows x86-64

scale_nucleus-0.20.0-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (225.6 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.28+ x86-64manylinux: glibc 2.5+ x86-64

scale_nucleus-0.20.0-cp311-cp311-macosx_11_0_arm64.whl (209.6 kB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

scale_nucleus-0.20.0-cp310-cp310-win_amd64.whl (212.3 kB view details)

Uploaded CPython 3.10Windows x86-64

scale_nucleus-0.20.0-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (225.3 kB view details)

Uploaded CPython 3.10manylinux: glibc 2.28+ x86-64manylinux: glibc 2.5+ x86-64

scale_nucleus-0.20.0-cp310-cp310-macosx_11_0_arm64.whl (209.6 kB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

File details

Details for the file scale_nucleus-0.20.0.tar.gz.

File metadata

  • Download URL: scale_nucleus-0.20.0.tar.gz
  • Upload date:
  • Size: 165.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.4.1 CPython/3.10.20 Linux/7.0.0-1009-aws

File hashes

Hashes for scale_nucleus-0.20.0.tar.gz
Algorithm Hash digest
SHA256 e55f12e4944ed5a55d590d56782e18a25ff2962714ae153434415c69abaa82cd
MD5 861f8fd7a4563db1b6604e2b0cc6e891
BLAKE2b-256 5ad36e236920803d473c428a1c856159730bba15c3cb537ee82b85f800b761ac

See more details on using hashes here.

File details

Details for the file scale_nucleus-0.20.0-cp314-cp314-win_amd64.whl.

File metadata

  • Download URL: scale_nucleus-0.20.0-cp314-cp314-win_amd64.whl
  • Upload date:
  • Size: 212.2 kB
  • Tags: CPython 3.14, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.4.1 CPython/3.10.20 Linux/7.0.0-1009-aws

File hashes

Hashes for scale_nucleus-0.20.0-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 8bb6d8bcd829dfac8f14a831e11a21c9750fb896461c1198195f89617b18e307
MD5 bf590086a1a99f10359a844e8fc70dad
BLAKE2b-256 4e4f5a1a1e6ef6fd81c8b88a420fb0d5aae7f8b06dbff8bcf2906f818242692c

See more details on using hashes here.

File details

Details for the file scale_nucleus-0.20.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for scale_nucleus-0.20.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 515a524c7df2b29647106380cded3aaa96091bdb1c204e7603d13e0c81611746
MD5 67f6e088135a87acf79788b0fce75ebc
BLAKE2b-256 f2e0622d59d8e2492e9b2e10598f2b9b992c24a5e95385d9b96aaeaff0640bdb

See more details on using hashes here.

File details

Details for the file scale_nucleus-0.20.0-cp314-cp314-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for scale_nucleus-0.20.0-cp314-cp314-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 850e41cfb21ad48f8be208a02366b4e82f76a86604b060c4e6c8d4694b5b74f5
MD5 c8be65409fb8169e690fca77484347ee
BLAKE2b-256 8e6eb56aef782777646456f01bc04d03dc543af33637c4d0ca018937522ef1c6

See more details on using hashes here.

File details

Details for the file scale_nucleus-0.20.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: scale_nucleus-0.20.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 212.3 kB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.4.1 CPython/3.10.20 Linux/7.0.0-1009-aws

File hashes

Hashes for scale_nucleus-0.20.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 6d70d139b858cca6506db1ecc8ddbb35cb3fd07abe73fca1277765ece9fc8ffa
MD5 1e5f92e1efad10f5a2e943fa5938e459
BLAKE2b-256 a1016190ad4aea1d9ef31dbaa696b631c1b1baae8c594eed52f95a0497f0dfeb

See more details on using hashes here.

File details

Details for the file scale_nucleus-0.20.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for scale_nucleus-0.20.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 90dcbaf329727108e1246d3f40eec9da0f289de2bacd638b8e9d3faebc6838fb
MD5 c40b2103a9fe8823d9f6281ffc72558e
BLAKE2b-256 92b061a13e8d276e5cf01bff593edcd7895b878f731d40351a94c9b0031bd3b6

See more details on using hashes here.

File details

Details for the file scale_nucleus-0.20.0-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for scale_nucleus-0.20.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2116c2707049c2ac708093a7dbd36b6ca387d475ee01d2f9c40c503e32e5ec8a
MD5 5432eac3795b1979b75b27f5f4206956
BLAKE2b-256 acfee408cd186f3fcb210009c948c20fa63eee8ecccd16802ca09a8b38ae39b2

See more details on using hashes here.

File details

Details for the file scale_nucleus-0.20.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: scale_nucleus-0.20.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 212.3 kB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.4.1 CPython/3.10.20 Linux/7.0.0-1009-aws

File hashes

Hashes for scale_nucleus-0.20.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 93a725b523cff83bae5400a51f5917c873688817a99027e76cfa3a3c196c8942
MD5 9cc11ec7a76b89e6fba8bd04deed6b29
BLAKE2b-256 127e6da500dfe746f9746fcf2727428b8aed3693ceaaaecfbce8e350413bb408

See more details on using hashes here.

File details

Details for the file scale_nucleus-0.20.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for scale_nucleus-0.20.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 1af1a6ed5f6d107914a4ec8d44bcbb07c769fec12794d23a12d468a71b19f18a
MD5 860cfeb0a1e44db73be3c1292efa7bc4
BLAKE2b-256 aa72878d2a08f68fa9aac4d0923837ceace88b62343c11d8a6723a0fd874afb0

See more details on using hashes here.

File details

Details for the file scale_nucleus-0.20.0-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for scale_nucleus-0.20.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 0affb47819eabb03ea48a86ab79dcc54908a170654cc09f97c1494969a8ce354
MD5 96004649f5a675e5099a9f1f8b7f7bc1
BLAKE2b-256 efd5c5e5c67f8962bebba90f46c1f585002ca303566ed82b0f9781ba61fc6406

See more details on using hashes here.

File details

Details for the file scale_nucleus-0.20.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: scale_nucleus-0.20.0-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 212.3 kB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.4.1 CPython/3.10.20 Linux/7.0.0-1009-aws

File hashes

Hashes for scale_nucleus-0.20.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 69bdd5b85fbc623496fe480bebdcb37b3b24348994aafc83f61e0b1da98323b2
MD5 5407b3f87a4030d39a0f3c2826136772
BLAKE2b-256 e09da48721786b2666dbb36a18b0a0b2f019f1bfbb8f12fd7a85b01d8fc10274

See more details on using hashes here.

File details

Details for the file scale_nucleus-0.20.0-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for scale_nucleus-0.20.0-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 4bd436dd55800aa0e9e96db0e9bbf4abe2be0e1db5c8fd9d8d7c2efaf51c50e7
MD5 5b223890277d1dccdf11e24dc79dcb71
BLAKE2b-256 856b8d992b307f7123e8855a65e195a5b0b0e192769f33dede25dd99b66f8019

See more details on using hashes here.

File details

Details for the file scale_nucleus-0.20.0-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for scale_nucleus-0.20.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 b26765c6ea910aefb7bb4778bee63ff0ef50aa86b19ff136a5dc86f94b443d8c
MD5 81ae4097976338f069590b8fb1c87f53
BLAKE2b-256 7ef923ed9216a5894b35aea8ecb06109b5c3c3f941492013c265ee4070570893

See more details on using hashes here.

File details

Details for the file scale_nucleus-0.20.0-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: scale_nucleus-0.20.0-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 212.3 kB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.4.1 CPython/3.10.20 Linux/7.0.0-1009-aws

File hashes

Hashes for scale_nucleus-0.20.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 2de640d6ee1ba20a8ef50e13773a746fc367f8cc95a843e3068e0d50f4ae9ef0
MD5 ee7ff02caf14e2e2818742c53dff5eea
BLAKE2b-256 b34b68d39c9b50e796aaa118b6f93f07b7eaac805ff6df2f63e43f42aa15ec94

See more details on using hashes here.

File details

Details for the file scale_nucleus-0.20.0-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for scale_nucleus-0.20.0-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 4e32b43527422a815999b2b7123dbe55f11bccd66f2c9a3bc8581af8f882d873
MD5 a488d92baf667c211591948e41632e0f
BLAKE2b-256 b50248619ed53a047359841ec9bffbdc03af756af95ee5e72c5669e743e5014b

See more details on using hashes here.

File details

Details for the file scale_nucleus-0.20.0-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for scale_nucleus-0.20.0-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 78b8d0df6aa0dcbce691490c2f35a9175a18fe538097218c0879b433d5e26970
MD5 2af8b085055f429d0707903fe67e830a
BLAKE2b-256 95bd8307409777b0a5f0e053149ccc9600ac31c499362bed2aa532e06633c374

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

0.20.0

0.19.0

0.18.4

0.18.3

0.18.1

0.17.14

0.17.13

0.17.12

0.17.11

0.17.10

0.17.9

0.17.8

0.17.7

0.17.6

0.17.6b4 pre-release

0.17.6b3 pre-release

0.17.6b2 pre-release

0.17.6b1 pre-release

0.17.6b0 pre-release

0.17.5

0.17.3

0.17.2

0.17.1

0.17.0

0.16.18

0.16.17

0.16.16

0.16.15

0.16.14

0.16.13

0.16.12

0.16.11

0.16.10

0.16.8

0.16.7

0.16.6

0.16.5

0.16.4

0.16.3

0.16.2

0.16.1

0.15.10

0.15.10b0 pre-release

0.15.8

0.15.7

0.15.6

0.15.5

0.15.4

0.15.3

0.15.2

0.15.1

0.15.0

0.14.29

0.14.28

0.14.27

0.14.26

0.14.25

0.14.24

0.14.23

0.14.21

0.14.20

0.14.17

0.14.16

0.14.15

0.14.14

0.14.14b0 pre-release

0.14.13b2 pre-release

0.14.12

0.14.12b1 pre-release

0.14.12b0 pre-release

0.14.10

0.14.9

0.14.8

0.14.8b0 pre-release

0.14.7

0.14.5

0.14.5b1 pre-release

0.14.5b0 pre-release

0.14.4

0.14.3

0.14.2

0.14.1

0.14.0

0.14b2 pre-release

0.14b1 pre-release

0.14b0 pre-release

0.13.4

0.13.3

0.13.2

0.13.1

0.13.0

0.13b2 pre-release

0.13b1 pre-release

0.13b0 pre-release

0.12.4

0.12b10 pre-release

0.12b9 pre-release

0.12b8 pre-release

0.12b7 pre-release

0.12b5 pre-release

0.12b4 pre-release

0.12b3 pre-release

0.12b2 pre-release

0.12b1 pre-release

0.11.2

0.11.1

0.11.0

0.11b2 pre-release

0.11b1 pre-release

0.10.7

0.10.6

0.10.5

0.10.4

0.10.3

0.10.1

0.10.0

0.10b1 pre-release

0.10b0 pre-release

0.9.0

0.9b6 pre-release

0.9b5 pre-release

0.9b4 pre-release

0.9b3 pre-release

0.8.4

0.8.3

0.8.2

0.8.1

0.8.0

0.7.0

0.7b2 pre-release

0.7b0 pre-release

0.6.7

0.6.6

0.6.4

0.6.3

0.6.1

0.6.0

0.6b4 pre-release

0.6b3 pre-release

0.6b2 pre-release

0.6b0 pre-release

0.5.2

0.5.1

0.5.0

0.4.5

0.4.4

0.4.3

0.4.2

0.4.1

0.4.0

0.3.3

0.3.2

0.3.1

0.3.0

0.1.25

0.1.24

0.1.22

0.1.21

0.1.20

0.1.19

0.1.18

0.1.17

0.1.15

0.1.14

0.1.13

0.1.12

0.1.11

0.1.10

0.1.8

0.1.7

0.1.6

0.1.5

0.1.4

0.1.3

0.1.2

0.1.1

0.1.0

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page