v0.6.0 to v0.8.0

50 added, 90 removed. Audit A to A.

---

name: i4h-workflow-dataset-mimic

- version: "0.6.0"

- description: Expand an HDF5 recording by cloning trajectories with action/state noise. Use when asked to mimic, expand, or augment a dataset; not for recording new demos (use [[i4h-workflow-dataset-teleop]]).

+ description: Expand workflow HDF5 demonstrations with action jitter, optionally scoped to node segments. Use for synthetic variants; do not use to collect data, alter state directly, or generate new images.

license: Apache-2.0

metadata:

author: "Isaac for Healthcare Team <isaac-for-healthcare-support@nvidia.com>"

+ version: "0.8.0"

tags:

- isaac-for-healthcare

- i4h

- dataset

- - mimic

- augmentation

+ - hdf5

---

- # i4h Workflow — Mimic Dataset

+ # Mimic Workflow Demonstrations

## Purpose

- Expand an HDF5 recording by replicating trajectories with small action and state noise. Use when the user asks to mimic, expand, or augment a dataset without recording new episodes. If the same prompt also asks to visualize the dataset, finish mimic first, then compose [[i4h-workflow-dataset-convert]] and [[i4h-lerobot-viz]] on the mimic output.

+ Clone successful source episodes and perturb recorded actions.

- ## Base Code

+ ## Instructions

- 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:

+ 1. Run the checkout resolver and select the source HDF5.

+ 2. Inspect successful episodes and segments.

+ 3. Run mimic to generate the requested additional action-jitter variants.

+ 4. Compare exact counts and preserved contracts.

+ ## Resolve and inspect

```bash

- # Resolve the i4h-workflows base code (provides workflows/agentic/).

+ export I4H_WORKFLOWS_REPO_URL="${I4H_WORKFLOWS_REPO_URL:-https://github.com/isaac-for-healthcare/i4h-workflows}"

+ I4H_REPO_DIR_NAME="${I4H_WORKFLOWS_REPO_URL%/}"

+ I4H_REPO_DIR_NAME="${I4H_REPO_DIR_NAME##*/}"

+ I4H_REPO_DIR_NAME="${I4H_REPO_DIR_NAME##*:}"

+ I4H_REPO_DIR_NAME="${I4H_REPO_DIR_NAME%.git}"

+ [ -n "$I4H_REPO_DIR_NAME" ] || { echo "Cannot derive a checkout name from I4H_WORKFLOWS_REPO_URL" >&2; exit 2; }

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"

+ if [ ! -d "$ROOT/workflows/i4h_workflows" ]; then

+ ROOT="${I4H_WORKFLOWS:-$HOME/$I4H_REPO_DIR_NAME}"

+ [ -d "$ROOT/workflows/i4h_workflows" ] || git clone "$I4H_WORKFLOWS_REPO_URL" "$ROOT"

- export I4H_WORKFLOWS="$ROOT"; cd "$ROOT"

+ export I4H_WORKFLOWS="$ROOT"

+ cd "$ROOT"

+ HDF5_PATH=/absolute/path/to/source.hdf5

+ uv run --project tools/dataset i4h-dataset inspect "$HDF5_PATH" --segments

```

- ## Basics

- - **Env config (source of truth):** `workflows/agentic/config/environments/<env>.yaml` defines the `<env>` robot and task the mimicked trajectories replay against.

- - Mimic perturbs action/state, not visuals.

- - Default `--include-source` keeps the original demos in the output.

- - In a chained workflow after teleop/validate, use the HDF5 produced by that chain. Do not silently fall back to an older same-env recording if the latest/current recording is empty or failed; stop and report that source demos are missing.

- - Count HDF5 episodes with the workflow venv, not system Python (`h5py` may not be installed globally).

- ## Run

+ Treat the resolver above as part of the skill contract: a hosted copy may run outside the base repository, so never assume the current checkout contains `workflows/i4h_workflows`. `I4H_WORKFLOWS_REPO_URL` selects the clone source. When `I4H_WORKFLOWS` is unset, derive the fallback directory from that URL; set `I4H_WORKFLOWS` only to reuse or choose a specific destination. Never replace an existing checkout.

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

+ Use the explicit/current-chain recording. Require at least one successful source episode. If the user asks for node-scoped jitter, require that node in segment metadata.

- ### Step 1 — setup and resolve input HDF5

+ ## Expand

```bash

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

- ENV_ID=scissor_pick_and_place

- RUNS_ROOT="${REPO_ROOT}/workflows/agentic/runs"

- # Point IN at a real recording to expand (absolute path). Recordings come from teleop or

- # validate (which writes data/verify.hdf5 under each runs/eval_* dir). List candidates newest-first:

- # find "${RUNS_ROOT}" -name '*.hdf5' -printf '%TY-%Tm-%Td %TH:%TM %p\n' | sort -r | head

- IN="${IN:-}"

- if [ ! -f "${IN}" ]; then

- echo "mimic: set IN to an existing .hdf5 (got '${IN:-<unset>}'). Candidates:" >&2

- find "${RUNS_ROOT}" -name '*.hdf5' -printf '%TY-%Tm-%Td %TH:%TM %p\n' 2>/dev/null | sort -r | head

- exit 1

- fi

- # Verify the selected input is a real recording before mimic. A tiny HDF5 or

- # `0/N episodes succeeded` teleop artifact is not usable source data.

- "${REPO_ROOT}/workflows/agentic/mimic/.venv/bin/python" - "${IN}" <<'PY'

- import h5py

- import sys

- path = sys.argv[1]

- with h5py.File(path, "r") as f:

- count = len(f["data"]) if "data" in f else 0

- print(f"source episodes: {count}")

- if count <= 0:

- raise SystemExit("mimic: input HDF5 has no episodes; record successful demos first")

- PY

- RUN_DIR="${RUNS_ROOT}/mimic_${ENV_ID}_$(date +%Y%m%d_%H%M%S)"

- mkdir -p "${RUN_DIR}/data" "${RUN_DIR}/logs"

- ln -sfn "${RUN_DIR}" "${RUNS_ROOT}/.latest"

- OUT="${RUN_DIR}/data/demo_mimic.hdf5"

+ RUN_DIR="$(pwd)/runs/<workflow>/$(date +%Y%m%d_%H%M%S)"

+ mkdir -p "$RUN_DIR"

+ uv run --project tools/mimic i4h-mimic \

+ "$HDF5_PATH" "$RUN_DIR/expanded.hdf5" \

+ --episodes <additional-count> \

+ --noise 0.01 \

+ --seed <seed> \

+ --include-source \

+ --successful-only

```

- When resolving "my dataset" from prior prompts, inspect candidates newest-first and prefer the current chain's latest successful teleop/validate HDF5. If the newest HDF5 for the target env has 0 episodes, do not skip back to an older run unless the user explicitly asks to reuse that older dataset.

+ `--episodes` is the number of generated variants, not the final total. Add `--node <node-id>` only when requested. Preserve the default deterministic seed unless the user supplies another.

- ### Step 2 — mimic expand

+ ## Verify and compose

```bash

- "${REPO_ROOT}/workflows/agentic/mimic/run.sh" --env "${ENV_ID}" \

- --input "${IN}" \

- --output "${OUT}" \

- --episodes 3 \

- --noise-std 0.01 \

- --include-source \

- --overwrite \

- 2>&1 | tee "${RUN_DIR}/logs/mimic.log"

+ uv run --project tools/dataset i4h-dataset inspect "$RUN_DIR/expanded.hdf5" --segments

```

- ## Verify

- ```bash

- uv --directory "${REPO_ROOT}/workflows/agentic/mimic" run python -c \

- "import h5py; print('episodes:', len(h5py.File('${OUT}','r')['data']))"

- ```

+ Confirm source count, generated count, dimensions, success flags, and segment preservation. Reject zero generated episodes.

- Confirm the output episode count equals the source demos plus `--episodes`.

- Also confirm the input episode count was greater than zero; mimic output from an empty source is invalid.

+ If the same prompt requests visualization, continue with `i4h-workflow-dataset-convert`, then `i4h-lerobot-viz`; raw HDF5 is not a LeRobot visualizer input.

- If the prompt includes visualization (for example, "Mimic 3 more episodes and visualize my dataset"), continue after this verify step:

+ ## Troubleshooting

- 1. Load [[i4h-workflow-dataset-convert]] and set `HDF5_PATH="${OUT}"` so the augmented HDF5 is converted to LeRobot with `--video-codec h264`.

- 2. Load [[i4h-lerobot-viz]] and set `DATASET_DIR` to the converted dataset directory (`${HF_LEROBOT_HOME}/local/${ENV_ID}` by default).

- 3. Report both the augmented HDF5 and the visualizer URL.

+ On failure, inspect the first episode shape or segment error. If a requested node is absent, report available node ids.

## Prerequisites

- - Workflow set up via [[i4h-workflow-setup]] (the `.venv` must exist).

- - An existing input HDF5 recording (`--input`).

- - The env id that produced the recording.

+ Require a readable HDF5 file with at least one successful episode and valid segments for node-scoped jitter.

## Limitations

- - Perturbs action/state only, not visuals.

- - Augments an existing recording rather than recording new episodes.

- - Output state/action dimensions must match the source.

+ The current tool does not independently add state noise, rerun physics, or synthesize camera frames.

- ## Troubleshooting

+ ## Examples

- - **Error:** `.venv` not found / mimic fails to launch - Cause: workflow not set up. Fix: run [[i4h-workflow-setup]] first.

- - **Error:** input recording not found - Cause: wrong or missing `--input` HDF5 path. Fix: point to the existing recording file.

- - **Error:** input HDF5 has no episodes - Cause: teleop was launched but no successful episodes were saved. Fix: record successful source demos first; do not substitute an older run without explicit user direction.

- - **Error:** output already exists / write refused - Cause: `--output` path is occupied. Fix: choose a new path or pass `--overwrite`.

- - **Error:** state/action dimension mismatch on inspect - Cause: `--env` differs from the env that produced the input. Fix: use the same env id as the source recording.

+ - `Mimic 3 more episodes and visualize my dataset.` → generate three variants, convert the expanded HDF5, then launch LeRobot visualization.

- ## Final Response

+ ## Completion gate

- Report input path, output path, generated episode count, noise std, whether source demos were included, and the visualizer URL if visualization was requested.

+ Report input/output paths, source and generated counts, final total, action-noise value, seed, optional node, limitations, and conversion/visualizer result when requested.