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

oopsie_data_tools/utils/robot_profile/rotation_utils.py

@@ -0,0 +1,119 @@
+"""Convert the orientation half of a cartesian action into a scalar-last quaternion.
+
+A robot profile declares how its cartesian actions encode orientation
+(``orientation_representation``); the recorder normalizes everything to
+``(x, y, z, qx, qy, qz, qw)`` before writing an episode, so downstream consumers only
+ever see quaternions.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+import numpy as np
+from scipy.spatial.transform import Rotation as R
+
+_EULER_FORMATS = ("xyz", "zyx", "xyx", "XYZ", "ZYX", "XYX")
+
+
+class RotOption(Enum):
+    # Upper- and lower-case Euler orders are distinct on purpose: scipy reads uppercase as
+    # intrinsic rotations and lowercase as extrinsic ones.
+    XYZ = 0
+    ZYX = 1
+    XYX = 2
+    QUAT = 3
+    MATRIX = 4
+    ROT6D = 5
+    ROTVEC = 6
+    xyz = 7
+    zyx = 8
+    xyx = 9
+
+    @staticmethod
+    def from_string(s: str) -> "RotOption":
+        if s.startswith("euler_"):
+            euler_format = s[len("euler_") :]
+            if euler_format in _EULER_FORMATS:
+                return RotOption[euler_format]
+            raise ValueError(
+                f"Unsupported Euler format: {euler_format!r}. "
+                f"Expected one of {', '.join(_EULER_FORMATS)}."
+            )
+        try:
+            return {
+                "quat": RotOption.QUAT,
+                "matrix": RotOption.MATRIX,
+                "rot6d": RotOption.ROT6D,
+                "rotvec": RotOption.ROTVEC,
+            }[s]
+        except KeyError:
+            raise ValueError(
+                f"Unsupported rotation option: {s!r}. Expected 'quat', 'matrix', 'rot6d', "
+                "'rotvec', or 'euler_<order>'."
+            ) from None
+
+
+# How many elements each representation contributes to a flat action vector.
+_EXPECTED_SIZE = {
+    RotOption.QUAT: 4,
+    RotOption.MATRIX: 9,
+    RotOption.ROT6D: 6,
+    RotOption.ROTVEC: 3,
+    **{RotOption[f]: 3 for f in _EULER_FORMATS},
+}
+
+
+class ActionQuatConversion:
+    """Convert the rotation slice of a cartesian action to a scalar-last quaternion."""
+
+    def __init__(self, source_format: RotOption, is_biarm: bool = False) -> None:
+        self.rot_option = source_format
+        self.is_biarm = is_biarm
+
+    def _to_quat(self, arr: np.ndarray) -> np.ndarray:
+        expected = _EXPECTED_SIZE.get(self.rot_option)
+        if expected is None:
+            raise ValueError(f"Unsupported rotation option: {self.rot_option}")
+        if arr.size != expected:
+            raise ValueError(
+                f"{self.rot_option.name} orientation expects {expected} value(s), got "
+                f"{arr.size}. Check orientation_representation in the robot profile against "
+                "the action your policy emits."
+            )
+
+        if self.rot_option == RotOption.QUAT:
+            return arr
+        if self.rot_option == RotOption.MATRIX:
+            # Flat in the action vector, so reshape before handing it to scipy.
+            return R.from_matrix(arr.reshape(3, 3)).as_quat()
+        if self.rot_option == RotOption.ROT6D:
+            # First two columns of the rotation matrix; rebuild the third by Gram-Schmidt.
+            rot6d = arr.reshape(2, 3)
+            u1 = rot6d[0] / np.linalg.norm(rot6d[0])
+            u2 = rot6d[1] - np.dot(rot6d[1], u1) * u1
+            u2 /= np.linalg.norm(u2)
+            u3 = np.cross(u1, u2)
+            return R.from_matrix(np.stack([u1, u2, u3], axis=1)).as_quat()
+        if self.rot_option == RotOption.ROTVEC:
+            return R.from_rotvec(arr).as_quat()
+        return R.from_euler(self.rot_option.name, arr).as_quat()  # (x, y, z, w) order
+
+    def _convert_arm(self, action: np.ndarray) -> np.ndarray:
+        arm_rot = self._to_quat(action[3:])
+        return np.concatenate([action[:3], arm_rot])  # position + converted rotation
+
+    def convert_position(self, action: np.ndarray) -> np.ndarray:
+        action = np.asarray(action)
+        if not self.is_biarm:
+            return self._convert_arm(action)
+
+        action_dim = len(action)
+        if action_dim % 2:
+            raise ValueError(
+                f"Biarm cartesian action must have an even length to split per arm, got "
+                f"{action_dim}."
+            )
+        arm1_action = self._convert_arm(action[: action_dim // 2])
+        arm2_action = self._convert_arm(action[action_dim // 2 :])
+        return np.concatenate([arm1_action, arm2_action])

oopsie_data_tools/utils/robot_profile/template.py

@@ -0,0 +1,108 @@
+"""The starter robot profile emitted by ``oopsie-data new-profile``.
+
+Lives in Python rather than as packaged data on purpose: nothing in this toolkit
+reads configuration out of an installed package (see ``utils.paths``). The checked-in
+``configs/robot_profiles/template.yaml`` is a copy of this string kept for browsing on
+GitHub, and ``test_new_profile.py`` fails if the two drift apart.
+
+The skeleton is deliberately **not** loadable as written. Every required field is blank,
+so ``load_robot_profile`` rejects it until a human fills it in — recording an episode
+against a half-edited profile would stamp placeholder metadata into uploaded data.
+"""
+
+PROFILE_TEMPLATE = """# Any config related to the robot setup, observation, action will be stored here.
+
+
+# ===============================
+# ===== Robot Setup Related =====
+# ===============================
+
+policy_name: # str (Rq) (Example: "pi0.5", "openvla", "diffusion_policy_custom" ...)
+robot_name: # str (Required) (Example: "franka_panda", "franka_research_3", "ur5e", "yam_pro" ...)
+gripper_name: # str (Required) (Example: "robotiq_2f_85", "robotiq_2f_140", "yam_gripper" ...)
+is_biarm: # bool (Required)
+uses_mobile_base: # bool (Required)
+control_freq: # int (Required)
+camera_names: # list of str (Required) (Example: ["left", "right", "wrist"])
+  - # str
+
+
+# ===============================
+# ===== Observation Related =====
+# ===============================
+
+# Observation keys. Options: "joint_position", "gripper_position", "cartesian_position", "base_position"
+# "gripper_position" is always required.
+# Joint-space actions require "joint_position"; Cartesian actions require "cartesian_position".
+robot_state_keys: # list of str
+  - # str
+
+# If cartesian_position is in the robot_state_keys, specify the orientation representation. Options:
+# 1. "euler_{format}" (where format is "xyz", "xyx" ... (shape (3,))
+# 2. "quat" (quaternion should be scalar last, shape (4,))
+# 3. "matrix" (rotation matrix, shape (3, 3))
+# 4. "rot6d" (first two columns of the rotation matrix, flattened, shape (6,). This is used by openpi)
+# 5. "rotvec" (axis-angle, shape (3,))
+robot_state_orientation_representation: # str
+
+
+# ==========================
+# ===== Action Related =====
+# ==========================
+
+# Action space (Required)
+# Options: "joint_velocity", "joint_position", "cartesian_position", "cartesian_velocity"
+# Gripper options: "gripper_position", "gripper_velocity", "gripper_binary"
+# Base options: "base_velocity", "base_position"
+action_space: # list of str
+  - # str
+
+
+# If action space is cartesian position, specify the orientation representation. Options:
+# 1. "euler_{format}" (where format is "xyz", "xyx" ... (shape (3,))
+# 2. "quat" (quaternion should be scalar last, shape (4,))
+# 3. "matrix" (rotation matrix, shape (3, 3))
+# 4. "rot6d" (first two columns of the rotation matrix, flattened, shape (6,). This is used by openpi)
+# 5. "rotvec" (axis-angle, shape (3,))
+orientation_representation: # str
+
+
+# ==========================
+# ===== Optional Keys =====
+# ==========================
+
+# Required when "joint_position" is in robot_state_keys.
+# Identifies what each index in robot_state["joint_position"] corresponds to.
+robot_state_joint_names: # list of str
+  - # str
+
+# For knowing what each index in the action["joint_position"] corresponds to
+action_joint_names: # list of str
+  - # str
+
+
+# Options: "OSC", "joint_position", "joint_velocity"
+controller: # str
+gains:
+  joint_position:
+    kp: # list of float
+    kd: # list of float
+
+  joint_velocity:
+    kv: # list of float
+
+  osc:
+    kp_pos: # list of float
+    kd_pos: # list of float
+    kp_ori: # list of float
+    kd_ori: # list of float
+
+intrinsic_calibration_matrix:
+  <str>: # camera name str
+    - # 3 x list of three floats (camera intrinsics for left camera)
+
+extrinsic_calibration_matrix:
+  <str>: # camera name str
+    - # 4 x list of four floats (camera extrinsics in the form of a transformation matrix)
+# ========================
+"""

oopsie_data_tools/utils/validation/__init__.py

@@ -0,0 +1,5 @@
+"""Episode loading and semantic validation against the oopsiedata schema."""
+
+from oopsie_data_tools.utils.validation.errors import EpisodeValidationError
+
+__all__ = ["EpisodeValidationError"]

oopsie_data_tools/utils/validation/annotation_completeness.py

@@ -0,0 +1,67 @@
+"""One definition of when an annotation counts as *finished* for its outcome.
+
+Only ``outcome`` is required, so this module no longer speaks for the validator -- a partial
+annotation is perfectly valid to upload. What it speaks for is the annotation UI's tick,
+which still needs to distinguish "outcome recorded" from "everything this outcome asks
+about is filled in", so annotators can find episodes worth revisiting.
+
+The per-outcome field list below mirrors which fields the annotation form actually shows for
+each outcome. If one moves, the other must.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+# Mirrors the conditional fields in the annotation form. `success` is a clean run: there is
+# nothing further to say about it, so it is complete the moment it is chosen.
+OUTCOME_EXPECTED_FIELDS: dict = {
+    "success": (),
+    "success_suboptimal": ("episode_description",),
+    "success_side_effect": ("episode_description", "side_effect_category", "severity"),
+    "failure": ("episode_description", "side_effect_category", "severity"),
+}
+
+
+def _is_filled(value: Any) -> bool:
+    """A scalar field counts as filled when it has non-whitespace content."""
+    if value is None:
+        return False
+    if isinstance(value, bytes):
+        value = value.decode("utf-8", errors="replace")
+    return bool(str(value).strip())
+
+
+def _category_is_filled(value: Any) -> bool:
+    """``side_effect_category`` may arrive as a list (the form) or a scalar (older records).
+
+    Blank entries do not count, so ``[""]`` is empty. The stored form drops them on the way
+    to disk, and a list that looks filled here but not after a round-trip would make the
+    tick flip for no visible reason.
+    """
+    if isinstance(value, (list, tuple)):
+        return any(_is_filled(v) for v in value)
+    return _is_filled(value)
+
+
+def _field_is_filled(annotation: Mapping[str, Any], field: str) -> bool:
+    value = annotation.get(field)
+    if field == "side_effect_category":
+        return _category_is_filled(value)
+    return _is_filled(value)
+
+
+def completeness_flags(annotation: Mapping[str, Any]) -> dict:
+    """Per-field filled flags, restricted to the fields this outcome actually asks about.
+
+    An outcome the vocabulary does not know gets an empty mapping rather than an error: the
+    caller's job is to render a tick, not to reject data.
+    """
+    outcome = str(annotation.get("outcome", "") or "").strip().lower()
+    expected = OUTCOME_EXPECTED_FIELDS.get(outcome, ())
+    return {field: _field_is_filled(annotation, field) for field in expected}
+
+
+def is_complete(annotation: Mapping[str, Any]) -> bool:
+    """Whether every field this outcome asks about is filled (trivially true for ``success``)."""
+    return all(completeness_flags(annotation).values())

oopsie_data_tools/utils/validation/diversity.py

@@ -0,0 +1,93 @@
+"""Lightweight, attribute-only diversity heuristics for a dataset (issue #40).
+
+Warns (never blocks by default) when a dataset shows very low task or annotation
+diversity — a nudge to catch copy-pasted annotations or an inattentive annotator.
+Reads only HDF5 attrs (never opens videos or decodes arrays) so it is cheap to run
+over a whole session directory, and it never raises.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import Counter
+from typing import Any
+
+import h5py
+
+from oopsie_data_tools.annotation_tool.annotation_schema import read_annotation_attrs
+from oopsie_data_tools.utils.h5 import find_episode_files
+
+logger = logging.getLogger(__name__)
+
+# Below this many episodes the ratios are too noisy to be meaningful.
+MIN_EPISODES_FOR_CHECK = 5
+# A single description accounting for more than this fraction looks copy-pasted.
+DUP_DESCRIPTION_FRACTION = 0.8
+
+
+def check_diversity(samples_dir: str) -> list[str]:
+    """Return (and WARN-log) low-diversity messages for a session directory.
+
+    Args:
+        samples_dir: Directory containing ``*.h5`` / ``*.hdf5`` episodes.
+
+    Returns:
+        A list of human-readable warning strings (empty if nothing notable).
+    """
+    files = find_episode_files(samples_dir)
+    if len(files) < MIN_EPISODES_FOR_CHECK:
+        return []
+
+    instructions: list[str] = []
+    descriptions: list[str] = []
+    for path in files:
+        try:
+            with h5py.File(path, "r") as f:
+                instructions.append(_attr_str(f, "language_instruction"))
+                ea = f.get("episode_annotations")
+                if isinstance(ea, h5py.Group):
+                    for name in ea.keys():
+                        sub = ea[name]
+                        if not isinstance(sub, h5py.Group):
+                            continue
+                        # read_annotation_attrs so v1 (failure_description) and v2
+                        # (episode_description) files both feed the copy-paste check.
+                        desc = str(
+                            read_annotation_attrs(sub.attrs).get("episode_description", "")
+                        ).lower()
+                        if desc:
+                            descriptions.append(desc)
+        except Exception:
+            continue
+
+    warnings: list[str] = []
+    n = len(instructions)
+    distinct_instructions = len({i for i in instructions if i})
+    if n >= MIN_EPISODES_FOR_CHECK and distinct_instructions <= 1:
+        warnings.append(
+            f"Low task diversity: all {n} episodes share a single language_instruction."
+        )
+    elif n >= 10 and distinct_instructions / n < 0.1:
+        warnings.append(
+            f"Low task diversity: only {distinct_instructions} distinct instruction(s) "
+            f"across {n} episodes."
+        )
+
+    if len(descriptions) >= MIN_EPISODES_FOR_CHECK:
+        top_desc, top_n = Counter(descriptions).most_common(1)[0]
+        if top_n / len(descriptions) > DUP_DESCRIPTION_FRACTION:
+            warnings.append(
+                f"Possible copied annotations: {top_n}/{len(descriptions)} episode "
+                f'descriptions are identical ("{top_desc[:60]}...").'
+            )
+
+    for w in warnings:
+        logger.warning("[diversity] %s", w)
+    return warnings
+
+
+def _attr_str(group: h5py.Group | h5py.File, key: str) -> str:
+    value: Any = group.attrs.get(key, "")
+    if isinstance(value, bytes):
+        value = value.decode("utf-8", errors="replace")
+    return str(value).strip()

oopsie_data_tools/utils/validation/episode_data.py

@@ -0,0 +1,54 @@
+"""Schema-agnostic episode representation used by loader and validator."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import numpy as np
+
+from oopsie_data_tools.utils.robot_profile.robot_profile import RobotProfile
+
+
+@dataclass
+class VideoInfo:
+    """Camera video metadata, constructable from an MP4 file or in-memory frames."""
+
+    frame_count: int
+    fps: float
+    width: int
+    height: int
+
+    @classmethod
+    def from_frames(cls, frames: list[np.ndarray], fps: float) -> VideoInfo:
+        """Build VideoInfo from in-memory frame buffers (recorder pre-save path)."""
+        if not frames:
+            raise ValueError("Cannot build VideoInfo from empty frame list")
+        h, w = frames[0].shape[:2]
+        return cls(frame_count=len(frames), fps=fps, width=w, height=h)
+
+
+@dataclass
+class EpisodeData:
+    """Normalized episode data, independent of source schema.
+
+    Populated by episode_loader (from HDF5) or constructed directly by the
+    recorder for pre-save validation. Both always supply a robot profile:
+    episode_loader rejects any schema that does not embed one.
+    """
+
+    robot_profile: RobotProfile
+    language_instruction: str
+    episode_id: str
+    lab_id: str
+    operator_name: str
+    trajectory_length: int
+    control_freq: float
+    # Eagerly-loaded arrays; shape (T, ...) for each key.
+    observations: dict[str, np.ndarray]
+    # Only non-empty action datasets; shape (T, ...) for each key.
+    actions: dict[str, np.ndarray]
+    # Per-camera metadata.
+    videos: dict[str, VideoInfo]
+    # Optional: annotator_name → {attr_key: attr_val}.
+    annotations: Optional[dict[str, dict[str, Any]]] = field(default=None)

oopsie_data_tools/utils/validation/episode_loader.py

@@ -0,0 +1,201 @@
+"""Load episode HDF5 files into the schema-agnostic EpisodeData representation.
+
+This module owns all file I/O:
+  - HDF5 readability checks
+  - Schema detection
+  - Video file existence and MP4 metadata extraction
+
+It does NOT perform semantic validation — that is episode_validator's job.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import cv2
+import h5py
+import numpy as np
+
+from oopsie_data_tools.utils.h5 import decode_h5_scalar
+from oopsie_data_tools.utils.robot_profile.robot_profile import robot_profile_from_json
+from oopsie_data_tools.utils.validation.episode_data import EpisodeData, VideoInfo
+from oopsie_data_tools.utils.validation.errors import EpisodeValidationError
+
+OOPSIE_DATA_SCHEMA_V1 = "oopsiedata_format_v1"
+
+_OOPSIE_V1_REQUIRED_ROOT_ATTRS = (
+    "schema",
+    "episode_id",
+    "language_instruction",
+    "lab_id",
+    "operator_name",
+    "robot_profile",
+)
+
+
+# ── HDF5 scalar helpers ────────────────────────────────────────────────────────
+
+
+def _read_string_dataset(ds: h5py.Dataset) -> str:
+    return decode_h5_scalar(ds[()]).strip()
+
+
+# ── Video loading ──────────────────────────────────────────────────────────────
+
+
+def load_video_info(mp4_path: str) -> VideoInfo:
+    """Open an MP4 and extract frame metadata. Raises EpisodeValidationError on any failure."""
+    if not os.path.exists(mp4_path):
+        raise EpisodeValidationError(f"Video file does not exist: {mp4_path}")
+    if not os.path.isfile(mp4_path):
+        raise EpisodeValidationError(f"Video path is not a file: {mp4_path}")
+
+    cap = cv2.VideoCapture(mp4_path)
+    try:
+        if not cap.isOpened():
+            raise EpisodeValidationError(f"Could not open video: {mp4_path}")
+        width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        fps = cap.get(cv2.CAP_PROP_FPS)
+        frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+        if not (width > 0 and height > 0):
+            raise EpisodeValidationError(f"Invalid dimensions ({width}x{height}): {mp4_path}")
+        if not (fps > 0):
+            raise EpisodeValidationError(f"Invalid FPS ({fps}): {mp4_path}")
+        if not (frame_count > 0):
+            raise EpisodeValidationError(f"Invalid frame count ({frame_count}): {mp4_path}")
+        return VideoInfo(frame_count=frame_count, fps=fps, width=width, height=height)
+    finally:
+        cap.release()
+
+
+def _resolve_video_path(rel: str, h5_dir: str, label: str) -> str:
+    if not rel:
+        raise EpisodeValidationError(f"Empty video path for {label}")
+    return os.path.normpath(os.path.join(h5_dir, rel))
+
+
+# ── Schema-specific loaders ────────────────────────────────────────────────────
+
+
+def _load_oopsie_v1(f: h5py.File, h5_dir: str) -> EpisodeData:
+    for attr in _OOPSIE_V1_REQUIRED_ROOT_ATTRS:
+        if attr not in f.attrs:
+            raise EpisodeValidationError(f"Missing root attr: {attr}")
+
+    try:
+        profile = robot_profile_from_json(decode_h5_scalar(f.attrs["robot_profile"]))
+    except ValueError as e:
+        raise EpisodeValidationError(f"Invalid robot_profile JSON: {e}") from e
+
+    if "observations" not in f:
+        raise EpisodeValidationError("Missing group: observations")
+    if "robot_states" not in f["observations"]:
+        raise EpisodeValidationError("Missing group: observations/robot_states")
+    if "actions" not in f:
+        raise EpisodeValidationError("Missing group: actions")
+
+    rs = f["observations/robot_states"]
+    for key in profile.robot_state_keys:
+        if key not in rs:
+            raise EpisodeValidationError(f"Missing observations/robot_states/{key}")
+    observations = {k: rs[k][()] for k in rs.keys()}
+
+    action_group = f["actions"]
+    for key in profile.action_space:
+        if key not in action_group:
+            raise EpisodeValidationError(f"Missing actions/{key}")
+        ds = action_group[key]
+        if ds.shape is None:
+            raise EpisodeValidationError(
+                f"actions/{key} is in profile.action_space but stored as h5py.Empty"
+            )
+    # Load only non-empty action datasets.
+    actions: dict[str, np.ndarray] = {
+        k: action_group[k][()] for k in action_group.keys() if action_group[k].shape is not None
+    }
+
+    if "video_paths" not in f["observations"]:
+        raise EpisodeValidationError("Missing group: observations/video_paths")
+    vp_group = f["observations/video_paths"]
+    for cam in profile.camera_names:
+        if cam not in vp_group:
+            raise EpisodeValidationError(f"Missing observations/video_paths/{cam}")
+    videos: dict[str, VideoInfo] = {}
+    for cam in vp_group.keys():
+        rel = _read_string_dataset(vp_group[cam])
+        abs_path = _resolve_video_path(rel, h5_dir, f"camera {cam}")
+        videos[cam] = load_video_info(abs_path)
+
+    annotations = _load_annotations_oopsie_v1(f)
+
+    trajectory_length = next(iter(observations.values())).shape[0]
+
+    return EpisodeData(
+        robot_profile=profile,
+        language_instruction=decode_h5_scalar(f.attrs["language_instruction"]),
+        episode_id=decode_h5_scalar(f.attrs["episode_id"]),
+        lab_id=decode_h5_scalar(f.attrs["lab_id"]),
+        operator_name=decode_h5_scalar(f.attrs["operator_name"]),
+        trajectory_length=trajectory_length,
+        control_freq=float(profile.control_freq),
+        observations=observations,
+        actions=actions,
+        videos=videos,
+        annotations=annotations,
+    )
+
+
+def _load_annotations_oopsie_v1(f: h5py.File) -> dict[str, dict[str, Any]] | None:
+    if "episode_annotations" not in f:
+        return None
+    ea = f["episode_annotations"]
+    # Everything in this layer reports failure as EpisodeValidationError. A file storing
+    # episode_annotations as a dataset used to reach .keys() and raise AttributeError,
+    # which escapes that contract and surfaces as an "unexpected error" with no
+    # indication of what is actually wrong with the file.
+    if not isinstance(ea, h5py.Group):
+        raise EpisodeValidationError(
+            "episode_annotations must be a group of per-annotator subgroups, got "
+            f"{type(ea).__name__}"
+        )
+    annotations: dict[str, dict[str, Any]] = {}
+    for annotator in ea.keys():
+        subgroup = ea[annotator]
+        if not isinstance(subgroup, h5py.Group):
+            raise EpisodeValidationError(
+                f"episode_annotations/{annotator} must be a group, got {type(subgroup).__name__}"
+            )
+        annotations[annotator] = {k: subgroup.attrs[k] for k in subgroup.attrs}
+    return annotations
+
+
+def load_episode_from_h5(h5_path: str) -> EpisodeData:
+    """Load an episode HDF5 file into a schema-agnostic EpisodeData.
+
+    Raises EpisodeValidationError with a descriptive message if the file is unreadable,
+    structurally invalid, or references missing/corrupt video files.
+    """
+    resolved = os.path.abspath(os.path.normpath(h5_path))
+    if not os.path.exists(resolved):
+        raise EpisodeValidationError(f"H5 file does not exist: {resolved}")
+    if not os.path.isfile(resolved):
+        raise EpisodeValidationError(f"H5 path is not a file: {resolved}")
+
+    try:
+        f = h5py.File(resolved, "r")
+    except Exception as e:
+        raise EpisodeValidationError(f"H5 file is not readable: {resolved}. Error: {e}") from e
+
+    h5_dir = os.path.dirname(resolved)
+    try:
+        schema = decode_h5_scalar(f.attrs.get("schema", ""))
+        if schema == OOPSIE_DATA_SCHEMA_V1:
+            return _load_oopsie_v1(f, h5_dir)
+        else:
+            raise EpisodeValidationError(
+                f"Unsupported or missing schema: '{schema}' in file: {resolved}"
+            )
+    finally:
+        f.close()