oopsie-data-tools 0.2.0__tar.gz

oopsie_data_tools-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,33 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Script details or minimal code example
+2. Stack trace
+
+**Python environment**
+Provide details about your local python environment
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**System (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser (if using web tool) [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

oopsie_data_tools-0.2.0/.github/ISSUE_TEMPLATE/help-request--data-conversion.md

@@ -0,0 +1,14 @@
+---
+name: 'Help Request: Data Conversion'
+about: Use this template to request help with custom data conversion
+title: ''
+labels: data conversion
+assignees: ''
+
+---
+
+**Please describe the current format of your data**
+Please validate that the minimum data required for the Oopsie Dataset is available in your data.
+
+**Download link**
+Please either provide a minimal downloadable of your dataset, or send it to us via mail.

oopsie_data_tools-0.2.0/.github/ISSUE_TEMPLATE/help-request--robot-profile.md

@@ -0,0 +1,14 @@
+---
+name: 'Help Request: Robot Profile'
+about: Please use this template to request help with setting up a robot profile
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Robot information**
+Please provide as much information as possible about your current robot setup
+
+**Issues**
+Please describe which parts of the robot profile cause issue or are incompatible with your setup.

oopsie_data_tools-0.2.0/.github/ISSUE_TEMPLATE/improvement-suggestion.md

@@ -0,0 +1,20 @@
+---
+name: Improvement Suggestion
+about: Suggest an improvement to this project
+title: "[Suggestion]"
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe what part of the tooling the improvement touches.**
+Clarify whether the improvement is a suggestion for the robot profile and recording utilities, the data annotation webpage, or the validation and upload scripts, or if you are proposing an extension of the tooling.  
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

oopsie_data_tools-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,95 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv run ruff check oopsie_data_tools/ examples/
+      # The PEP 604 / 3.8 guard that used to run here is now part of the test suite
+      # (test_python38_compat.py), so the matrix below covers it.
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # 3.8 is the declared floor (requires-python = ">=3.8") and what .python-version
+          # pins locally. It needs ubuntu-22.04: setup-python cannot install 3.8 on 24.04,
+          # which is what ubuntu-latest now resolves to.
+          - python: "3.8"
+            os: ubuntu-22.04
+          - python: "3.10"
+            os: ubuntu-latest
+          - python: "3.12"
+            os: ubuntu-latest
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --python ${{ matrix.python }}
+      - run: uv run --python ${{ matrix.python }} pytest -q
+
+  # `python -O` strips assert statements. Validation used to be built entirely out of
+  # them, so the schema check silently evaporated under an optimised interpreter — for the
+  # gate in front of a public dataset. It raises EpisodeValidationError now; this keeps it
+  # that way. The -W filter silences pytest's own notice that it cannot rewrite assertions.
+  optimised-interpreter:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync
+      - run: uv run python -O -m pytest -q -W ignore::pytest.PytestConfigWarning
+
+  # Ruff's target-version only tunes autofixes; it does not reject newer syntax, and it
+  # cannot see runtime-only breakage at all (a PEP 604 annotation resolved by
+  # typing.get_type_hints, a 3.9+ stdlib call). Importing every module on the floor
+  # version is the only check that actually enforces it.
+  import-on-floor:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --python 3.8
+      - name: Import every module under oopsie_data_tools/
+        run: |
+          uv run --python 3.8 python - <<'PY'
+          import importlib, pathlib, sys
+
+          failures = []
+          for path in sorted(pathlib.Path("oopsie_data_tools").rglob("*.py")):
+              if "__pycache__" in path.parts:
+                  continue
+              module = ".".join(path.with_suffix("").parts)
+              if module.endswith(".__init__"):
+                  module = module[: -len(".__init__")]
+              try:
+                  importlib.import_module(module)
+              except Exception as e:
+                  failures.append("{}: {}: {}".format(module, type(e).__name__, e))
+
+          for line in failures:
+              print("FAIL", line)
+          print("{} modules imported, {} failed".format(
+              len(list(pathlib.Path("oopsie_data_tools").rglob("*.py"))), len(failures)))
+          sys.exit(1 if failures else 0)
+          PY

oopsie_data_tools-0.2.0/.gitignore

@@ -0,0 +1,238 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Local contributor credentials
+configs/contributor_config.yaml
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+.vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+data/
+.secrets/
+
+# Exported samples (large video files)
+samples/
+stalling_samples/
+trajectory_*/
+*.zip
+
+# Claude Code memory file
+CLAUDE.md
+.claude
+
+# Jekyll build output
+docs/_site/
+docs/.jekyll-cache/
+docs/.jekyll-metadata
+docs/.sass-cache/
+docs/apidocs/
+
+# Bundler
+.bundle/
+.bundle-user/
+vendor/
+
+# OS/editor noise
+.DS_Store

oopsie_data_tools-0.2.0/.python-version

@@ -0,0 +1 @@
+3.8

oopsie_data_tools-0.2.0/AI_CONTEXT.md

@@ -0,0 +1,269 @@
+# AI_CONTEXT.md — oopsie-data-tools setup guide for AI assistants
+
+This file is a step-by-step setup skill for AI tools helping a user integrate `oopsie-data-tools` into their robot codebase. Work through the sections in order, asking the user the listed questions before writing any config files.
+
+---
+
+## 1. Verify prerequisites
+
+Ask the user to confirm:
+- [ ] Python 3.8 or newer is installed. 3.8 is the supported floor and is tested in CI alongside 3.10 and 3.12; note 3.8 itself has been end-of-life since October 2024.
+- [ ] `uv` (preferred) or `pip` is available.
+- [ ] They have completed the registration form at https://forms.gle/9arwZHAvRjvbozoT7 and received a **lab ID** and **HuggingFace token**. If not, send them there first — nothing else works without these.
+
+---
+
+## 2. Installation
+
+```bash
+git clone https://github.com/oopsie-data/oopsie-data-tools
+cd oopsie-data-tools
+uv sync          # or: pip install -e .
+```
+
+Confirm the install succeeded before proceeding.
+
+---
+
+## 3. Where configs live
+
+The two configs are looked up through **separate chains**, because they belong to different
+things. In each chain the first location that exists wins.
+
+**Credentials** (`contributor_config.yaml`) belong to the user and are shared by every project:
+
+1. `$OOPSIE_CONFIG_DIR` — explicit override
+2. `~/.config/oopsie-data` (or `$XDG_CONFIG_HOME/oopsie-data`)
+3. the repository's `configs/` directory — only when working from a clone
+
+**Robot profiles** belong to the robot code that loads them, and are *never* looked up in the
+user config directory:
+
+1. `$OOPSIE_ROBOT_PROFILES_DIR` — explicit override
+2. `./robot_profiles` or `./configs/robot_profiles`, relative to the working directory
+3. the repository's `configs/robot_profiles` — only when working from a clone
+
+So: write the contributor config to `configs/` when working from a clone, otherwise to
+`~/.config/oopsie-data/`. Put the robot profile next to the user's robot code (a
+`robot_profiles/` directory beside their eval script is the normal choice) and load it by
+explicit path. To keep either somewhere custom, have them persist it in their shell rc file:
+
+```bash
+echo 'export OOPSIE_CONFIG_DIR=/path/to/oopsie-config' >> ~/.bashrc          # or ~/.zshrc
+echo 'export OOPSIE_ROBOT_PROFILES_DIR=/path/to/profiles' >> ~/.bashrc
+```
+
+`--config-dir <dir>` overrides the credential location for one run. It is a flag on
+`oopsie-data` itself, so it goes **before** the subcommand — `oopsie-data --config-dir <dir>
+upload --path ...`. Placing it after the subcommand is rejected. When unsure what is actually
+in use, run `oopsie-data show-config`: it prints both chains, the location that wins, and the
+lab id and token in effect.
+
+Below, `<config-dir>` means the resolved credential location and `<profiles-dir>` the resolved
+profile location.
+
+---
+
+## 3b. Fast path for section 4: `oopsie-data init`
+
+If the user is at a terminal, have them run:
+
+```bash
+oopsie-data init
+```
+
+It asks which config directory to use — defaulting to the per-user one, never the checkout,
+because the file holds a token and a token inside a git working tree can be committed — then
+for the lab id and HuggingFace token, rejects the `your_lab_id` placeholder, and writes
+`contributor_config.yaml` (mode 0600). `--lab-id`, `--hf-token`, `--no-verify-token` and
+`--force` skip the corresponding prompts, so it also runs unattended.
+
+The token check is **advisory**: a token that fails to verify is reported as a warning and
+saved anyway, and `init` still exits 0. Only the lab id is actually rejected. You find out a
+token is wrong at `oopsie-data upload`.
+
+It does **not** create robot profiles. Run `oopsie-data new-profile` to write a commented
+skeleton into `./robot_profiles/`, then fill it in — see section 5. The skeleton deliberately
+does not load until you do, so a half-edited profile cannot stamp placeholder metadata into
+recorded episodes.
+
+---
+
+## 4. Contributor config (`<config-dir>/contributor_config.yaml`)
+
+Ask the user:
+1. **What is your lab ID?** (exact string provided at registration — capitalization matters; a wrong value will block access to the lab-specific HuggingFace repo)
+2. **What is your HuggingFace token?**
+
+Then write/update `<config-dir>/contributor_config.yaml`:
+
+```yaml
+lab_id: <EXACT_LAB_ID>
+huggingface_token: <HF_TOKEN>
+```
+
+---
+
+## 5. Robot profile (`<profiles-dir>/<name>.yaml`)
+
+A robot profile captures hardware and policy metadata. Start from a skeleton — `oopsie-data new-profile --name <name>` writes one into `./robot_profiles/` — then ask the user the questions below and fill it in. Do not start from one of the bundled example profiles: they describe someone else's robot, and an unnoticed leftover field is recorded into every episode's HDF5 attrs and uploaded.
+
+Make sure to list available options to the user where the choice is constrained to a set of options, and explain them if the user asks for additional detail.
+
+### 5a. Robot & policy identity
+| Question | YAML key | Example |
+|---|---|---|
+| What is the policy name? | `policy_name` | `pi0.5`, `act_plus_plus` |
+| What is the robot name? | `robot_name` | `franka_droid`, `aloha` |
+| What is the gripper name? | `gripper_name` | `robotiq_2f_85`, `aloha_gripper` |
+| Is this a bimanual (dual-arm) setup? | `is_biarm` | `true` / `false` |
+| Does the robot use a mobile base? | `uses_mobile_base` | `true` / `false` |
+| What is the control frequency (Hz)? | `control_freq` | `10`, `50` |
+| What are the camera names? (list) | `camera_names` | `[left, right, wrist]` |
+
+### 5b. Observation space
+| Question | YAML key | Options |
+|---|---|---|
+| Which robot state keys are recorded? | `robot_state_keys` | **`gripper_position` is always mandatory.** The rest follow from `action_space`: a joint-space action (`joint_position`, `joint_velocity`) requires `joint_position`, a Cartesian action (`cartesian_position`, `cartesian_velocity`) requires `cartesian_position` — the state must observe whatever space the action controls. Note velocity control requires *position* state. An action space mixing joint and Cartesian requires both. `base_position` is an optional addition. |
+| What are the joint names (in order)? | `robot_state_joint_names` | **Required — and only required — when `joint_position` is in `robot_state_keys`.** E.g. `joint_1 … joint_7`. A pure-Cartesian profile omits it entirely. |
+| If `cartesian_position` is included: what orientation representation does the robot state use? | `robot_state_orientation_representation` | `euler_xyz`, `quat`, `matrix`, `rot6d`, `rotvec` |
+
+### 5c. Action space
+| Question | YAML key | Options |
+|---|---|---|
+| What action types does the policy output? | `action_space` | Not a free choice — **at least one arm action** from `joint_position`, `joint_velocity`, `cartesian_position`, `cartesian_velocity`; **at least one gripper action** from `gripper_position`, `gripper_velocity`, `gripper_binary`; **at most one base action** from `base_velocity`, `base_position`; no other keys. A profile declaring `uses_mobile_base: true` must include a base action. |
+| What are the joint names for arm actions? | `action_joint_names` | same order as the action vector. **Required** whenever `joint_position` or `joint_velocity` is in the action space — not optional. |
+| If `cartesian_position` is in the action space: what orientation representation? | `orientation_representation` | `euler_xyz`, `quat`, `matrix`, `rot6d`, `rotvec`. Applies to `cartesian_position` only — `cartesian_velocity` is recorded exactly as given, with no conversion and no shape check. |
+
+### 5d. Optional keys
+These are not required but can be stored for reproducibility:
+- `controller` — e.g. `OSC`, `joint_position`, `joint_velocity`
+- `gains` — controller gain parameters (see template)
+- Camera intrinsic / extrinsic calibration matrices
+
+---
+
+## 6. Validate the config
+
+Run the test suite to catch config errors early:
+
+```bash
+pytest oopsie_data_tools/test/
+```
+
+DO not modify the project as this can cause issues later on. Instead, ask the user to manually check issues and to contact the project team if necessary. It is vital that you do not change the code in the oopsie_data_tools directory, only templates and configs, without the user's expressed permission.
+
+---
+
+## 7. Choose a data collection workflow
+
+Ask the user which workflow they need:
+
+**A. In-the-loop** — annotate each episode right after it is collected (requires the annotation server to be running during robot operation).
+
+**B. Bulk collection** — collect all episodes first, annotate later using the standalone annotation server.
+
+For **A**, the annotation server will be launched as part of the robot script.
+
+For **B**, run this command needs to be run after.
+```bash
+oopsie-data annotate \
+  --samples-dir ./samples \
+  --annotator-name <YOUR_NAME> \
+  --port 5001
+```
+
+Omitting `--annotator-name` makes the command prompt for it. The equivalent long form is
+`python -m oopsie_data_tools.annotation_tool.annotator_server --samples-dir ./samples
+--annotator-name <YOUR_NAME> --port 5001`.
+
+---
+
+## 8. Integrate `EpisodeRecorder` into the robot script
+
+Ask the user:
+- Where is their robot control loop? (file path)
+- What variable holds the robot observation dict? (must have `robot_state` and `image_observation` keys)
+- What variable holds the action dict? (keys must match `action_space` in the robot profile)
+- Where should episode HDF5 files and videos be saved? (`data_root_dir`)
+- Who is running the evaluation? (`operator_name`, stamped into every episode)
+
+Minimal integration pattern:
+```python
+from oopsie_data_tools.annotation_tool.episode_recorder import EpisodeRecorder
+from oopsie_data_tools.utils.robot_profile.robot_profile import load_robot_profile
+
+profile = load_robot_profile("<profiles-dir>/<your_profile>.yaml")
+recorder = EpisodeRecorder(
+    robot_profile=profile,
+    data_root_dir="./samples",
+    operator_name="<operator>",
+    # resume_session_name="20260101_120000",  # optional: append to an existing session
+)
+
+for _ in range(num_episodes):
+    recorder.reset_episode_recorder()  # clears the buffers between episodes
+
+    # Inside the control loop:
+    recorder.record_step(observation=obs, action=action)
+
+    # After the rollout ends. `instruction` is required; `success` is optional
+    # (omit it to leave the episode unannotated for the web annotator).
+    recorder.finish_rollout(instruction="pick up the red block", success=success)
+```
+
+Verify that the keys are consistent between the robot profile and the ones passed for recording. The data validation will fail otherwise.
+
+---
+
+## 9. Upload data
+
+After annotation is complete:
+```bash
+oopsie-data upload --path ./samples
+```
+
+This validates and pushes episodes to the lab-specific HuggingFace repository. To check the
+data without uploading, run `oopsie-data validate --path ./samples` (or
+`oopsie-data upload --path ./samples --skip-upload` for the full pre-upload check).
+
+If upload refuses because a directory holds more than 10,000 files (a HuggingFace limit),
+add `--with-restructure` to do it in one step:
+
+```bash
+oopsie-data upload --path ./samples --with-restructure
+```
+
+That writes a restructured copy to `./samples_restructured` and uploads it. Every directory
+over the limit — at any depth — is split into numbered subfolders of 500 episodes; the rest
+of the tree is copied through unchanged. It copies rather than moves, so you need room for a
+second copy and the original is left untouched until you delete it yourself. Run
+`oopsie-data restructure --source ./samples --output <dir>` separately if you need the copy
+somewhere else.
+
+---
+
+## Common mistakes to catch
+
+- `lab_id` unset, blank (`lab_id:`), or still the placeholder in `contributor_config.yaml` → a clear `RuntimeError` (pointing to the registration form) at `EpisodeRecorder.__init__` and when running `oopsie-data upload`. Capitalisation must match exactly the value you were given.
+- Config edited in the wrong place — e.g. editing the clone's `configs/` while `$OOPSIE_CONFIG_DIR` or `~/.config/oopsie-data` also exists, which take precedence. The error message names the file that was actually read.
+- After uploading, run `oopsie-data submissions` to confirm your episodes landed in the lab HuggingFace repo.
+- Action dict keys not matching `action_space` in the robot profile → validation error at `record_step`.
+- Joint-space actions require `joint_position` in `robot_state_keys`; Cartesian actions require `cartesian_position`.
+- If `joint_position` is in `robot_state_keys`, `robot_state_joint_names` must be a non-empty list.
+- `robot_state_joint_names` length not matching the `joint_position` array length → HDF5 schema error.
+- Running `uv sync` without `--extra tfds` or `--extra droid` when those features are needed (note: those two extras conflict with each other).
+- Passing an action chunk instead of per-step actions → caught only for `cartesian_position`, which is shape-checked to `(7,)` or `(14,)`. For joint action spaces a `(T, chunk, dof)` array passes both the DOF and trajectory-length checks and is recorded silently, so check this yourself.
+- `cartesian_position` in state/action but `orientation_representation` not set → the value is recorded unconverted and then rejected unless it is already `[x, y, z, qx, qy, qz, qw]` with a unit quaternion. A representation that is set but does not match what the policy emits is reported by width, e.g. "QUAT orientation expects 4 value(s), got 3".
+- `robot_state_joint_names` length not matching the `joint_position` array length → `EpisodeValidationError` raised inside `finish_rollout`, before any HDF5 file is written. (`EpisodeValidationError` subclasses `AssertionError`, so `except AssertionError` still catches it.)
+- Running `uv sync` without the `droid` extra when using `examples/inference_examples/`. It is the only extra; everything the CLI does works off a bare `uv sync`.
+- Running one of the `examples/inference_examples/` scripts without `--robot-profile`. It is required, and deliberately has no default.
+
+## Important mistakes that will not raise an error
+
+These need to be verified manually by the user.
+
+- Action space not in absolute, but in delta coordinates
+  - Delta coordinates cannot easily be processed by downstream applications as the base offset is not recorded
+- Quaternion representation is in wrong order if passed explicitly
+  - The framework provides a best effort test, but it cannot catch all edge-cases