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

oopsie_data_tools/skill/reference/format.md

@@ -0,0 +1,112 @@
+# The `oopsiedata_format_v1` data format
+
+One episode per HDF5 file, with its MP4 videos alongside. Run `oopsie-data inspect <file.h5>` to
+see what a file actually contains before theorizing about it — it works even on files `validate`
+rejects.
+
+## Layout
+
+Root attributes — `schema`, `episode_id`, `language_instruction`, `lab_id`, `operator_name` and
+`robot_profile` (the whole profile, JSON-serialized) are **required**. `timestamp` (float epoch
+seconds) is written by the recorder but not required by the loader.
+
+```
+observations/
+  robot_states/<key>      one float64 dataset per profile.robot_state_keys, shape (T, ...)
+  video_paths/<camera>    one string dataset per profile.camera_names, holding a path
+                          relative to the .h5 file
+actions/<key>             one dataset per VALID_ACTION_KEYS
+episode_annotations/<annotator_name>/    optional; annotation fields are HDF5 attrs on the
+                          subgroup, not datasets
+```
+
+Note that state datasets live under `observations/robot_states/`, not directly under
+`observations/`.
+
+## Actions
+
+The recorder writes a dataset for **all nine** valid action keys. Keys outside the profile's
+`action_space` are written as `h5py.Empty` placeholders; **every key in `action_space` must be a
+real tensor** — an `h5py.Empty` there is rejected with `actions/<key> is in profile.action_space
+but stored as h5py.Empty`. Since a valid action space always has at least one arm and one gripper
+key, at least two `actions/` datasets are always real.
+
+The reverse also holds: a non-empty action dataset the profile does not declare is rejected.
+
+Actions are **unnormalized and absolute**. Bi-arm setups concatenate left and right.
+
+## What the validator checks
+
+Metadata:
+
+- `language_instruction`, `episode_id`, `lab_id`, `operator_name` all non-empty; `lab_id` must
+  not still be `your_lab_id`.
+- `control_freq > 0`.
+- **Episode duration, not step count**: `trajectory_length / control_freq` must be between 1 and
+  600 seconds. A 5-step episode at 10 Hz is rejected.
+
+Profile consistency — the profile documents the episode, so both directions are enforced:
+
+- Every `robot_state_keys`, `action_space` and `camera_names` entry must be present.
+- Nothing may be present that the profile does not declare, for either
+  `observations/robot_states` or `actions`.
+- `len(robot_state_joint_names)` must equal the last axis of `observations/joint_position`, when
+  `joint_position` is recorded at all.
+- `len(action_joint_names)` must equal the last axis of `actions/joint_position` /
+  `joint_velocity`, when set.
+- `cartesian_position` (state or action) must be exactly 7 DOF, or 14 when `is_biarm` — it is
+  `[x, y, z, qx, qy, qz, qw]` per arm. Joint counts are deliberately **not** constrained by
+  `is_biarm`: two arms need not share a DOF count. Gripper DOF is not checked at all, since
+  nothing in the profile declares it.
+
+Trajectories:
+
+- Every observation and action array must share the same leading dimension `T`.
+
+Videos:
+
+- Each side between 180 and 1280 px.
+- Frame count within `max(5, 0.1 * T)` of `T`.
+- Video duration within 0.5 s of `T / control_freq`.
+- Frame counts across cameras within 1 of each other.
+
+Annotations — **always checked by `validate` and `upload`.** The `strict_annotation_check`
+*parameter* defaults to `False`, but `run_validation` — what both CLI commands call — passes
+`True` unconditionally, so an episode with no `episode_annotations` group fails with
+`Annotations dict is empty, must be provided for upload`. Record an episode first and annotate
+it second; it is only between those two steps that an unannotated episode is legal.
+
+- Every annotator subgroup needs a numeric, non-NaN `success` in `[0.0, 1.0]`.
+- A present `taxonomy` attr must parse as a JSON object.
+- If that object carries an `outcome`, it must be one of `success`, `success_suboptimal`,
+  `success_side_effect`, `failure`, and must agree in sign with `success` (`failure` iff
+  `success < 0.5`).
+- Nothing else is required. `episode_description`, `side_effect_category` and `severity` are
+  all optional in every branch, so a partial annotation — including a failure with no taxonomy
+  at all — is valid. Taxonomy v1 files, which carry no `outcome`, skip the outcome check and
+  remain valid unchanged.
+
+## Recording-time checks
+
+`record_step` requires:
+
+- `observation` to be a dict with both `robot_state` and `image_observation`;
+- `robot_state` to contain every `robot_state_keys` entry, and `image_observation` a key named
+  exactly `<cam>` for every `camera_names` entry — the alternative spellings `image_<cam>` and
+  `<cam>_image` are recognized when the frame is read, but the presence check runs first and
+  rejects the step, so they are not a usable substitute for the plain name;
+- `action` keys to equal `action_space` exactly, with no `None` values.
+
+`cartesian_position` is converted to `(x, y, z, qx, qy, qz, qw)` via
+`orientation_representation`, then shape-checked to `(7,)` or `(14,)` with a unit quaternion in
+`[3:7]` (tolerance 1e-2). Everything else is recorded as given.
+
+`finish_rollout` validates *before* writing videos or HDF5, so a rejected episode leaves nothing
+on disk. It runs the same checks as `validate` **except** the annotation ones — this is the one
+path that uses the lenient default — which is why `finish_rollout(instruction=...)` without
+`success` is allowed, and why the resulting episode does not pass `validate` until annotated. It raises `EpisodeValidationError`, which subclasses `AssertionError` — so an existing
+`except AssertionError` still catches it. One exception: a camera with zero buffered frames
+raises a plain `ValueError` from `VideoInfo.from_frames`, which neither catches.
+
+Episode file names are second-resolution timestamps with `_2`, `_3` suffixes on collision, so do
+not parse them as pure timestamps.

oopsie_data_tools/skill/reference/robot-profile.md

@@ -0,0 +1,104 @@
+# Robot profile
+
+A robot profile captures hardware and policy metadata. It is serialized to JSON and stored as an
+HDF5 root attribute on every episode, so it is the episode's documentation — the validator
+checks the recorded data against it in both directions.
+
+Start from `oopsie-data new-profile --name <name>`, which writes a commented skeleton into
+`<profiles-dir>/`. Every required field is blank, so the profile will not load until a human
+fills it in. Ask the user the questions below; where the choice is constrained to a set, list the
+options and explain them if asked.
+
+## Required fields
+
+All nine must be present or `load_robot_profile` raises `Robot profile missing keys: [...]`.
+
+| Question | YAML key | Example / rule |
+|---|---|---|
+| 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 setup? | `is_biarm` | `true` / `false` |
+| Does the robot use a mobile base? | `uses_mobile_base` | `true` / `false` |
+| Control frequency (Hz)? | `control_freq` | `10`, `50` — must be > 0 |
+| Camera names? | `camera_names` | `[left, right, wrist]` |
+| Which robot state keys are recorded? | `robot_state_keys` | see below |
+| What does the policy output? | `action_space` | see below |
+
+### `robot_state_keys`
+
+`gripper_position` is **always mandatory**. Beyond that, the state must observe whatever space
+the action controls — checked at profile load:
+
+| If `action_space` contains | `robot_state_keys` must contain |
+|---|---|
+| `joint_position` or `joint_velocity` | `joint_position` |
+| `cartesian_position` or `cartesian_velocity` | `cartesian_position` |
+
+Velocity control requires *position* state: you observe where the arm is, you command how fast
+it moves. The requirement is a union over the action space, so an `action_space` mixing joint
+and Cartesian actions needs both keys. `base_position` is an optional addition — no base action
+currently requires it.
+
+`base_position` aside, nothing else may be recorded: an observation key the profile does not
+declare fails validation, because it has no joint names, units or expected DOF and nothing
+downstream can interpret it.
+
+### `robot_state_joint_names`
+
+**Required when — and only when — `joint_position` is in `robot_state_keys`**; a profile whose
+robot is controlled purely in Cartesian space omits it. When present it must have exactly as
+many entries as the last axis of the recorded `joint_position` array. The emptiness is caught at
+profile load; the length mismatch at validation.
+
+### `action_space`
+
+Not a free choice. The rule (`is_valid_action_space`):
+
+- **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
+
+Declaring two arm actions or two gripper actions is legal — but every declared key must then be
+recorded as a real array in every episode. A profile with `uses_mobile_base: true` must include a
+base action. (The converse is not checked: a base action with `uses_mobile_base: false` passes.)
+
+The dict passed to `record_step` must have keys equal to `action_space` **exactly** — not a
+subset, not a superset.
+
+## Conditionally required
+
+| Question | YAML key | Rule |
+|---|---|---|
+| Joint names for the robot state, in order? | `robot_state_joint_names` | **Required** whenever `joint_position` is in `robot_state_keys` — see above. Not one of the nine unconditional keys, so a purely Cartesian profile omits it entirely. |
+| Joint names for arm actions? | `action_joint_names` | **Required** whenever `joint_position` or `joint_velocity` is in `action_space`. Same order as the action vector; its length is checked against the recorded DOF. |
+| Orientation representation for cartesian actions? | `orientation_representation` | Needed whenever `cartesian_position` is in `action_space` and the policy does not already emit scalar-last quaternions. |
+| Orientation representation for cartesian state? | `robot_state_orientation_representation` | Same, for `cartesian_position` in `robot_state_keys`. |
+
+### Orientation representation values
+
+`quat` (scalar-last, shape `(4,)`), `matrix` (`(3, 3)`), `rot6d` (first two columns of the
+rotation matrix, flattened, `(6,)` — what openpi uses), `rotvec` (axis-angle, `(3,)`), or
+`euler_<order>` where order is one of `xyz`, `zyx`, `xyx`, `XYZ`, `ZYX`, `XYX`. **Case is
+meaningful**: lowercase orders are extrinsic rotations, uppercase intrinsic.
+
+These strings are **not validated when the YAML is parsed**. A bad value is stored verbatim and
+surfaces as a plain `ValueError` from `EpisodeRecorder.__init__` — at construction, not
+mid-rollout, but not as a profile error either.
+
+Conversion applies to `cartesian_position` only. `cartesian_velocity` is recorded exactly as
+given, with no conversion and no shape check.
+
+## Optional
+
+Stored for reproducibility, never validated:
+
+- `controller` — e.g. `OSC`, `joint_position`, `joint_velocity`
+- `gains` — controller gains; see the skeleton for the expected nesting
+- `intrinsic_calibration_matrix` / `extrinsic_calibration_matrix`, keyed by camera name. Both
+  the underscored and the spaced spelling (`intrinsic calibration matrix`) are read; the
+  underscored one is canonical.
+
+Please ask explicitly if the user wants to provide the optional inputs!

oopsie_data_tools/skill/reference/setup.md

@@ -0,0 +1,216 @@
+# Setup
+
+Onboarding a user into `oopsie-data-tools`, in order. Ask the questions in each section before
+writing anything.
+
+## 1. Prerequisites
+
+- Python 3.8 or newer. 3.8 is the supported floor and is tested in CI alongside 3.10 and 3.12,
+  but 3.8 itself has been end-of-life since October 2024 — prefer newer if the user has a choice.
+- `uv` (preferred) or `pip`.
+- A **lab ID** and **HuggingFace token** from the registration form,
+  <https://forms.gle/9arwZHAvRjvbozoT7>. Nothing works without these; if the user does not have
+  them, send them there first.
+
+## 2. Installation
+
+To use the toolkit:
+
+```bash
+uv add oopsie-data-tools        # or: pip install oopsie-data-tools
+```
+
+To work from a checkout (contributing to the toolkit, or running the bundled examples):
+
+```bash
+git clone https://github.com/oopsie-data/oopsie-data-tools
+cd oopsie-data-tools
+uv sync                         # or: pip install -e .
+uv sync --extra droid           # only for examples/inference_examples/
+```
+
+`droid` is the only extra; everything the CLI does works off a bare install. In a `uv sync`
+checkout, every command below needs a `uv run` prefix.
+
+Confirm `oopsie-data --version` works before continuing.
+
+## 3. Where configs live
+
+The two kinds of config 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: let `oopsie-data init` write the contributor config (it defaults to `~/.config/oopsie-data`,
+never the checkout, because the file holds a token and a token inside a git working tree can be
+committed). 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, persist it in the 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 an argparse error.
+
+When unsure what is in effect, run `oopsie-data show-config`: it prints both chains, the
+location that wins, and the lab id and token in use (`--show-token` prints the token unmasked).
+`$HF_TOKEN` in the environment overrides the stored token.
+
+Below, `<config-dir>` means the resolved credential location and `<profiles-dir>` the resolved
+profile location.
+
+## 4. Contributor config — `oopsie-data init`
+
+Ask the user for:
+
+1. **Their lab ID** — the exact string from registration. Capitalization matters; a wrong value
+   blocks access to the lab's HuggingFace repo.
+2. **Their HuggingFace token.**
+
+Then have them run:
+
+```bash
+oopsie-data init
+```
+
+It asks which config directory to use, then for the lab id and token, rejects the `your_lab_id`
+placeholder, and writes `<config-dir>/contributor_config.yaml` with mode 0600. `--lab-id`,
+`--hf-token`, `--no-verify-token` and `--force` skip the corresponding prompts, so it also runs
+unattended.
+
+Do **not** write this file by hand. The token check is **advisory**: a token that fails to
+verify is reported as a warning, 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`.
+
+`init` does not create robot profiles — see section 5.
+
+## 5. Robot profile
+
+```bash
+oopsie-data new-profile --name <name>       # writes <profiles-dir>/<name>.yaml
+```
+
+Then fill it in by hand, using `reference/robot-profile.md` for the questions to ask and the
+legal values. 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.
+
+Check the result loads:
+
+```bash
+python -c "from oopsie_data_tools.utils.robot_profile.robot_profile import load_robot_profile; load_robot_profile('<path>')"
+```
+
+## 6. Confirm the setup
+
+`oopsie-data show-config` is what verifies a contributor config; loading the profile as above is
+what verifies a profile. Real confirmation comes from `oopsie-data validate --path ./samples`
+once episodes exist.
+
+Running `pytest oopsie_data_tools/test/` checks the toolkit, not the user's setup — the suite
+deliberately isolates `HOME`, `XDG_CONFIG_HOME`, both `OOPSIE_*` variables and the working
+directory, so it cannot see the user's config at all.
+
+## 7. Choose an annotation workflow
+
+Ask which the user needs:
+
+**A. In-the-loop** — annotate each episode right after it is collected. The annotation server
+runs during robot operation; launch it from the robot script (`WebRolloutAnnotator`), or run
+`oopsie-data annotate --with-rollouts`.
+
+**B. Bulk collection** — collect everything first, annotate later:
+
+```bash
+oopsie-data annotate --samples-dir ./samples --annotator-name <YOUR_NAME> --port 5001
+```
+
+`--samples-dir` defaults to `./samples` and `--port` to 5001. Omitting `--annotator-name`
+prompts for it, and errors out when stdin is not a terminal. `--no-browser` suppresses opening
+a browser. The equivalent long form is `python -m
+oopsie_data_tools.annotation_tool.annotator_server --samples-dir ./samples --annotator-name
+<YOUR_NAME> --port 5001`.
+
+## 8. Wire `EpisodeRecorder` into the robot script
+
+Ask the user:
+
+- Where is their robot control loop? (file path)
+- What variable holds the observation dict? (needs `robot_state` and `image_observation` keys)
+- What variable holds the action dict? (keys must equal `action_space` in the profile exactly)
+- Where should episode HDF5 files and videos be saved? (`data_root_dir`)
+- Who is running the evaluation? (`operator_name`, stamped into every episode)
+
+```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 for the web annotator — but note that an episode
+    # with no annotation at all fails `oopsie-data validate`, so it must be annotated
+    # before it can be uploaded).
+    recorder.finish_rollout(instruction="pick up the red block", success=success)
+```
+
+`record_step` does not mutate the dicts it is passed. `finish_rollout` validates *before*
+writing anything, so a rejected episode leaves no MP4s and no HDF5 on disk.
+
+The keys in the profile and the keys passed to `record_step` must agree exactly — see
+`reference/format.md`.
+
+## 9. Upload
+
+```bash
+oopsie-data upload --path ./samples
+```
+
+This validates, then pushes to `OopsieData-Submissions/<lab_id>`. To check without publishing,
+use `oopsie-data validate --path ./samples`, or `upload --path ./samples --skip-upload` for the
+full pre-upload sequence. `--episode-id` restricts either command to one episode; `--log-path`
+writes a report.
+
+If upload refuses because a directory holds more than 10,000 files (a HuggingFace limit), add
+`--with-restructure`:
+
+```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, with video paths inside the copied HDF5 files rewritten. It
+copies rather than moves, so you need room for a second copy, and the original is untouched
+until the user deletes it. Run `oopsie-data restructure --source ./samples --output <dir>`
+separately to put the copy elsewhere.
+
+Afterwards, `oopsie-data submissions` confirms what landed in the lab's repo.

oopsie_data_tools/skill/reference/troubleshooting.md

@@ -0,0 +1,97 @@
+# Troubleshooting
+
+## Errors you will actually see
+
+**`lab_id` unset, blank (`lab_id:`), or still `your_lab_id`.** A `RuntimeError` pointing at the
+registration form, raised from `EpisodeRecorder.__init__` and from `oopsie-data upload`.
+Capitalization must match the value you were given exactly.
+
+**Config edited in the wrong place.** Editing the clone's `configs/` while `$OOPSIE_CONFIG_DIR`
+or `~/.config/oopsie-data` also exists — the earlier entry in the chain wins. The error message
+names the file that was actually read; `oopsie-data show-config` shows the whole chain.
+
+**Action dict keys not matching `action_space`.** Raised at `record_step`. The two must be equal
+as sets, not merely overlapping.
+
+**"missing robot state keys required by its action_space".** Raised at `load_robot_profile`. The
+state must observe the space the action controls: add `joint_position` to `robot_state_keys` for a
+`joint_position`/`joint_velocity` action space, or `cartesian_position` for a
+`cartesian_position`/`cartesian_velocity` one. `gripper_position` is required either way.
+
+**"robot_state_joint_names is required when joint_position is included in robot_state_keys".**
+Also at `load_robot_profile`. Name every joint, in the order the `joint_position` array uses. The
+key is needed *only* in that case — drop it from a purely Cartesian profile rather than leaving it
+blank.
+
+**`robot_state_joint_names` length ≠ `joint_position` DOF.** `EpisodeValidationError` inside
+`finish_rollout`, before any file is written.
+
+**`cartesian_position` recorded but `orientation_representation` unset.** The value is stored
+unconverted and then rejected unless it already is `[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`.
+
+**Episode duration out of range.** `[1, 600]` seconds, computed as `trajectory_length /
+control_freq` — not a step count. Short test rollouts trip this constantly.
+
+**"Annotations dict is empty, must be provided for upload".** The episode has no
+`episode_annotations` group. `validate` and `upload` both check annotations unconditionally, so a
+freshly recorded episode fails until someone has annotated it — run `oopsie-data annotate` first.
+This is expected between recording and annotation, not a malformed file.
+
+**"taxonomy is not valid JSON" / "taxonomy must be a JSON object".** The `taxonomy` attr on an
+annotator subgroup is stored as a JSON object string. Something wrote it by hand and got the
+quoting wrong — write annotations through `write_episode_annotations` or the annotation tool
+rather than setting the attr directly.
+
+**"unrecognized outcome" / "outcome disagrees with success".** The `outcome` slug inside
+`taxonomy` must be one of `success`, `success_suboptimal`, `success_side_effect`, `failure`,
+and must match the `success` float (`failure` iff `success < 0.5`). Both are only reachable by
+writing the attrs by hand; the writers derive one from the other. Taxonomy v1 files have no
+`outcome` at all and are exempt.
+
+**Undeclared keys.** `observations/robot_states contains N key(s) the robot profile does not
+declare`. Add them to the profile or stop recording them; an extra diagnostic channel is not
+allowed through.
+
+**"Too many files in a directory" on upload.** HuggingFace caps a directory at 10,000 files.
+`oopsie-data restructure --source ./samples` writes a split copy alongside the original
+(non-destructive, rewrites video paths inside the copied HDF5 files), or `oopsie-data upload
+--with-restructure` does it inline. Both need room for a second copy.
+
+**Low-diversity warnings on upload.** A submission of near-identical tasks or annotations warns
+by default and fails with `--strict-diversity`. It is a signal about dataset value, not a bug to
+silence. The check runs even under `--skip-validate`.
+
+**`--config-dir` rejected.** It is a flag on `oopsie-data` itself and must come *before* the
+subcommand.
+
+**`oopsie-data inspect --path ...` fails.** `inspect` takes a positional path.
+
+**`--robot-profile` missing** when running an `examples/inference_examples/` script. It is
+required and deliberately has no default. Those examples also need `uv sync --extra droid`.
+
+Exit codes: 1 on a handled failure, 2 for a bare invocation or argparse error, 130 on Ctrl-C.
+
+## Mistakes that pass validation silently
+
+These cannot be caught by the toolkit. Ask the user to confirm each.
+
+**Actions in delta rather than absolute coordinates.** Nothing detects this, and deltas cannot be
+used downstream because the base offset is not recorded.
+
+**Wrong quaternion component order.** Poses must be scalar-last, `(x, y, z, w)`. A scalar-first
+pose only produces a `logger.warning` from a heuristic, never an error.
+
+**An action chunk passed instead of a per-step action.** Only `cartesian_position` is
+shape-checked, to `(7,)` or `(14,)`. For joint action spaces a `(T, chunk, dof)` array satisfies
+both the DOF and trajectory-length checks and is recorded silently.
+
+**Annotation *quality*.** The presence and shape of annotations *is* checked (see above), but
+nothing judges what they say — whether a failure description actually describes what happened,
+or whether the category fits, is unverifiable by the toolkit.
+
+**`cartesian_velocity` of any shape.** It is recorded exactly as given, with no conversion and
+no shape check.
+
+**A base action declared with `uses_mobile_base: false`.** Only the other direction is checked.

oopsie_data_tools/test/__init__.py

@@ -0,0 +1 @@
+"""Test suite for oopsie_data_tools."""