i4h-lerobot-viz

name	i4h-lerobot-viz
version	0.6.0
description	Serve the LeRobot HTML visualizer for a converted dataset in a browser. Use when asked to visualize, inspect, or open a LeRobot dataset; not for converting HDF5 (use [[i4h-workflow-dataset-convert]]).
license	Apache-2.0
metadata	{"author":"Isaac for Healthcare Team <[e-mail]>","tags":["isaac-for-healthcare","i4h","lerobot","visualization","dataset"]}

i4h Workflow — LeRobot Viz

Purpose

Serve the LeRobot HTML visualizer for a converted dataset in a browser. Use when the user asks to visualize, inspect, or open a LeRobot dataset.

Base Code

These steps drive the i4h-workflows base code (the workflows/agentic/ tree). To reuse an existing checkout, set I4H_WORKFLOWS to its path (no clone happens). Otherwise this resolves the current repo, or clones to ~/i4h-workflows — pick that default without prompting. Run every command below from the resolved root:

# Resolve the i4h-workflows base code (provides workflows/agentic/).
ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"
if [ ! -d "$ROOT/workflows/agentic" ]; then
  ROOT="${I4H_WORKFLOWS:-$HOME/i4h-workflows}"
  [ -d "$ROOT/workflows/agentic" ] || git clone https://github.com/isaac-for-healthcare/i4h-workflows "$ROOT"
fi
export I4H_WORKFLOWS="$ROOT"; cd "$ROOT"

Basics

• Input is a converted LeRobot dataset directory containing meta/info.json.
• Use for visual checks after conversion or video augmentation.

Run

Run the steps below in order. Each step is a separate bash call; variables persist in the local agent's tmux session.

Step 1 — setup and resolve dataset

REPO_ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"; [ -d "$REPO_ROOT/workflows/agentic" ] || REPO_ROOT="$HOME/i4h-workflows"
RUNS_ROOT="${REPO_ROOT}/workflows/agentic/runs"

# Point DATASET_DIR at a converted LeRobot dataset dir (absolute; must contain meta/info.json),
# produced by [[i4h-workflow-dataset-convert]]. List candidates:
#   find "${RUNS_ROOT}" "${HF_LEROBOT_HOME:-$HOME/.cache/huggingface/lerobot}" -name info.json -path '*/meta/*' -printf '%h\n' | sed 's#/meta$##' | sort -u
DATASET_DIR="${DATASET_DIR:-}"
if [ ! -f "${DATASET_DIR%/}/meta/info.json" ]; then
  echo "viz: set DATASET_DIR to a LeRobot dataset dir with meta/info.json (got '${DATASET_DIR:-<unset>}'). Candidates:" >&2
  find "${RUNS_ROOT}" "${HF_LEROBOT_HOME:-$HOME/.cache/huggingface/lerobot}" -name info.json -path '*/meta/*' -printf '%h\n' 2>/dev/null | sed 's#/meta$##' | sort -u | head
  exit 1
fi

RUN_DIR="${RUNS_ROOT}/viz_$(date +%Y%m%d_%H%M%S)"
mkdir -p "${RUN_DIR}/logs" "${RUN_DIR}/viz_state"
ln -sfn "${RUN_DIR}" "/.latest"

Step 2 — serve visualizer

"${REPO_ROOT}/workflows/agentic/dataset/viz.sh" "${DATASET_DIR}" \
  --state-dir "${RUN_DIR}/viz_state" \
  2>&1 | tee "${RUN_DIR}/logs/viz.log"

Notes

• The dataset path must be absolute. viz.sh treats relative paths as Hugging Face repo ids and looks them up under ~/.cache/huggingface/lerobot/<path>.
• Override --state-dir only when the caller provides one.

Verify

• The visualizer prints a local URL (e.g. http://127.0.0.1:9090/).
• Videos and joint timelines load in the browser.

Prerequisites

• Workflow set up via [[i4h-workflow-setup]] (the .venv must exist).
• A converted LeRobot dataset directory containing meta/info.json (see [[i4h-workflow-dataset-convert]]).
• An absolute path to that dataset directory.

Limitations

• Input must be a converted LeRobot dataset directory with meta/info.json; intended for visual checks after conversion or video augmentation.
• The dataset path must be absolute; viz.sh treats relative paths as Hugging Face repo ids and looks them up under ~/.cache/huggingface/lerobot/<path>.
• Override --state-dir only when the caller provides one.

Troubleshooting

• Error: .venv not found / module import fails - Cause: workflow not set up. Fix: run [[i4h-workflow-setup]] first.
• Error: dataset resolved as a Hugging Face repo id / not found - Cause: a relative dataset path was passed. Fix: pass the absolute path to the dataset directory.
• Error: no meta/info.json - Cause: directory is not a converted LeRobot dataset. Fix: convert first with [[i4h-workflow-dataset-convert]].
• Error: address/port already in use - Cause: a visualizer is already serving that local URL. Fix: stop the existing process before starting a new one.

Final Response

Report dataset path, visualizer URL, stop command, startup failures.