Nuuduu

Nuuduu is a Python SDK and CLI that gets robotics training data from the Nuuduu Atlas library onto your machine as a PyTorch-ready dataset — and automatically requests new data collection when the library does not have enough.

Use what Atlas already has, or combine --min-episodes on bundle to bundle available episodes and request the rest in one command.

The CLI talks to the API at nuuduu.com. Browse episodes in the Atlas web app. v1 may still send you to the web app for some bundle payments; the destination is fully in-CLI purchase (see Roadmap).

Source repository: bitbucket.org/nuuduu/nuuduu

Installation

# Library only
pip install nuuduu

# Library + CLI command (quote brackets so the shell does not treat them as globs)
pip install 'nuuduu[cli]'

Development install:

git clone git@bitbucket.org:nuuduu/nuuduu.git
cd nuuduu
uv sync --all-extras

How it works

Atlas library                    Your machine
─────────────                    ────────────
  search  ──→  find episodes
  bundle  ──→  package as LeRobot / MCAP / HEVC dataset
  sync    ──→  download  ──→  PyTorch / LeRobot training dataset

  request ──→  collect new episodes (when library is short)
       ↑
       └── triggered automatically by bundle --min-episodes

Typical path — library has enough data:

nuuduu episodes search --text "shirt folding"   # explore + see total price
nuuduu episodes bundle --text "shirt folding"   # purchase + package
nuuduu sync                                     # download locally

When you need more than the library has:

nuuduu episodes bundle --text "shirt folding" --country fi,ee --min-episodes 10000
# bundles 6 000 available episodes, requests collection of the remaining 4 000
nuuduu sync   # run again as bundles become ready

The default output format is LeRobot v2.1, ready for PyTorch training via LeRobot or your own data loader.

Quick start (CLI)

nuuduu auth login

# 1. Search the Atlas library
nuuduu episodes search --text "pick up cup"

# 2. Bundle into a training dataset (confirms total price before purchase)
nuuduu episodes bundle --text "pick up cup"

# 3. Download to your local dataset directory
nuuduu sync

# 4. Train — LeRobot example
python -c "
from lerobot.common.datasets.lerobot_dataset import LeRobotDataset
dataset = LeRobotDataset('local', root='~/.cache/huggingface/lerobot/nuuduu-atlas/<download-uuid>')
print(len(dataset))
"

Need episodes that are not in the library yet? Use --min-episodes to bundle what's available and request collection of the rest, or request directly:

nuuduu episodes bundle --text "shirt folding" --min-episodes 10000 --country fi,ee
nuuduu request --text "pick and place red blocks" --episodes 1000 --country fi,ee

Quick start (library)

from nuuduu import NuuduuAtlas

atlas = NuuduuAtlas.from_config()

# Search the Atlas library
episodes = atlas.search_episodes(text="shirt folding", country="fi,ee", limit=100)
print(f"Found {len(episodes)} episodes")

# Bundle available episodes; automatically request collection for any shortfall
bundle = atlas.bundle_episodes(
    text="shirt folding",
    country="fi,ee",
    min_episodes=10000,
    confirm_request=True,
)
print(f"{bundle.bundled_episodes} bundled, {bundle.requested_episodes} requested")

# Download ready bundles to a local PyTorch-ready dataset
result = atlas.sync(format="lerobot")
for item in result.synced:
    print(item.path)  # e.g. .../lerobot/<uuid>/

Authentication

Use the same email and password as your Atlas web app account. The CLI authenticates against the API at https://nuuduu.com with type=api.

Credentials are stored at ~/.config/nuuduu/config.toml with 0600 permissions. The CLI refuses to read config files that are group- or world-readable.

nuuduu auth login              # email + password → saves token
nuuduu auth logout             # clear saved token
nuuduu auth token set TOKEN    # set token manually
nuuduu auth status             # show masked token status

Tokens expire after 24 hours in production. On HTTP 401, run nuuduu auth login again.

Dataset directory

Resolved automatically via priority chain:

1. --dataset-dir CLI flag
2. NUUDUU_DATASET_DIR environment variable
3. dataset_dir in config file
4. HF_LEROBOT_HOME/nuuduu-atlas (LeRobot ecosystem default)
5. Project .env, training configs, or ./datasets/nuuduu-atlas
6. Fallback: ~/.cache/huggingface/lerobot/nuuduu-atlas

nuuduu config show   # shows resolved path and source

Local layout:

{dataset_dir}/
  .nuuduu/manifest.json
  lerobot/{download_uuid}/     # LeRobot v2.1 dataset
  mcap/{download_uuid}/        # per-episode .mcap files
  hevc/{download_uuid}/        # per-episode .mp4 files

CLI reference

nuuduu --help
nuuduu --version

nuuduu auth login
nuuduu auth logout
nuuduu auth token set TOKEN
nuuduu auth status

nuuduu config show
nuuduu config set KEY VALUE

nuuduu sync [--dataset-dir PATH] [--format lerobot|mcap|hevc|all] [--dry-run] [--verify]

nuuduu episodes search [--text QUERY] [--country fi,ee] [--limit N]
nuuduu episodes latest [--limit N]
nuuduu episodes bundle [--text QUERY] [--country fi,ee] [--limit N] \
  [--min-episodes N] [--format lerobot|mcap|hevc] [--uuids UUID[,UUID...]] \
  [--wait] [--yes]

nuuduu request --text "TASK" --episodes N [--country fi,ee] [--yes]
nuuduu request list

Add --json to any command for machine-readable output.

Shared search options

These options work the same on episodes search, episodes bundle, and request:

episodes search prints a total price line after the results table. episodes bundle shows the same total and prompts Proceed with bundle purchase? [Y/n] before creating the bundle.

Bundle-specific options

Roadmap

v1 (today): Search the Atlas library, bundle episodes into a training dataset, and download locally with nuuduu sync. Some paid bundles still require completing payment in the Atlas web app before download.

Destination UX — order new data entirely from the terminal:

nuuduu request --text "pick and place red blocks" --episodes 1000

Estimated price: €742
Available immediately: 681 episodes
To collect: 319 episodes

Purchase using Acme Robotics account? [Y/n]

After confirmation, Atlas fulfills the order and nuuduu sync materializes bundles locally. No browser step.

Output formats

Bundles are written to your local dataset directory in one of these formats:

Integrity verification

When the Atlas API provides a hash field (SHA256 of the bundle zip), nuuduu sync:

1. Verifies the downloaded zip before extracting
2. Stores the hash in .nuuduu/manifest.json
3. Skips re-download when the local hash matches

nuuduu sync --verify   # re-check local bundles without downloading

Library API

Key methods on NuuduuAtlas:

Exceptions: AuthError, ApiError, IntegrityError, ConfigError, NotFoundError

Progress callbacks for sync:

from nuuduu.types import SyncProgressEvent

def on_progress(event: SyncProgressEvent) -> None:
    print(event.phase, event.bytes_done, event.bytes_total)

atlas.sync(on_progress=on_progress)

Troubleshooting

Development

uv sync --all-extras
uv run pytest
uv build

See CONTRIBUTING.md for release and contribution guidelines.

CI runs on Bitbucket Pipelines for every push and pull request.

Publishing

# Bump version in pyproject.toml and CHANGELOG.md
uv build
git tag v0.4.0 && git push origin v0.4.0   # triggers Bitbucket Pipeline PyPI publish

One-time setup: add a secured PYPI_TOKEN repository variable in Bitbucket → Repository settings → Pipelines → Repository variables.

Legal

Copyright © 2026 Nuuduu UAB. Licensed under the MIT License.

Nuuduu® is a registered trademark of Nuuduu UAB. All rights reserved. The Nuuduu name and logo may not be used to imply endorsement or affiliation without prior written permission from Nuuduu UAB.