oopsie-data-tools 0.2.0__py3-none-any.whl

oopsie_data_tools/init_wizard.py

@@ -0,0 +1,329 @@
+"""Interactive setup wizard behind ``oopsie-data init``.
+
+Writes ``contributor_config.yaml`` — the lab id and HuggingFace token every contributor
+needs before uploading — into the config directory chosen in :func:`choose_target_dir`,
+which follows the lookup order documented in :mod:`oopsie_data_tools.utils.paths`.
+
+Robot profiles are not created here: they are hand-written YAML, documented in
+``configs/robot_profiles/template.yaml`` and on the docs site.
+
+Every question can be answered ahead of time with a flag, so a fully-flagged invocation
+runs unattended (see ``oopsie-data init --help``).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import stat
+import sys
+from pathlib import Path
+from typing import Any, Callable, Sequence
+
+import yaml
+
+from oopsie_data_tools.utils import paths
+from oopsie_data_tools.utils.contributor_config import read_contributor_config
+
+logger = logging.getLogger(__name__)
+
+CONTRIBUTOR_CONFIG_NAME = "contributor_config.yaml"
+PLACEHOLDER_LAB_ID = "your_lab_id"
+REGISTRATION_URL = "https://forms.gle/9arwZHAvRjvbozoT7"
+
+
+class WizardAbort(Exception):
+    """Raised when the wizard cannot continue (no TTY, or the user gave up on a question)."""
+
+
+# ── prompt helpers ────────────────────────────────────────────────────────────
+#
+# Same contract as cli._prompt_annotator_name: never block on a non-interactive stdin,
+# re-ask a bounded number of times, strip every answer.
+
+_MAX_ATTEMPTS = 3
+
+
+def _require_tty(what: str) -> None:
+    if not sys.stdin.isatty():
+        raise WizardAbort(
+            f"Cannot ask for {what}: stdin is not a terminal. "
+            "Pass the value as a command line flag to run non-interactively."
+        )
+
+
+def _with_default(prompt: str, default: str | None) -> str:
+    return f"{prompt} [{default}]: " if default else f"{prompt}: "
+
+
+def ask(
+    prompt: str,
+    default: str | None = None,
+    validate: Callable[[str], str | None] | None = None,
+) -> str:
+    """Ask for a string. ``validate`` returns an error message, or None if the value is fine."""
+    _require_tty(prompt)
+    for _ in range(_MAX_ATTEMPTS):
+        answer = input(_with_default(prompt, default)).strip()
+        if not answer and default is not None:
+            answer = default
+        if not answer:
+            print("  Please enter a value.")
+            continue
+        error = validate(answer) if validate else None
+        if error:
+            print(f"  {error}")
+            continue
+        return answer
+    raise WizardAbort(f"No valid answer for: {prompt}")
+
+
+def ask_optional(prompt: str, default: str | None = None) -> str:
+    """Ask for a string that may be left empty."""
+    _require_tty(prompt)
+    answer = input(_with_default(prompt, default)).strip()
+    if not answer and default is not None:
+        return default
+    return answer
+
+
+def ask_bool(prompt: str, default: bool = False) -> bool:
+    _require_tty(prompt)
+    hint = "[Y/n]" if default else "[y/N]"
+    for _ in range(_MAX_ATTEMPTS):
+        answer = input(f"{prompt} {hint}: ").strip().lower()
+        if not answer:
+            return default
+        if answer in ("y", "yes"):
+            return True
+        if answer in ("n", "no"):
+            return False
+        print("  Please answer y or n.")
+    raise WizardAbort(f"No valid answer for: {prompt}")
+
+
+def ask_choice(prompt: str, options: Sequence[str], default: str | None = None) -> str:
+    _require_tty(prompt)
+    print(f"\n{prompt}")
+    for index, option in enumerate(options, start=1):
+        marker = "  <- default" if option == default else ""
+        print(f"  {index}) {option}{marker}")
+
+    def _validate(value: str) -> str | None:
+        if value in options:
+            return None
+        if value.isdigit() and 1 <= int(value) <= len(options):
+            return None
+        return f"Please enter a number between 1 and {len(options)}."
+
+    answer = ask("Choice", default, _validate)
+    return options[int(answer) - 1] if answer.isdigit() else answer
+
+
+# ── config directory ──────────────────────────────────────────────────────────
+
+
+def choose_target_dir() -> Path:
+    """Pick the directory to write the config into.
+
+    ``$OOPSIE_CONFIG_DIR`` (set directly or via ``--config-dir``) wins outright. Otherwise
+    the per-user config directory is the default everywhere; inside a checkout we still
+    offer the checkout's ``configs/``, but never pick it for you.
+
+    The default deliberately points away from the checkout. The file holds a HuggingFace
+    token, and a token inside a git working tree is one ``git add -A`` away from being
+    published — which is exactly how it used to be committed.
+    """
+    env_dir = paths.env_config_dir()
+    if env_dir is not None:
+        logger.info("Using config directory from $%s: %s", paths.ENV_CONFIG_DIR, env_dir)
+        return env_dir
+
+    repo_dir = paths.repo_config_dir()
+    user_dir = paths.user_config_dir()
+    if repo_dir is None or not sys.stdin.isatty():
+        logger.info("Using config directory: %s", user_dir)
+        return user_dir
+
+    user_option = f"{user_dir}  (your user config directory)"
+    repo_option = f"{repo_dir}  (this checkout — holds a token inside a git working tree)"
+    choice = ask_choice(
+        "Where should your config be saved? Both are found automatically.",
+        [user_option, repo_option],
+        default=user_option,
+    )
+    return repo_dir if choice.startswith(str(repo_dir)) else user_dir
+
+
+def _shell_rc_path() -> Path:
+    shell = os.path.basename(os.environ.get("SHELL", "")).strip()
+    name = ".zshrc" if shell == "zsh" else ".bashrc"
+    return Path.home() / name
+
+
+def advise_persisting_config_dir(target_dir: Path, from_flag: bool = False) -> None:
+    """Tell the user how to make ``target_dir`` stick, if it would not be found next run.
+
+    ``from_flag`` marks a location that came from ``--config-dir``: the CLI exports that into
+    the environment for the current process only, so it must not count as persisted.
+    """
+    if target_dir in (paths.user_config_dir(), paths.repo_config_dir()):
+        return  # found by the normal lookup order
+    if paths.env_config_dir() == target_dir and not from_flag:
+        return  # already exported in the user's environment
+
+    export_line = f'export {paths.ENV_CONFIG_DIR}="{target_dir}"'
+    rc_path = _shell_rc_path()
+    logger.warning(
+        "\nOne more step: %s is not a location oopsie-data looks in by default, so a new "
+        "terminal will not find it.\nAdd this line to %s to make it stick:\n\n    %s\n",
+        target_dir, rc_path, export_line,
+    )
+    if sys.stdin.isatty() and ask_bool(f"Append that line to {rc_path} now?", default=False):
+        with rc_path.open("a", encoding="utf-8") as handle:
+            handle.write(f"\n# Added by oopsie-data init\n{export_line}\n")
+        logger.info("Done. Run 'source %s' or open a new terminal.", rc_path)
+
+
+# ── contributor config ────────────────────────────────────────────────────────
+
+
+def _read_existing_yaml(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _mask(token: str) -> str:
+    return f"{token[:5]}…{token[-4:]}" if len(token) > 12 else "…"
+
+
+def _validate_lab_id(value: str) -> str | None:
+    if value == PLACEHOLDER_LAB_ID:
+        return f"'{PLACEHOLDER_LAB_ID}' is the placeholder value — use the lab id you were given."
+    return None
+
+
+def _verify_token(token: str) -> None:
+    """Confirm the token works, without ``login()`` writing it to the HF cache."""
+    try:
+        from huggingface_hub import whoami
+
+        info = whoami(token=token)
+        logger.info("  Token verified — logged in as %s", info["name"])
+    except Exception as e:
+        logger.warning(
+            "  Could not verify the token (%s). Saving it anyway; "
+            "'oopsie-data upload' will tell you if it is wrong.", e
+        )
+
+
+def step_credentials(
+    target_dir: Path,
+    lab_id: str | None = None,
+    hf_token: str | None = None,
+    verify_token: bool = True,
+    force: bool = False,
+) -> Path | None:
+    """Write ``contributor_config.yaml``. Returns the path, or None if nothing was written."""
+    path = target_dir / CONTRIBUTOR_CONFIG_NAME
+    existing = _read_existing_yaml(path)
+    existing_lab_id = str(existing.get("lab_id") or "").strip()
+    existing_token = str(existing.get("huggingface_token") or "").strip()
+
+    logger.info("\n── Contributor config ─────────────────────────────────")
+    logger.info("Writing to %s", path)
+    if path.is_file() and not force:
+        if existing_lab_id:
+            logger.info("This file already has lab_id '%s'.", existing_lab_id)
+        if not sys.stdin.isatty():
+            logger.error(
+                "%s already exists. Re-run with --force to overwrite it non-interactively.", path
+            )
+            return None
+        if not ask_bool("Update it?", default=True):
+            logger.info("Keeping the existing contributor config.")
+            return path
+
+    if lab_id is None:
+        logger.info(
+            "Your lab id and HuggingFace token come from the registration form: %s", REGISTRATION_URL
+        )
+        logger.info("Use the exact lab id you were given — capitalization matters.")
+        lab_id = ask("Lab id", existing_lab_id or None, _validate_lab_id)
+    else:
+        error = _validate_lab_id(lab_id)
+        if error:
+            raise WizardAbort(error)
+
+    if hf_token is None:
+        hf_token = ask_optional(
+            "HuggingFace token (leave blank to set $HF_TOKEN instead)",
+            _mask(existing_token) if existing_token else None,
+        )
+        if existing_token and hf_token == _mask(existing_token):
+            hf_token = existing_token  # user accepted the masked default: keep the real value
+
+    if hf_token and verify_token:
+        _verify_token(hf_token)
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        yaml.safe_dump({"lab_id": lab_id, "huggingface_token": hf_token}, sort_keys=False),
+        encoding="utf-8",
+    )
+    path.chmod(stat.S_IRUSR | stat.S_IWUSR)  # contains a credential
+
+    # Prove the file round-trips through the reader the rest of the toolkit uses.
+    saved_lab_id, _ = read_contributor_config(path)
+    logger.info("Saved. Episodes will be uploaded to OopsieData-Submissions/%s", saved_lab_id)
+    if not hf_token:
+        logger.info("No token saved — set $HF_TOKEN in your environment before uploading.")
+    return path
+
+
+# ── entry point ───────────────────────────────────────────────────────────────
+
+
+def run_init(
+    config_dir_from_flag: bool = False,
+    lab_id: str | None = None,
+    hf_token: str | None = None,
+    verify_token: bool = True,
+    force: bool = False,
+) -> int:
+    """Run the wizard. Returns a shell-style exit code."""
+    try:
+        target_dir = choose_target_dir()
+        written = step_credentials(
+            target_dir,
+            lab_id=lab_id,
+            hf_token=hf_token,
+            verify_token=verify_token,
+            force=force,
+        )
+        if written is None:
+            return 1  # refused to touch an existing config; the reason is already logged
+        advise_persisting_config_dir(target_dir, from_flag=config_dir_from_flag)
+
+        # Profiles deliberately do not live next to the credentials: they belong with the
+        # robot code that loads them (see oopsie_data_tools.utils.paths).
+        logger.info("\nSetup complete. Your credentials are saved in %s", target_dir)
+        logger.info("Run 'oopsie-data show-config' at any time to see what is in use.")
+        logger.info(
+            "Next: write a robot profile and keep it next to your robot code, e.g. %s.\n"
+            "Copy one of the examples or the commented template from the repo's "
+            "configs/robot_profiles/, then load it with load_robot_profile(<path>).",
+            paths.write_profiles_dir(),
+        )
+        return 0
+    except WizardAbort as e:
+        logger.error("%s", e)
+        return 1
+    except (KeyboardInterrupt, EOFError):
+        logger.info("\nAborted — nothing further was written.")
+        return 130

oopsie_data_tools/skill/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: oopsie-data
+description: Use when working with Oopsie Data robotic manipulation failure datasets — recording rollouts, annotating episodes, validating the HDF5 format, or uploading a submission with the oopsie-data CLI.
+---
+
+# Oopsie Data
+
+Oopsie Data is a community dataset of **robotic manipulation failures**. Contributors record
+rollouts, annotate what went wrong, and upload them to a shared HuggingFace repo. The
+`oopsie-data` CLI is the single entry point for all of it — there are no side scripts.
+
+Run `oopsie-data <command> --help` before constructing an invocation rather than guessing at
+flags.
+
+## The workflow
+
+Once per contributor, then once per recording session:
+
+```bash
+oopsie-data init                              # lab id + HuggingFace token (one time)
+oopsie-data new-profile                       # robot profile skeleton, then fill it in by hand
+#           ... record episodes by calling EpisodeRecorder from the robot control loop
+oopsie-data annotate --samples-dir ./samples  # label episodes in a browser UI
+oopsie-data validate --path ./samples         # check against oopsiedata_format_v1
+oopsie-data upload   --path ./samples         # validates again, then publishes
+```
+
+Recording is the step that produces the episodes everything after it consumes; it is code the
+user adds to their own control loop, not a CLI command. See `reference/setup.md`.
+
+Some users prefer to convert pre-recorded data instead of recording through `EpisodeRecorder`.
+That path writes the HDF5 directly rather than going through the recorder, so it bypasses every
+recording-time check — see `reference/conversion.md`.
+
+Supporting commands: `show-config` (which config files are in effect), `submissions` (what the
+lab has already uploaded), `inspect <file.h5>` (dump one episode's structure — a debugging aid
+that works even on files `validate` rejects; the path is positional, there is no `--path`),
+`restructure` (split a directory HuggingFace would reject), `install-skill` (copy this skill
+into a Claude configuration).
+
+Inside a git checkout that was set up with `uv sync`, prefix every command with `uv run`. A
+pip- or uv-installed package puts `oopsie-data` on `PATH` directly.
+
+## Rules
+
+**Never invent identity or annotation content.** `lab_id` comes from the registration form,
+`operator_name` and `annotator_name` are the human's, and an episode's `outcome` and
+`episode_description` record what actually happened in a rollout. If one is missing, ask. Do
+not fill in a plausible value.
+
+**Never hand-write `contributor_config.yaml`.** Run `oopsie-data init`. It rejects the
+`your_lab_id` placeholder, writes the file mode 0600, and keeps the token out of the checkout
+by defaulting to the per-user config directory. Writing the YAML yourself loses all three.
+
+**Uploads are public and effectively irreversible.** `oopsie-data upload` publishes to
+`OopsieData-Submissions/<lab_id>` on HuggingFace. Confirm with the user before running it, even
+if they asked for the whole pipeline in one go. `--skip-upload` runs every check and publishes
+nothing; use it as the dry run.
+
+**Never reach for `--skip-validate`.** Validation is the only thing standing between a
+malformed episode and the shared dataset. If validation fails, ask the user how to fix the
+data. Do not assume you know better than the validator or the user.
+
+**A robot profile that has not been filled in will not load, by design.** `new-profile` writes
+a skeleton whose required fields are blank so a half-edited profile cannot stamp placeholder
+metadata into recorded episodes. If loading one raises, fill in the fields; do not work around
+the loader.
+
+**Do not change code under `oopsie_data_tools/` to make a check pass.** Configs, robot profiles
+and the user's own robot script are yours to edit; the toolkit is not, without the user's
+explicit permission. A failing validator is a finding to report, not an obstacle to remove.
+
+**Credentials and robot profiles are different things** with separate lookup chains.
+`contributor_config.yaml` belongs to the person, robot profiles belong next to the robot code.
+`oopsie-data show-config` prints both chains and marks what is actually in use — start any
+config confusion there, and see `reference/setup.md` for the resolution order.
+
+## Reference files
+
+Read the one you need; do not read all five.
+
+- `reference/setup.md` — installing, where configs live, `init`, choosing an annotation
+  workflow, and wiring `EpisodeRecorder` into a robot control loop. The onboarding path.
+- `reference/robot-profile.md` — every profile field, which are required, the legal values,
+  and the questions to ask the user when filling one in.
+- `reference/format.md` — the `oopsiedata_format_v1` HDF5 layout and every rule the validator
+  enforces. Read before theorizing about why an episode was rejected.
+- `reference/conversion.md` — the same schema from the writing side, for converting an existing
+  dataset into `oopsiedata_format_v1` instead of recording it.
+- `reference/troubleshooting.md` — common errors, and the mistakes that pass validation
+  silently and must be checked by a human.
+
+## Reference
+
+- Documentation: <https://oopsie-data.com>
+- Toolkit source: <https://github.com/oopsie-data/oopsie-data-tools>
+- `oopsie-data --help` lists every command; `oopsie-data <command> --help` documents its flags
+  and shows worked examples.

oopsie_data_tools/skill/reference/conversion.md

@@ -0,0 +1,257 @@
+# oopsiedata_format_v1 — Full Schema Reference
+
+Use this skill whenever writing or debugging a converter that produces Oopsie HDF5 episode files. It describes the canonical `oopsiedata_format_v1` schema as enforced by `oopsie_data_tools`.
+
+`reference/format.md` is the same schema from the reading side; this page is the writing side. Where they disagree, the validator source wins — check it rather than guessing.
+
+You follow these steps:
+
+1. Create a new robot profile with `oopsie-data new-profile`, which writes into `./robot_profiles/` by default. Leave it where the command put it — profiles are looked up at `$OOPSIE_ROBOT_PROFILES_DIR`, then `./robot_profiles` or `./configs/robot_profiles`, so a bare `./configs/` is not found. Double check with the user that this robot profile is correct and no unverified information has been entered.
+2. Create the conversion script. Follow DRY and make sure to reuse utilities from `oopsie_data_tools.utils.conversion_utils`. Make sure to read all relevant information before attempting to write the conversion script.
+3. Wait for the user to run the conversion script with the full correct input path.
+
+## Validation entry points (`oopsie_data_tools`)
+
+```
+oopsie_data_tools/utils/validation/episode_loader.py    # HDF5 → EpisodeData
+oopsie_data_tools/utils/validation/episode_validator.py # semantic checks
+oopsie_data_tools/utils/validation/validation_utils.py  # public API
+oopsie_data_tools/utils/robot_profile/robot_profile.py  # RobotProfile
+```
+
+Run validation:
+```bash
+oopsie-data validate --path /path/to/directory
+oopsie-data inspect  /path/to/episode.h5    # structure dump, works on files validate rejects
+```
+
+---
+
+## HDF5 File Structure
+
+### Root attributes (all required)
+
+| Attribute | Type | Notes |
+|---|---|---|
+| `schema` | str | Must be `"oopsiedata_format_v1"` |
+| `episode_id` | str | Non-empty unique identifier |
+| `language_instruction` | str | Non-empty task description |
+| `lab_id` | str | Non-empty; not `"your_lab_id"` |
+| `operator_name` | str | Non-empty |
+| `robot_profile` | str | JSON-serialized `RobotProfile` (use `robot_profile_to_json`) |
+
+### `/observations/` group
+
+**`/observations/video_paths/`** — one string dataset per camera:
+- Key = camera name (must match `profile.camera_names`)
+- Value = relative path to MP4 from the HDF5 file's directory
+
+**`/observations/robot_states/`** — one dataset per robot state key:
+- Keys must equal `profile.robot_state_keys` exactly — every declared key present, and nothing
+  undeclared (an extra key is rejected, not ignored)
+- Shape: `(T, D)` float64
+- `joint_position`: `(T, n_joints)` — names from `robot_state_joint_names`, and the count must match
+- `gripper_position`: `(T, 1)` or `(T, n_fingers)` — DOF is not checked
+- `cartesian_position`: **`(T, 7)`**, or `(T, 14)` when `is_biarm` — `[x, y, z, qx, qy, qz, qw]`
+  per arm, scalar-last. Not euler: convert before writing, or the episode is rejected.
+
+`gripper_position` is the only unconditionally required state key. `joint_position` is required
+only when `action_space` holds `joint_position`/`joint_velocity`, and `cartesian_position` only
+when it holds `cartesian_position`/`cartesian_velocity` — the state must observe the space the
+action controls. Mixing joint and Cartesian actions requires both.
+
+### `/actions/` group
+
+- Keys in `profile.action_space`: stored as `(T, D)` float64 arrays (non-empty)
+- All other canonical action keys: stored as `h5py.Empty(dtype=np.float64)`
+
+Canonical action keys (write Empty for any not in action_space):
+```
+cartesian_position, cartesian_velocity,
+joint_position, joint_velocity,
+base_position, base_velocity,
+gripper_velocity, gripper_position, gripper_binary
+```
+
+### `/episode_annotations/` group (required by both `validate` and `upload`)
+
+Structure: `episode_annotations/{annotator_name}/` — a group with HDF5 attributes:
+
+| Attr | Type | Notes |
+|---|---|---|
+| `success` | float | Required; must be in [0.0, 1.0] |
+| `episode_description` | str | Optional free text |
+| `taxonomy` | str | JSON: `{"outcome": "...", "side_effect_category": [...], "severity": "..."}` |
+
+`outcome` is one of four slugs — `success`, `success_suboptimal`, `success_side_effect`,
+`failure` — and is the only taxonomy field that matters to validation. It must agree in sign
+with `success` (`failure` iff `success < 0.5`); all three `success_*` outcomes write
+`success = 1.0`, so a consumer that only reads the float sees them alike.
+
+`side_effect_category` and `severity` are stored as stable slugs, not prose:
+
+| Field | Allowed values |
+|---|---|
+| `side_effect_category` | `reaching`, `grasp`, `manipulation`, `sequencing_semantic`, `collision`, `hardware`, `not_attempted`, `other` |
+| `severity` | `low`, `medium`, `catastrophic` |
+
+Every field except `outcome` is optional — a partial annotation is valid, and so is a failure
+with no taxonomy at all.
+
+Files written by an older release carry `schema = oopsie_failure_taxonomy_v1`,
+`failure_description` instead of `episode_description`, prose values instead of slugs, and no
+`outcome`. Readers upcast those on the fly and never rewrite them, so both versions can sit in
+one dataset. `oopsie_data_tools/utils/migrate_taxonomy_v2.py` converts them in place if you
+want them normalized.
+
+A converter that emits no `episode_annotations` produces structurally valid files that still fail `oopsie-data validate` with `Annotations dict is empty, must be provided for upload`. Either carry the source dataset's labels across, or plan to run `oopsie-data annotate` afterwards.
+
+---
+
+## RobotProfile fields
+
+Defined in `oopsie_data_tools/utils/robot_profile/robot_profile.py`. Serialized as JSON into `f.attrs["robot_profile"]`.
+
+**Required fields** — these nine, and no others, are what `REQUIRED_KEYS` enforces:
+
+| Field | Type | Example |
+|---|---|---|
+| `policy_name` | str | `"pi0_droid"` |
+| `robot_name` | str | `"franka_research_3"` |
+| `gripper_name` | str | `"robotiq_2f_85"` |
+| `is_biarm` | bool | `false` |
+| `uses_mobile_base` | bool | `false` |
+| `control_freq` | int | `10` |
+| `camera_names` | list[str] | `["left", "right", "wrist"]` |
+| `robot_state_keys` | list[str] | Must include `"gripper_position"`, plus whatever `action_space` implies (see above) |
+| `action_space` | list[str] | ≥1 arm key + ≥1 gripper key (see below) |
+
+**`action_space` validity rules** (`is_valid_action_space`):
+- **at least one** arm key from: `{joint_position, joint_velocity, cartesian_position, cartesian_velocity}`
+- **at least one** gripper key from: `{gripper_position, gripper_velocity, gripper_binary}`
+- **at most one** base key from: `{base_velocity, base_position}`
+- No other keys allowed
+
+Declaring two arm keys or two gripper keys is legal — but every declared key must then be written as a real (non-Empty) array. `uses_mobile_base: true` requires a base key; the converse is not checked.
+
+**Optional fields:**
+
+| Field | Notes |
+|---|---|
+| `robot_state_joint_names` | Required if `joint_position` is in `robot_state_keys` (enforced at profile load). One entry per joint DOF; the count is checked against the recorded array |
+| `action_joint_names` | Required if `action_space` includes `joint_position` or `joint_velocity` |
+| `robot_state_orientation_representation` | Declares how `cartesian_position` state encodes orientation. Options: `"quat"`, `"matrix"`, `"rot6d"`, `"rotvec"`, `"euler_<order>"` where order ∈ `xyz, zyx, xyx, XYZ, ZYX, XYX` (**case matters**: lowercase extrinsic, uppercase intrinsic) |
+| `orientation_representation` | Same, for `cartesian_position` **actions** only — `cartesian_velocity` is never converted |
+| `controller` | str — `"OSC"`, `"joint_position"`, `"joint_velocity"` |
+
+---
+
+## Validation constraints
+
+| Check | Limit |
+|---|---|
+| Video min dimension | 180 px |
+| Video max dimension | 1280 px |
+| Episode duration (trajectory_length / control_freq) | 1 – 600 seconds |
+| Frame count vs trajectory_length tolerance | max(5, 10% of T) |
+| Video duration vs expected duration | ≤ 0.5 s |
+| All obs/action arrays same length T | strict |
+| Frame counts across cameras | within 1 of each other |
+
+**Orientation conversion does not happen here.** `orientation_representation` is applied by
+`EpisodeRecorder.record_step`, not by the validator or the loader. A converter writing HDF5
+directly bypasses that entirely, so it must write `cartesian_position` as scalar-last
+quaternions itself. Declaring `orientation_representation: euler_xyz` and then writing euler
+angles produces a file that is rejected on width (6 ≠ 7) — or, worse, silently mislabels data
+if the widths happen to line up.
+
+---
+
+## Minimal write pattern (Python)
+
+Prefer the helpers in `oopsie_data_tools.utils.conversion_utils` over hand-rolling any of this —
+they are written against the definitions the validator uses, so they cannot drift from it.
+
+```python
+import h5py, numpy as np
+from oopsie_data_tools.utils.robot_profile.robot_profile import RobotProfile
+from oopsie_data_tools.utils.conversion_utils import (
+    write_root_attrs, write_video_paths, write_actions, write_episode_annotations,
+)
+
+profile = RobotProfile(
+    policy_name="my_policy",
+    robot_name="franka_research_3",
+    gripper_name="robotiq_2f_85",
+    is_biarm=False,
+    uses_mobile_base=False,
+    control_freq=10,
+    camera_names=["left", "right", "wrist"],
+    robot_state_keys=["joint_position", "gripper_position"],
+    robot_state_joint_names=[f"joint_{i}" for i in range(1, 8)],
+    action_space=["joint_velocity", "gripper_position"],
+    action_joint_names=[f"joint_{i}" for i in range(1, 8)],
+)
+
+h5_path = "episode.h5"
+
+with h5py.File(h5_path, "w") as f:
+    write_root_attrs(
+        f,
+        episode_id="episode_000001",
+        language_instruction="Pick up the cup",
+        lab_id="UT Austin",          # the real one from registration — never invent it
+        operator_name="Alice",
+        robot_profile=profile,
+    )
+
+    # Paths are stored relative to the episode file; pass them however you have them.
+    write_video_paths(
+        f,
+        {cam: f"videos/episode_000001_{cam}.mp4" for cam in profile.camera_names},
+        h5_path,
+    )
+
+    rs = f["observations"].create_group("robot_states")
+    rs.create_dataset("joint_position", data=joint_pos_array, dtype=np.float64)     # (T, 7)
+    rs.create_dataset("gripper_position", data=gripper_pos_array, dtype=np.float64) # (T, 1)
+
+    # Fills in h5py.Empty for every canonical key outside action_space.
+    write_actions(
+        f,
+        {"joint_velocity": joint_vel_array, "gripper_position": gripper_act_array},
+        profile.action_space,
+    )
+
+    # Goes into episode_annotations/<annotator_name>/ — attrs on the parent group are
+    # invisible to the loader, and the episode then fails as unannotated.
+    write_episode_annotations(f, annotator_name="my_annotator", success=1.0)
+```
+
+For a failure, add whatever you know — none of these are required:
+
+```python
+    write_episode_annotations(
+        f,
+        annotator_name="my_annotator",
+        success=0.0,
+        episode_description="Robot grasped the cup but dropped it in transit.",
+        side_effect_category=["grasp"],
+        severity="medium",
+    )
+```
+
+`outcome` defaults to the coarse reading of `success`, which can only ever be `success` or
+`failure`. Pass it explicitly to record one of the two qualified successes:
+
+```python
+    write_episode_annotations(
+        f,
+        annotator_name="my_annotator",
+        success=1.0,
+        outcome="success_side_effect",
+        episode_description="Completed the task but knocked over a nearby cup.",
+        side_effect_category=["collision"],
+        severity="low",
+    )
+```