vlakit 0.1.0__tar.gz

vlakit-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# vlakit — never commit real secrets or a user's local config dir
+**/secrets.local.env
+/configs/
+
+# OS / editor
+.DS_Store
+.vscode/

vlakit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkipngenokoech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vlakit-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: vlakit
+Version: 0.1.0
+Summary: Config-driven CLI to launch, monitor, and ship VLA fine-tunes across ephemeral GPU boxes.
+Project-URL: Homepage, https://github.com/kkipngenokoech/vlakit
+Project-URL: Issues, https://github.com/kkipngenokoech/vlakit/issues
+Author-email: kkipngenokoech <kkipngenokoech22@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: fine-tuning,lerobot,molmoact,openpi,robotics,vla
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: numpy; extra == 'all'
+Requires-Dist: pyarrow; extra == 'all'
+Requires-Dist: pyyaml; extra == 'all'
+Requires-Dist: wandb; extra == 'all'
+Provides-Extra: stats
+Requires-Dist: numpy; extra == 'stats'
+Requires-Dist: pyarrow; extra == 'stats'
+Provides-Extra: wandb
+Requires-Dist: wandb; extra == 'wandb'
+Provides-Extra: yaml
+Requires-Dist: pyyaml; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# vlakit
+
+`vlakit` is a config-driven command-line tool for launching VLA fine-tunes across **ephemeral GPU boxes**, keeping them alive through crashes, and shipping verified weights to durable storage. You describe a run in YAML and drive everything with a single `vla` command from your laptop; the actual work runs on a GPU box over ssh, and the durable artifacts land on Weights & Biases and a storage box — never on the GPU box, which you throw away.
+
+It packages a set of battle-tested shell and Python scripts (the ones that encode the hard-won operational lessons) behind a friendly CLI. The scripts ship with the install as read-only package data, while your environment — the boxes, datasets, baselines, and runs — lives in a `configs/` directory you own and edit.
+
+## Install
+
+`vlakit` is best installed as an isolated CLI with [pipx](https://pipx.pypa.io):
+
+```bash
+pipx install vlakit
+```
+
+Or with pip. The core install is dependency-light because the laptop-side commands need almost nothing; the heavier pieces are opt-in extras:
+
+```bash
+pip install vlakit                 # laptop-side: config / remote / launch
+pip install "vlakit[stats]"        # adds numpy + pyarrow for `vla stats`
+pip install "vlakit[wandb]"        # adds wandb for publish / pull / eval logging
+pip install "vlakit[all]"          # everything
+```
+
+## Quickstart
+
+```bash
+vla init                           # scaffold an editable ./configs from templates
+# edit configs/boxes.yaml, datasets.yaml, baselines.yaml, and a runs/<name>.yaml
+# then copy configs/secrets.example.env -> configs/secrets.local.env and fill it
+
+vla config <run>                   # resolve + print the run config (local, no box)
+vla remote <box> deploy            # rsync the toolkit + your configs onto the box
+vla remote <box> push-secrets      # install ~/.secrets.env on the box (mode 600)
+vla remote <box> ensure-swap       # provision swap (absorbs the checkpoint-save spike)
+vla launch <run>                   # launch detached + auto-resume (box read from the run cfg)
+vla remote <box> monitor           # step / rate / ETA + liveness
+```
+
+## Where each command runs
+
+`vlakit` keeps a clean split between your laptop and the GPU box. Commands that resolve or inspect configuration — `init`, `config`, `stats`, `split`, `eval`, `doctor` — run entirely on your **laptop** and need no box. Commands that operate on a machine — everything under `vla remote ...`, and `vla launch` — open an ssh connection from your laptop and run the work **on the box** defined in your `boxes.yaml`.
+
+Run `vla doctor` to see exactly which scripts directory and config directory were resolved, and which optional dependencies are installed.
+
+## Commands
+
+| Command | Runs | What it does |
+|---|---|---|
+| `vla init [dir]` | laptop | Scaffolds an editable `configs/` directory from the bundled templates. |
+| `vla config <run>` | laptop | Resolves a run (defaults merged under the run) and prints the config plus the exact command, running nothing. |
+| `vla remote <box> <subcmd> [args]` | box | Runs an operational subcommand on the box: `deploy`, `push-secrets`, `ensure-swap`, `launch`, `autoresume`, `monitor`, `kill`, `rescale`, `pull`, `gpus`, `exec`, `shell`. |
+| `vla launch <run>` | box | Launches the run detached and auto-resuming; the box is read from the run's `box:` field. |
+| `vla stats [args]` | laptop/box | Computes the full dataset statistics (quantiles + image stats) that lerobot and molmo need. Requires the `[stats]` extra. |
+| `vla split [args]` | laptop | Produces a deterministic held-out episode split for validation/eval. |
+| `vla eval [args]` | laptop/box | Ranks a checkpoint by held-out error or rollout, not loss. Try `vla eval --self-test` to verify the harness with no box. |
+| `vla doctor` | laptop | Prints the resolved scripts/config directories and optional-dependency status. |
+
+## Configuration
+
+Your `configs/` directory holds everything dynamic, and no secrets ever live in it: keys resolve on the box via `~/.secrets.env`. The directory is resolved from `--config-dir`, then the `VLA_CONFIG_DIR` environment variable, then `./configs`. A run file under `runs/` is a thin recipe that names a `box`, a `dataset`, and a `baseline` — each a pointer into the corresponding registry — plus a few hyperparameters; everything else is inherited from `_defaults.yaml`.
+
+## Status
+
+The local commands (`init`, `config`, `stats`, `split`, `eval`, `doctor`) are implemented and tested. The remote commands shell out to the bundled, proven ops scripts; `vla remote <box> deploy` now ships both the toolkit and your `configs/` to the box. The `eval` offline comparator is implemented and self-tested (`vla eval --self-test`); its sim and robot rollout modes are still stubs.
+
+## Publishing (maintainers)
+
+Releases publish to PyPI automatically through [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC), so no API token is stored anywhere. The workflow is [`.github/workflows/release.yml`](.github/workflows/release.yml).
+
+One-time setup:
+
+1. On PyPI, add a **pending** Trusted Publisher (Account → Publishing) with these exact values:
+   - PyPI Project Name: `vlakit`
+   - Owner: `kkipngenokoech`
+   - Repository name: `vlakit`
+   - Workflow name: `release.yml`
+   - Environment name: `pypi`
+2. In the GitHub repo, create an Environment named `pypi` (Settings → Environments).
+
+To cut a release, tag a version that matches `pyproject.toml` and push it:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The workflow builds the sdist + wheel, verifies the bundled scripts/templates are inside the wheel, checks the tag matches the package version, and publishes. After the first successful run the pending publisher becomes a normal one, and `pipx install vlakit` works for everyone.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

vlakit-0.1.0/README.md

@@ -0,0 +1,91 @@
+# vlakit
+
+`vlakit` is a config-driven command-line tool for launching VLA fine-tunes across **ephemeral GPU boxes**, keeping them alive through crashes, and shipping verified weights to durable storage. You describe a run in YAML and drive everything with a single `vla` command from your laptop; the actual work runs on a GPU box over ssh, and the durable artifacts land on Weights & Biases and a storage box — never on the GPU box, which you throw away.
+
+It packages a set of battle-tested shell and Python scripts (the ones that encode the hard-won operational lessons) behind a friendly CLI. The scripts ship with the install as read-only package data, while your environment — the boxes, datasets, baselines, and runs — lives in a `configs/` directory you own and edit.
+
+## Install
+
+`vlakit` is best installed as an isolated CLI with [pipx](https://pipx.pypa.io):
+
+```bash
+pipx install vlakit
+```
+
+Or with pip. The core install is dependency-light because the laptop-side commands need almost nothing; the heavier pieces are opt-in extras:
+
+```bash
+pip install vlakit                 # laptop-side: config / remote / launch
+pip install "vlakit[stats]"        # adds numpy + pyarrow for `vla stats`
+pip install "vlakit[wandb]"        # adds wandb for publish / pull / eval logging
+pip install "vlakit[all]"          # everything
+```
+
+## Quickstart
+
+```bash
+vla init                           # scaffold an editable ./configs from templates
+# edit configs/boxes.yaml, datasets.yaml, baselines.yaml, and a runs/<name>.yaml
+# then copy configs/secrets.example.env -> configs/secrets.local.env and fill it
+
+vla config <run>                   # resolve + print the run config (local, no box)
+vla remote <box> deploy            # rsync the toolkit + your configs onto the box
+vla remote <box> push-secrets      # install ~/.secrets.env on the box (mode 600)
+vla remote <box> ensure-swap       # provision swap (absorbs the checkpoint-save spike)
+vla launch <run>                   # launch detached + auto-resume (box read from the run cfg)
+vla remote <box> monitor           # step / rate / ETA + liveness
+```
+
+## Where each command runs
+
+`vlakit` keeps a clean split between your laptop and the GPU box. Commands that resolve or inspect configuration — `init`, `config`, `stats`, `split`, `eval`, `doctor` — run entirely on your **laptop** and need no box. Commands that operate on a machine — everything under `vla remote ...`, and `vla launch` — open an ssh connection from your laptop and run the work **on the box** defined in your `boxes.yaml`.
+
+Run `vla doctor` to see exactly which scripts directory and config directory were resolved, and which optional dependencies are installed.
+
+## Commands
+
+| Command | Runs | What it does |
+|---|---|---|
+| `vla init [dir]` | laptop | Scaffolds an editable `configs/` directory from the bundled templates. |
+| `vla config <run>` | laptop | Resolves a run (defaults merged under the run) and prints the config plus the exact command, running nothing. |
+| `vla remote <box> <subcmd> [args]` | box | Runs an operational subcommand on the box: `deploy`, `push-secrets`, `ensure-swap`, `launch`, `autoresume`, `monitor`, `kill`, `rescale`, `pull`, `gpus`, `exec`, `shell`. |
+| `vla launch <run>` | box | Launches the run detached and auto-resuming; the box is read from the run's `box:` field. |
+| `vla stats [args]` | laptop/box | Computes the full dataset statistics (quantiles + image stats) that lerobot and molmo need. Requires the `[stats]` extra. |
+| `vla split [args]` | laptop | Produces a deterministic held-out episode split for validation/eval. |
+| `vla eval [args]` | laptop/box | Ranks a checkpoint by held-out error or rollout, not loss. Try `vla eval --self-test` to verify the harness with no box. |
+| `vla doctor` | laptop | Prints the resolved scripts/config directories and optional-dependency status. |
+
+## Configuration
+
+Your `configs/` directory holds everything dynamic, and no secrets ever live in it: keys resolve on the box via `~/.secrets.env`. The directory is resolved from `--config-dir`, then the `VLA_CONFIG_DIR` environment variable, then `./configs`. A run file under `runs/` is a thin recipe that names a `box`, a `dataset`, and a `baseline` — each a pointer into the corresponding registry — plus a few hyperparameters; everything else is inherited from `_defaults.yaml`.
+
+## Status
+
+The local commands (`init`, `config`, `stats`, `split`, `eval`, `doctor`) are implemented and tested. The remote commands shell out to the bundled, proven ops scripts; `vla remote <box> deploy` now ships both the toolkit and your `configs/` to the box. The `eval` offline comparator is implemented and self-tested (`vla eval --self-test`); its sim and robot rollout modes are still stubs.
+
+## Publishing (maintainers)
+
+Releases publish to PyPI automatically through [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC), so no API token is stored anywhere. The workflow is [`.github/workflows/release.yml`](.github/workflows/release.yml).
+
+One-time setup:
+
+1. On PyPI, add a **pending** Trusted Publisher (Account → Publishing) with these exact values:
+   - PyPI Project Name: `vlakit`
+   - Owner: `kkipngenokoech`
+   - Repository name: `vlakit`
+   - Workflow name: `release.yml`
+   - Environment name: `pypi`
+2. In the GitHub repo, create an Environment named `pypi` (Settings → Environments).
+
+To cut a release, tag a version that matches `pyproject.toml` and push it:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The workflow builds the sdist + wheel, verifies the bundled scripts/templates are inside the wheel, checks the tag matches the package version, and publishes. After the first successful run the pending publisher becomes a normal one, and `pipx install vlakit` works for everyone.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

vlakit-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vlakit"
+version = "0.1.0"
+description = "Config-driven CLI to launch, monitor, and ship VLA fine-tunes across ephemeral GPU boxes."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "kkipngenokoech", email = "kkipngenokoech22@gmail.com" }]
+keywords = ["vla", "fine-tuning", "robotics", "openpi", "lerobot", "molmoact"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "Operating System :: POSIX",
+]
+# Core stays light: the laptop-side commands (config/remote/launch) need nothing extra,
+# and PyYAML is optional because the bundled config reader falls back to grep/sed.
+dependencies = []
+
+[project.optional-dependencies]
+yaml  = ["pyyaml"]                  # faster/robust config parsing (else grep/sed fallback)
+stats = ["numpy", "pyarrow"]        # `vla stats` (compute_stats.py)
+wandb = ["wandb"]                   # publish / pull / eval logging
+all   = ["pyyaml", "numpy", "pyarrow", "wandb"]
+
+[project.scripts]
+vla = "vlakit.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/kkipngenokoech/vlakit"
+Issues = "https://github.com/kkipngenokoech/vlakit/issues"
+
+# src-layout: map src/vlakit -> vlakit. hatchling includes ALL files under the
+# package (the bundled scripts/ + templates/, not just .py) in the wheel by default,
+# so no force-include is needed — adding one would double-add files and fail the build.
+[tool.hatch.build.targets.wheel]
+packages = ["src/vlakit"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/vlakit", "README.md", "LICENSE"]

vlakit-0.1.0/src/vlakit/__init__.py

@@ -0,0 +1,8 @@
+"""vlakit — a config-driven CLI for launching and shipping VLA fine-tunes.
+
+The heavy lifting lives in battle-tested shell + Python scripts shipped as package
+data under `vlakit/scripts/`; this package's `cli` module is the friendly `vla`
+front door that resolves your config dir and dispatches to them.
+"""
+
+__version__ = "0.1.0"

vlakit-0.1.0/src/vlakit/cli.py

@@ -0,0 +1,199 @@
+"""vla — the command-line front door for vlakit.
+
+This module resolves two things and then hands off to the shipped scripts:
+
+  * the SCRIPTS dir   — the proven shell/Python toolkit, bundled as package data
+                        (vlakit/scripts/); exported to the scripts as FT_ROOT.
+  * the CONFIG dir    — YOUR editable configs (boxes/datasets/baselines/runs);
+                        resolved from --config-dir, then $VLA_CONFIG_DIR, then
+                        ./configs, and exported to the scripts as VLA_CONFIG_DIR.
+
+So the toolkit code is read-only and lives in the install, while your environment
+lives in a configs/ dir you own. `vla init` scaffolds that dir from templates.
+
+Commands that touch a GPU box (remote/launch/deploy/...) shell out to the bundled
+ops/remote.sh, which ssh's to the box defined in your boxes.yaml. Commands that run
+locally (config/stats/split/eval/init) do not need a box.
+"""
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+from contextlib import ExitStack
+from importlib.resources import files, as_file
+
+from . import __version__
+
+
+def _scripts_root(stack):
+    """Return a real filesystem path to the bundled scripts/ dir.
+
+    Uses importlib.resources so it works whether installed as a wheel, an editable
+    install, or run straight from the source tree. `stack` is an ExitStack that keeps
+    any extracted temp dir alive for the duration of the call.
+    """
+    return str(stack.enter_context(as_file(files("vlakit") / "scripts")))
+
+
+def _templates_configs(stack):
+    return str(stack.enter_context(as_file(files("vlakit") / "templates" / "configs")))
+
+
+def _config_dir(args, *, required=True):
+    """Resolve the user's config dir: --config-dir, then $VLA_CONFIG_DIR, then ./configs."""
+    cand = args.config_dir or os.environ.get("VLA_CONFIG_DIR") or os.path.join(os.getcwd(), "configs")
+    if required and not os.path.isdir(cand):
+        sys.exit(f"config dir not found: {cand}\n  run `vla init` to scaffold one, "
+                 f"or pass --config-dir / set VLA_CONFIG_DIR")
+    return cand
+
+
+def _env(scripts, config_dir=None):
+    """Build the environment the scripts expect: FT_ROOT + (optionally) VLA_CONFIG_DIR."""
+    env = dict(os.environ)
+    env["FT_ROOT"] = scripts
+    if config_dir:
+        env["VLA_CONFIG_DIR"] = config_dir
+    return env
+
+
+def _run(cmd, env):
+    """Run a subprocess, echo it, and propagate its exit code."""
+    print(f"# $ {' '.join(cmd)}", file=sys.stderr)
+    return subprocess.run(cmd, env=env).returncode
+
+
+# --------------------------------------------------------------------------- #
+# commands
+# --------------------------------------------------------------------------- #
+def cmd_version(args):
+    print(f"vlakit {__version__}")
+    return 0
+
+
+def cmd_init(args):
+    """Scaffold an editable configs/ dir from the bundled templates."""
+    dest = os.path.abspath(args.dir or os.path.join(os.getcwd(), "configs"))
+    if os.path.exists(dest) and not args.force:
+        sys.exit(f"{dest} already exists — pass --force to overwrite")
+    with ExitStack() as stack:
+        src = _templates_configs(stack)
+        if os.path.exists(dest) and args.force:
+            shutil.rmtree(dest)
+        shutil.copytree(src, dest)
+    print(f"scaffolded configs -> {dest}")
+    print("next: edit boxes.yaml / datasets.yaml / baselines.yaml / runs/, then "
+          "copy secrets.example.env -> secrets.local.env and fill it.")
+    return 0
+
+
+def cmd_config(args):
+    """Resolve a run config (defaults merged under the run) and print it. Runs locally."""
+    with ExitStack() as stack:
+        scripts = _scripts_root(stack)
+        cfg = _config_dir(args)
+        # source the resolver and print — exactly what ops/launch.sh shows in dry-run,
+        # without needing a box or ssh.
+        snippet = ('source "$FT_ROOT/lib/config.sh"; '
+                   'load_run_config "$1" && print_run_config')
+        return _run(["bash", "-c", snippet, "_", args.run], _env(scripts, cfg))
+
+
+def cmd_remote(args):
+    """Pass through to ops/remote.sh <box> <subcmd> [args...]."""
+    with ExitStack() as stack:
+        scripts = _scripts_root(stack)
+        cfg = _config_dir(args)
+        return _run(["bash", os.path.join(scripts, "ops", "remote.sh"),
+                     args.box, args.subcmd, *args.extra], _env(scripts, cfg))
+
+
+def cmd_launch(args):
+    """Launch detached + auto-resume; the box is read from the run's config (auto)."""
+    with ExitStack() as stack:
+        scripts = _scripts_root(stack)
+        cfg = _config_dir(args)
+        return _run(["bash", os.path.join(scripts, "ops", "remote.sh"),
+                     "auto", "autoresume", args.run], _env(scripts, cfg))
+
+
+def _run_pyscript(args, rel, passthrough):
+    with ExitStack() as stack:
+        scripts = _scripts_root(stack)
+        return _run([sys.executable, os.path.join(scripts, *rel), *passthrough],
+                    _env(scripts))
+
+
+def cmd_stats(args):
+    """data/compute_stats.py — needs the [stats] extra (numpy + pyarrow)."""
+    return _run_pyscript(args, ("data", "compute_stats.py"), args.extra)
+
+
+def cmd_split(args):
+    """data/heldout_split.py — deterministic held-out episode ids (stdlib only)."""
+    return _run_pyscript(args, ("data", "heldout_split.py"), args.extra)
+
+
+def cmd_eval(args):
+    """eval/rollout.py — offline comparator / rollout (use --self-test to verify the harness)."""
+    return _run_pyscript(args, ("eval", "rollout.py"), args.extra)
+
+
+def cmd_doctor(args):
+    """Print what vlakit resolved, so you can see where scripts/configs are coming from."""
+    with ExitStack() as stack:
+        scripts = _scripts_root(stack)
+        print(f"vlakit         {__version__}")
+        print(f"python         {sys.version.split()[0]}")
+        print(f"scripts (FT_ROOT)   {scripts}")
+        cfg = _config_dir(args, required=False)
+        print(f"config dir          {cfg}  {'(exists)' if os.path.isdir(cfg) else '(MISSING — run `vla init`)'}")
+        for mod in ("yaml", "numpy", "pyarrow", "wandb"):
+            try:
+                __import__(mod)
+                print(f"  {mod:8} ok")
+            except ImportError:
+                print(f"  {mod:8} not installed")
+    return 0
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="vla", description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--config-dir", help="path to your configs/ (else $VLA_CONFIG_DIR, else ./configs)")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("version", help="print the vlakit version").set_defaults(fn=cmd_version)
+    sub.add_parser("doctor", help="show resolved scripts/config dirs + optional deps").set_defaults(fn=cmd_doctor)
+
+    sp = sub.add_parser("init", help="scaffold a configs/ dir from templates")
+    sp.add_argument("dir", nargs="?", help="target dir (default ./configs)")
+    sp.add_argument("--force", action="store_true", help="overwrite an existing dir")
+    sp.set_defaults(fn=cmd_init)
+
+    sp = sub.add_parser("config", help="resolve + print a run config (local, no box)")
+    sp.add_argument("run", help="run name (a file in configs/runs/)")
+    sp.set_defaults(fn=cmd_config)
+
+    sp = sub.add_parser("remote", help="run an ops subcommand on a box (deploy/monitor/gpus/...)")
+    sp.add_argument("box", help="box alias from boxes.yaml, or 'auto'")
+    sp.add_argument("subcmd", help="deploy|push-secrets|ensure-swap|launch|autoresume|monitor|kill|rescale|pull|gpus|exec|shell")
+    sp.set_defaults(fn=cmd_remote)
+
+    sub.add_parser("launch", help="launch a run detached + auto-resume (box from the run cfg)").add_argument("run", help="run name")
+    sub.choices["launch"].set_defaults(fn=cmd_launch)
+
+    sub.add_parser("stats", help="compute full dataset stats (needs [stats] extra)").set_defaults(fn=cmd_stats)
+    sub.add_parser("split", help="deterministic held-out episode split").set_defaults(fn=cmd_split)
+    sub.add_parser("eval", help="held-out comparator / rollout (try: vla eval --self-test)").set_defaults(fn=cmd_eval)
+
+    # parse_known_args so unknown flags (e.g. `eval --self-test`, `split --episodes N`) forward
+    # cleanly to the wrapped script — argparse.REMAINDER drops a *leading* option.
+    args, extra = p.parse_known_args(argv)
+    args.extra = extra
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

vlakit-0.1.0/src/vlakit/scripts/data/README.md

@@ -0,0 +1,45 @@
+# data/ — dataset conversion + stats
+
+## The v2.1 / v3.0 split (ui.md §1.4)
+| Stack | Format it reads |
+|---|---|
+| **openpi** | **v2.1** directly — no conversion, no extra stats step |
+| **lerobot** | **v3.0** + full stats |
+| **molmo**  | **v3.0** + full stats |
+
+Convert **in place** — do NOT make a second full copy (towel_300h is ~2.6 TB).
+
+## Why a custom stats step (E6) — the important part
+lerobot's `gen_episode_stats.py` only computes **mean/std/min/max**. But lerobot &
+molmo read, at launch:
+- **quantiles q01–q99** (every percentile), and
+- **per-image-key stats** (channel mean/std for each camera/observation image key).
+
+Missing either => **KeyError at launch**. So [`compute_stats.py`](compute_stats.py) computes the FULL
+set and validates it before you launch. Performance: read parquet **columns with
+pyarrow** (numpy buffers); the naive `.to_pylist()` path was ~100× too slow (E6).
+
+## Pipeline
+```bash
+# lerobot/molmo only (openpi skips this entirely):
+./convert_v21_to_v30.sh /path/to/dataset      # in place, then chains compute_stats.py
+# or stats alone:
+python compute_stats.py --dataset /path/to/dataset
+```
+
+## Files
+
+- **convert_v21_to_v30.sh** — convert a LeRobot dataset v2.1→v3.0 in place, then chain stats. [deep dive →](../docs/reference/data.md#convert_v21_to_v30sh)
+- **compute_stats.py** — compute the full stats set (quantiles q01–q99 + image stats) and validate before launch. [deep dive →](../docs/reference/data.md#compute_statspy)
+- **heldout_split.py** — pick a deterministic, strided held-out episode set for validation/eval (no native val split exists since E20). Used by [`../eval/rollout.py`](../eval/rollout.py) offline mode and any in-training val. [deep dive →](../docs/reference/data.md#heldout_splitpy)
+
+## Honesty: what's verified vs template
+- **Verified from ui.md:** the v2.1/v3.0 split, in-place conversion, the requirement
+  for quantiles + image stats, the pyarrow-not-`to_pylist` performance lesson, and
+  validating stats before launch.
+- **TEMPLATE / TODO (need the box's lerobot version):**
+  - [`convert_v21_to_v30.sh`](convert_v21_to_v30.sh) — the exact upstream converter entrypoint (`UPSTREAM_CONVERT`).
+  - [`compute_stats.py`](compute_stats.py) — exact stats file path/format, the low-dim column names, and
+    the image-key decode/sampling path (`compute_image_stats` returns the right
+    SHAPE but placeholder values; wire it to the real frame decode).
+  These are clearly marked `TODO` in the files.