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.ai. Manage your account and payment method in the Atlas web app.

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
pip install -e '.[dev]'
pytest

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 search --text "shirt folding"   # explore + see total price
nuuduu bundle --text "shirt folding"   # purchase + package
nuuduu sync                                     # download locally

When you need more than the library has:

nuuduu 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 v3.0, ready for PyTorch training via LeRobot or your own data loader.

Quick start (CLI)

nuuduu auth login

# 1. Search Atlas
nuuduu search --text "fold a t-shirt"

# 2. Get 1,000 episodes bundled as LeRobot v3.0
# Existing episodes are used immediately and any shortfall is collected.
nuuduu bundle \
  --text "fold a t-shirt" \
  --min-episodes 1000 \
  --profile nuuduu

# 3. Download the dataset somewhere explicit
nuuduu sync --dataset-dir ~/nuuduu-atlas/datasets

# 4. Train with LeRobot
python -m lerobot.scripts.train \
  --dataset.repo_id=local \
  --dataset.root=~/nuuduu-atlas/datasets/lerobot/<download-uuid> \
  ...

Example output:

$ nuuduu auth login
✓ Logged in as researcher@acme.ai

$ nuuduu search --text "fold a t-shirt"
681 episodes found · $486.32 available now

$ nuuduu bundle --text "fold a t-shirt" --min-episodes 1000 --profile nuuduu
Available now: 681   To collect: 319
Estimated total: $742.00
Confirm purchase? [Y/n] y
✓ Bundle 7f3c2a91 created · LeRobot v3.0 · Nuuduu Ego

$ nuuduu sync --dataset-dir ~/nuuduu-atlas/datasets
✓ 681 episodes synced
~/nuuduu-atlas/datasets/lerobot/7f3c2a91

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 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,
    profile="nuuduu",
    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. nuuduu auth login calls POST /api/atlas/login with type=api and creates a named API key (default name Nuuduu CLI; override with --name). The returned token is long-lived (unlike 24-hour web session tokens).

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 → creates API key, saves token
nuuduu auth login --name "CI"  # custom label for the API key in Atlas settings
nuuduu auth logout             # clear saved token
nuuduu auth token set TOKEN    # set token manually
nuuduu auth status             # show masked token status

On HTTP 401, run nuuduu auth login again or set a valid API key from the Atlas web app.

Payment

When you confirm a bundle or collection request in the CLI, payment is charged automatically to the default payment method on your Atlas account. No browser step or extra checkout flow is required.

The only payment issues you may see:

nuuduu search shows the total price. nuuduu bundle and nuuduu request ask for confirmation before charging, then let you pick a saved card from Atlas (default card first; press Enter to accept). Use --default-card to charge the default card without the picker (required for --json purchases).

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: ~/nuuduu-atlas/datasets

The dataset directory is created automatically on first sync if it does not exist.

nuuduu config show   # shows resolved path and source

Local layout:

{dataset_dir}/
  .nuuduu/manifest.json
  lerobot/{download_uuid}/     # LeRobot v3.0 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 service-types [--json]

nuuduu search [--text QUERY] [--country fi,ee] [--service-types SLUG[,SLUG...]] [--limit N]
nuuduu bundle [--text QUERY] [--country fi,ee] [--service-types SLUG[,SLUG...]] [--limit N] \
  [--min-episodes N] [--format lerobot|mcap|hevc] \
  [--profile nuuduu] \
  [--uuids UUID[,UUID...]] [--wait] [--yes] [--default-card]

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

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

Shared search options

These options work the same on search and bundle (request supports --text and --country only):

Service types

List available service types (assignments) sorted alphabetically by slug:

nuuduu service-types

folding          7f3c2a91-...
pick-and-place   a1b2c3d4-...

Filter search and bundle results by slug:

nuuduu search --text "fold a t-shirt" --service-types folding,pick-and-place
nuuduu bundle --text "fold a t-shirt" --service-types folding --min-episodes 100

nuuduu search prints a one-line summary with episode count and total price. nuuduu bundle shows a purchase preview and prompts for confirmation before charging your saved payment method.

Bundle-specific options

Dataset profile

Use --profile nuuduu on nuuduu bundle to export in the Nuuduu Ego LeRobot v3.0 layout. Field names, observation keys, and episode structure are defined in the Nuuduu Ego profile specification.

Collection requests

Order new data to be collected when the library does not have enough:

nuuduu request --text "pick and place red blocks" --episodes 1000 --country fi,ee

Available now: 681   To collect: 319
Estimated total: $742.00
Confirm purchase? [Y/n]

After confirmation, Atlas collects the episodes. Run nuuduu sync as bundles become ready.

Note: the collection request API may return 404 until the backend endpoint is fully live — the CLI shows a preview of the intended UX when that happens.

Output formats

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

Integrity verification

When the Atlas API provides a sha256 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

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.