Nuuduu

Python SDK and CLI for Nuuduu Atlas — search, request, and sync robotics training datasets (LeRobot, MCAP, HEVC) to your local machine for PyTorch / LeRobot workflows.

Installation

# Library only
pip install nuuduu

# Library + CLI command
pip install nuuduu[cli]

Development install:

git clone https://github.com/nuuduu/nuuduu.git
cd nuuduu
uv sync --all-extras

Quick start (CLI)

# Authenticate (saves token to ~/.config/nuuduu/config.toml, mode 0600)
nuuduu auth login

# Search episodes
nuuduu episodes search --text "pick up cup"

# Request a LeRobot bundle
nuuduu episodes download --format lerobot --uuids "<uuid-1>,<uuid-2>"

# Sync ready bundles to your local dataset directory
nuuduu sync

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

Quick start (library)

from nuuduu import NuuduuAtlas

atlas = NuuduuAtlas.from_config()

episodes = atlas.search_episodes(text="fold laundry", limit=10)
job = atlas.request_download(
    format="lerobot",
    uuids=[ep.uuid for ep in episodes if ep.uuid],
)

result = atlas.sync(format="lerobot")
for bundle in result.synced:
    print(bundle.path)

Authentication

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 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 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 downloads list
nuuduu downloads status [ID]
nuuduu downloads cancel ID

nuuduu episodes search [--text QUERY] [--country CODE] [--assignment UUID] [--limit N]
nuuduu episodes latest [--limit N]
nuuduu episodes download --format FORMAT --uuids UUID[,UUID...] [--wait]

nuuduu requests list
nuuduu requests create --task TEXT --episodes N

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

Download 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

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.

Publishing

# Bump version in pyproject.toml and CHANGELOG.md
uv build
git tag v0.1.0 && git push --tags   # triggers PyPI publish workflow

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.