datahive-tools 0.1.0__tar.gz

datahive_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HiveBoard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

datahive_tools-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: datahive-tools
+Version: 0.1.0
+Summary: Client tooling to collect, validate, annotate and upload HiveBoard manipulation episodes.
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: huggingface_hub>=0.24
+Requires-Dist: h5py>=3.10
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn>=0.29
+Requires-Dist: typer>=0.12
+Requires-Dist: python-multipart>=0.0.9
+Provides-Extra: video
+Requires-Dist: opencv-python-headless>=4.8; extra == "video"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: opencv-python-headless>=4.8; extra == "dev"
+Dynamic: license-file
+
+# DataHive
+
+`datahive-tools`: the client-side package a lab installs to collect,
+validate, annotate, and upload HiveBoard manipulation episodes to its
+private Hugging Face dataset repo.
+
+> [!IMPORTANT]
+> **Credits & Attribution**: All pipeline architecture, workflows, and core design in DataHive are directly adapted from and credited to [**Oopsie Data**](https://github.com/oopsie-data) (`oopsie-data` / `oopsie_data_tools`). Everything in DataHive — from the CLI workflow, robot profiles, and dataset indexing to the annotation GUI and Hugging Face Hub synchronization pipeline — was built upon the pipeline and concepts developed by the Oopsie Data team.
+
+## Install
+
+```
+pip install -e .
+```
+
+## Quickstart
+
+```
+datahive init                 # one-time: writes ~/.datahive/config.yaml (0600)
+datahive new-profile          # writes samples/robot_profile.yaml -- fill in ONCE
+# ... record episodes into samples/{session}/episodes/{episode}.h5 + .mp4 ...
+datahive check <episode_id>   # pre-annotation health check (frames, Hz, MP4s)
+datahive annotate <episode_id>
+datahive validate <episode_id>
+datahive upload <episode_id>
+datahive sync                 # reconcile all of samples/ with the Hub
+datahive list
+datahive delete <episode_id>
+datahive interface --port 8000 # local web GUI, localhost only (alias: serve)
+```
+
+See `docs/MANUAL_SMOKE_TEST.md` for the manual (non-automated) end-to-end
+check against a real, disposable Hugging Face repo.
+
+## The sections of `datahive serve`
+
+Opening the interface shows a start screen with two sections, plus an About and FAQ area. Both sections share the same `samples/` tree.
+
+- **Runner** – runs HiveBoard trials. Create a session (operator and date; the lab ID comes from `datahive init` and the platform ID from the robot profile), generate the trial plan (5 trials for each chosen task, shuffled or ordered), then run each trial in one of two modes, switchable at any time:
+  - **Manual**: 5 s countdown, stopwatch, sounds and automatic timeout in the browser (Space starts and stops), then record the outcome and **upload the HDF5 file and one video per camera in the robot profile**. The trial counts as valid only when all of them are uploaded and the episode passes validation.
+  - **Automatic**: send the trial to your robot script (below). It records the episode, and you annotate it in the Annotate section, which opens on that episode.
+- **Annotate** – review recorded episodes, annotate them, validate the data, and upload it to the Hub.
+
+Robot side of automatic mode:
+
+```python
+from datahive.collect import CollectClient
+
+robot = CollectClient("samples", base_url="http://127.0.0.1:8000")
+while True:
+    task = robot.wait_for_task()             # blocks until you press "Send to robot"
+    with robot.new_writer(task) as writer:   # EpisodeWriter for that trial
+        ...                                  # append_proprioception / append_command / attach_video
+    robot.finish(writer)                     # hands the episode over, waits for the annotation
+```
+
+Trials are saved as rows of `samples/<session>/trials.csv`; all times are stored in UTC.
+
+## AI assistant skills
+
+Two skills for AI coding assistants (e.g. Claude Code) live in `src/datahive/skills/`:
+
+- `datahive-data-prep` – how to lay out, format, annotate and check data under `samples/` so it validates.
+- `datahive-auto-collect` – how automatic collection works and how to adapt the robot script to your setup.
+
+Install them for Claude Code with:
+
+```
+datahive install-skill          # into ./.claude/skills (this project)
+datahive install-skill --user   # into ~/.claude/skills (all projects)
+datahive install-skill --dir DIR --force
+```
+
+## Tests
+
+```
+pip install -e ".[dev]"
+pytest
+```
+
+All tests run with no real network access and no real Hugging Face
+credentials.
+
+## Credits & Acknowledgments
+
+All credit for the underlying pipeline architecture goes to the **Oopsie Data** (`oopsie-data` / `oopsie_data_tools`) project. DataHive was built on top of their pipeline patterns, including:
+
+- **Interactive Annotation & GUI**: The web-based annotator interface, video playback controls, task picker, episode navigation, and failure classification.
+- **Data Lifecycle**: The full `init` -> `new-profile` -> `annotate` -> `validate` -> `upload` -> `sync` pipeline.
+- **Dataset Structure & Profiling**: Hardware platform specification snapshots, HDF5 episode storage, and Hub reconciliation.
+
+We are deeply grateful to the Oopsie Data contributors for their pioneering work in robotic data pipelines.

datahive_tools-0.1.0/README.md

@@ -0,0 +1,92 @@
+# DataHive
+
+`datahive-tools`: the client-side package a lab installs to collect,
+validate, annotate, and upload HiveBoard manipulation episodes to its
+private Hugging Face dataset repo.
+
+> [!IMPORTANT]
+> **Credits & Attribution**: All pipeline architecture, workflows, and core design in DataHive are directly adapted from and credited to [**Oopsie Data**](https://github.com/oopsie-data) (`oopsie-data` / `oopsie_data_tools`). Everything in DataHive — from the CLI workflow, robot profiles, and dataset indexing to the annotation GUI and Hugging Face Hub synchronization pipeline — was built upon the pipeline and concepts developed by the Oopsie Data team.
+
+## Install
+
+```
+pip install -e .
+```
+
+## Quickstart
+
+```
+datahive init                 # one-time: writes ~/.datahive/config.yaml (0600)
+datahive new-profile          # writes samples/robot_profile.yaml -- fill in ONCE
+# ... record episodes into samples/{session}/episodes/{episode}.h5 + .mp4 ...
+datahive check <episode_id>   # pre-annotation health check (frames, Hz, MP4s)
+datahive annotate <episode_id>
+datahive validate <episode_id>
+datahive upload <episode_id>
+datahive sync                 # reconcile all of samples/ with the Hub
+datahive list
+datahive delete <episode_id>
+datahive interface --port 8000 # local web GUI, localhost only (alias: serve)
+```
+
+See `docs/MANUAL_SMOKE_TEST.md` for the manual (non-automated) end-to-end
+check against a real, disposable Hugging Face repo.
+
+## The sections of `datahive serve`
+
+Opening the interface shows a start screen with two sections, plus an About and FAQ area. Both sections share the same `samples/` tree.
+
+- **Runner** – runs HiveBoard trials. Create a session (operator and date; the lab ID comes from `datahive init` and the platform ID from the robot profile), generate the trial plan (5 trials for each chosen task, shuffled or ordered), then run each trial in one of two modes, switchable at any time:
+  - **Manual**: 5 s countdown, stopwatch, sounds and automatic timeout in the browser (Space starts and stops), then record the outcome and **upload the HDF5 file and one video per camera in the robot profile**. The trial counts as valid only when all of them are uploaded and the episode passes validation.
+  - **Automatic**: send the trial to your robot script (below). It records the episode, and you annotate it in the Annotate section, which opens on that episode.
+- **Annotate** – review recorded episodes, annotate them, validate the data, and upload it to the Hub.
+
+Robot side of automatic mode:
+
+```python
+from datahive.collect import CollectClient
+
+robot = CollectClient("samples", base_url="http://127.0.0.1:8000")
+while True:
+    task = robot.wait_for_task()             # blocks until you press "Send to robot"
+    with robot.new_writer(task) as writer:   # EpisodeWriter for that trial
+        ...                                  # append_proprioception / append_command / attach_video
+    robot.finish(writer)                     # hands the episode over, waits for the annotation
+```
+
+Trials are saved as rows of `samples/<session>/trials.csv`; all times are stored in UTC.
+
+## AI assistant skills
+
+Two skills for AI coding assistants (e.g. Claude Code) live in `src/datahive/skills/`:
+
+- `datahive-data-prep` – how to lay out, format, annotate and check data under `samples/` so it validates.
+- `datahive-auto-collect` – how automatic collection works and how to adapt the robot script to your setup.
+
+Install them for Claude Code with:
+
+```
+datahive install-skill          # into ./.claude/skills (this project)
+datahive install-skill --user   # into ~/.claude/skills (all projects)
+datahive install-skill --dir DIR --force
+```
+
+## Tests
+
+```
+pip install -e ".[dev]"
+pytest
+```
+
+All tests run with no real network access and no real Hugging Face
+credentials.
+
+## Credits & Acknowledgments
+
+All credit for the underlying pipeline architecture goes to the **Oopsie Data** (`oopsie-data` / `oopsie_data_tools`) project. DataHive was built on top of their pipeline patterns, including:
+
+- **Interactive Annotation & GUI**: The web-based annotator interface, video playback controls, task picker, episode navigation, and failure classification.
+- **Data Lifecycle**: The full `init` -> `new-profile` -> `annotate` -> `validate` -> `upload` -> `sync` pipeline.
+- **Dataset Structure & Profiling**: Hardware platform specification snapshots, HDF5 episode storage, and Hub reconciliation.
+
+We are deeply grateful to the Oopsie Data contributors for their pioneering work in robotic data pipelines.

datahive_tools-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "datahive-tools"
+version = "0.1.0"
+description = "Client tooling to collect, validate, annotate and upload HiveBoard manipulation episodes."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    "huggingface_hub>=0.24",
+    "h5py>=3.10",
+    "pydantic>=2.6",
+    "pyyaml>=6.0",
+    "numpy>=1.24",
+    "fastapi>=0.110",
+    "uvicorn>=0.29",
+    "typer>=0.12",
+    "python-multipart>=0.0.9",
+]
+
+[project.optional-dependencies]
+video = ["opencv-python-headless>=4.8"]
+dev = ["pytest>=8.0", "httpx>=0.27", "opencv-python-headless>=4.8"]
+
+[project.scripts]
+datahive = "datahive.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"datahive" = ["attachments.yaml", "interface/static/*", "interface/static/tasks/*", "skills/*/SKILL.md", "skills/*/reference/*.md"]

datahive_tools-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

datahive_tools-0.1.0/src/datahive/__init__.py

@@ -0,0 +1,31 @@
+"""datahive-tools: client package for collecting, validating, annotating and
+uploading HiveBoard manipulation episodes.
+
+Public library API (also used internally by the CLI and the local GUI, so
+all three surfaces stay in sync):
+
+    from datahive import EpisodeWriter, RobotProfile, TrialAnnotation
+"""
+
+from datahive.episode import EpisodeWriter, read_header, read_trajectory, resolve_episode
+from datahive.errors import DatahiveError
+from datahive.profile import RobotProfile, load_profile, write_profile_skeleton
+from datahive.schema import EpisodeHeader, FailureCause, Outcome, Strategy, TrialAnnotation
+
+__all__ = [
+    "EpisodeWriter",
+    "read_header",
+    "read_trajectory",
+    "resolve_episode",
+    "DatahiveError",
+    "RobotProfile",
+    "load_profile",
+    "write_profile_skeleton",
+    "EpisodeHeader",
+    "FailureCause",
+    "Outcome",
+    "Strategy",
+    "TrialAnnotation",
+]
+
+__version__ = "0.1.0"

datahive_tools-0.1.0/src/datahive/annotate.py

@@ -0,0 +1,123 @@
+"""`datahive annotate`: fills outcome/failure_cause/etc. for an episode's
+trial, shared by the CLI's interactive prompts and the GUI's validation
+form (both end up calling `annotate_episode`)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from datahive.attachments import is_composed_assembly
+from datahive.episode import read_header
+from datahive.errors import AnnotationError
+from datahive.paths import resolve_episode_paths
+from datahive.schema import ANNOTATION_SCHEMA_CURRENT, TrialAnnotation
+from datahive.trials import upsert_row
+
+
+def annotate_episode(
+    samples_root: Path, episode_id: str, fields: dict[str, Any], *, validate_after: bool = True
+) -> TrialAnnotation:
+    """`fields` is a dict of TrialAnnotation column values (trial_id/lab_id/
+    platform_id/attachment_id/date are filled in automatically from the
+    episode header + config when omitted). Writes the row to trials.csv and,
+    by default, runs full validation afterward so the index status reflects
+    whether the episode is now `validated`."""
+    paths = resolve_episode_paths(samples_root, episode_id)
+    header = read_header(paths.h5)
+
+    data = dict(fields)
+    data.setdefault("trial_id", header.trial_id)
+    data.setdefault("lab_id", header.lab_id)
+    data.setdefault("platform_id", header.platform_id)
+    if "date" not in data or data["date"] is None:
+        from datetime import datetime, timezone
+
+        data["date"] = datetime.now(timezone.utc).date().isoformat()
+    for name_field in ("operator_name", "annotator_name", "failure_cause_detail"):
+        if data.get(name_field) is None:
+            data[name_field] = ""
+
+    if data.get("outcome") == "success" and data.get("completion_time_s") is None:
+        from datahive.episode import episode_stats
+
+        duration = episode_stats(paths.h5).get("duration_s")
+        if duration is not None:
+            data["completion_time_s"] = round(duration, 3)
+            data.setdefault("completion_source", "hdf5")
+
+    from datetime import datetime, timezone
+
+    data["annotated_at"] = datetime.now(timezone.utc).isoformat()
+    data["schema_version"] = ANNOTATION_SCHEMA_CURRENT
+
+    attachment_id = data.get("attachment_id")
+    composed = is_composed_assembly(attachment_id or "", samples_root)
+    context = {} if composed is None else {"composed_assembly": composed}
+
+    try:
+        annotation = TrialAnnotation.model_validate(data, context=context)
+    except Exception as e:
+        raise AnnotationError(f"Invalid annotation: {e}") from e
+
+    upsert_row(paths.trials_csv, annotation)
+    write_h5_annotation(paths.h5, annotation)
+
+    if validate_after:
+        from datahive.validate import validate_episode
+
+        try:
+            validate_episode(samples_root, episode_id)
+        except Exception:
+            pass  
+        
+    return annotation
+
+
+def _annotator_key(name: str) -> str:
+    return (name or "unknown").strip().replace("/", "_") or "unknown"
+
+
+def write_h5_annotation(h5_path: Path, annotation: TrialAnnotation) -> None:
+    """Stores the annotation inside the episode as
+    episode_annotations/<annotator>/ (attrs), stamped with schema_version, so
+    the file stays self-describing if trials.csv is lost or the episode moved."""
+    import json
+
+    import h5py
+
+    row = annotation.to_csv_row()
+    key = _annotator_key(annotation.annotator_name)
+    with h5py.File(h5_path, "r+") as f:
+        root = f.require_group("episode_annotations")
+        if key in root:
+            del root[key]
+        grp = root.create_group(key)
+        grp.attrs["schema_version"] = annotation.schema_version
+        grp.attrs["source"] = "human"
+        grp.attrs["timestamp"] = row["annotated_at"]
+        grp.attrs["annotation"] = json.dumps(row, sort_keys=True)
+
+
+def read_h5_annotations(h5_path: Path) -> dict[str, dict]:
+    """{annotator: row-dict} from the episode file. Groups without a
+    schema_version are upcast to the legacy version; nothing is rewritten."""
+    import json
+
+    import h5py
+
+    from datahive.schema import ANNOTATION_SCHEMA_LEGACY
+
+    out: dict[str, dict] = {}
+    with h5py.File(h5_path, "r") as f:
+        root = f.get("episode_annotations")
+        if root is None:
+            return out
+        for name, grp in root.items():
+            try:
+                row = json.loads(grp.attrs.get("annotation", "{}"))
+            except (TypeError, ValueError):
+                row = {}
+            row["schema_version"] = grp.attrs.get("schema_version") or row.get("schema_version") or ANNOTATION_SCHEMA_LEGACY
+            out[name] = row
+    return out

datahive_tools-0.1.0/src/datahive/attachments.py

@@ -0,0 +1,71 @@
+"""Attachment registry: which attachment_ids are "composed-assembly"
+(multi-stage) attachments, for which stage_reached is meaningful.
+
+Bundled defaults live in datahive/attachments.yaml; a lab can add or
+override entries with samples/attachments.yaml.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+
+import yaml
+
+from datahive.paths import attachments_override_path
+
+_BUNDLED_PATH = Path(__file__).parent / "attachments.yaml"
+
+
+@dataclass
+class AttachmentInfo:
+    attachment_id: str
+    name: str
+    composed_assembly: bool
+    n_stages: int | None = None
+    family: str | None = None
+    timeout: int | None = None
+    success: str | None = None
+    reset: str | None = None
+    stages: list[str] | None = None
+    image: str | None = None
+
+
+@lru_cache(maxsize=1)
+def _bundled() -> dict:
+    return yaml.safe_load(_BUNDLED_PATH.read_text(encoding="utf-8")) or {}
+
+
+def load_registry(samples_root: Path | None = None) -> dict[str, AttachmentInfo]:
+    raw: dict = dict(_bundled())
+    if samples_root is not None:
+        override_path = attachments_override_path(samples_root)
+        if override_path.is_file():
+            override = yaml.safe_load(override_path.read_text(encoding="utf-8")) or {}
+            raw.update(override)
+    return {
+        aid: AttachmentInfo(
+            attachment_id=aid,
+            name=info.get("name", aid),
+            composed_assembly=bool(info.get("composed_assembly", False)),
+            n_stages=info.get("n_stages"),
+            family=info.get("family"),
+            timeout=info.get("timeout"),
+            success=info.get("success"),
+            reset=info.get("reset"),
+            stages=info.get("stages"),
+            image=info.get("image"),
+        )
+        for aid, info in raw.items()
+    }
+
+
+def is_composed_assembly(attachment_id: str, samples_root: Path | None = None) -> bool | None:
+    """Returns True/False if the attachment is known, or None if unknown
+    (caller should treat this as 'no constraint, but warn')."""
+    registry = load_registry(samples_root)
+    info = registry.get(attachment_id)
+    if info is None:
+        return None
+    return info.composed_assembly

datahive_tools-0.1.0/src/datahive/attachments.yaml

@@ -0,0 +1,124 @@
+# Bundled HiveBoard attachment (task) registry.
+#
+# This mirrors the 13 official HiveBoard evaluation conditions from
+# HiveBoard's Evaluation Runner
+# (https://hiveboard-bench.github.io/hivedocs/benchmark/evaluation-runner),
+# so `attachment_id` here means the same thing as `attachment_id` in a
+# HiveBoard submission. `composed_assembly: true` marks attachments made
+# of multiple stages that must be completed in sequence (stage_reached is
+# meaningful for these and required in the trial annotation).
+#
+# Labs can override/extend this list by placing an attachments.yaml with
+# the same shape at the root of their samples/ directory.
+valve_ball:
+  name: Ball valve
+  family: Torque
+  timeout: 60
+  composed_assembly: false
+  success: Rotate the handle 90° from the closed state to the open state.
+  reset: Return the handle to the closed position and confirm that the attachment is fully seated.
+  image: torque_valve_noFriction_3d.png
+valve_ball_ring:
+  name: Ball valve with friction ring
+  family: Torque
+  timeout: 90
+  composed_assembly: false
+  success: Rotate the handle 90° from closed to open with the friction ring fitted.
+  reset: Fit the friction ring, return the handle to closed, and confirm that the attachment is seated.
+  image: torque_valve_noFriction_3d.png
+valve_gate_small:
+  name: Small gate valve
+  family: Torque
+  timeout: 90
+  composed_assembly: false
+  success: Complete one full turn of the valve stem.
+  reset: Return the stem to the marked initial orientation without changing the board position.
+  image: small_valve_3d.png
+valve_gate_large:
+  name: Large gate valve
+  family: Torque
+  timeout: 120
+  composed_assembly: false
+  success: Complete one full turn of the valve stem.
+  reset: Return the stem to the marked initial orientation without changing the board position.
+  image: big_valve_3d.png
+circuit_breaker:
+  name: Circuit breaker
+  family: Torque
+  timeout: 60
+  composed_assembly: false
+  success: Move the toggle to the opposite state and hold it there.
+  reset: Return the toggle to its initial state and confirm that it moves freely.
+  image: switch_3d.png
+light_bulb:
+  name: Light bulb and socket
+  family: Precision
+  timeout: 120
+  composed_assembly: false
+  success: Thread the bulb into the socket until it is seated.
+  reset: Remove the bulb, restore the documented starting pose, and inspect the thread.
+  image: lamp_3d.png
+thread_m8:
+  name: M8 threaded fastener
+  family: Precision
+  timeout: 120
+  composed_assembly: false
+  success: Thread the bolt along the available length.
+  reset: Return the bolt to the documented initial engagement and check that the thread is clear.
+  image: m8_3d.png
+thread_m30:
+  name: M30 threaded fastener
+  family: Precision
+  timeout: 120
+  composed_assembly: false
+  success: Thread the bolt along the available length.
+  reset: Return the bolt to the documented initial engagement and check that the thread is clear.
+  image: m30_3d.png
+peg_insertion:
+  name: Threaded peg insertion
+  family: Precision
+  timeout: 120
+  composed_assembly: false
+  success: Thread the free 8 mm peg into the empty socket until it is seated.
+  reset: Remove the peg and return it to the initial pose next to the empty socket.
+  image: peg_and_hole_3d.png
+button:
+  name: Covered button
+  family: Composed assembly
+  timeout: 60
+  composed_assembly: true
+  n_stages: 2
+  stages: [Open cover, Press button]
+  success: Open the cover and press the button.
+  reset: Close the cover and confirm that the button has returned.
+  image: button_3d.png
+lock:
+  name: Lock and key
+  family: Composed assembly
+  timeout: 180
+  composed_assembly: true
+  n_stages: 3
+  stages: [Grasp key, Insert key vertically, Rotate to unlock]
+  success: Grasp the key, insert it vertically, and rotate it to unlock.
+  reset: Remove the key, return the lock to its initial state, and restore the key pose.
+  image: key_3d.png
+drawer:
+  name: Sliding drawer
+  family: Composed assembly
+  timeout: 120
+  composed_assembly: true
+  n_stages: 3
+  stages: [Grasp handle, Pull open, Push closed]
+  success: Grasp the handle, pull the drawer open, and push it closed.
+  reset: Return the drawer to the fully closed initial position.
+  image: box_3d.png
+shock_absorber:
+  name: Shock absorber
+  family: Composed assembly
+  timeout: 180
+  composed_assembly: true
+  n_stages: 3
+  stages: [Grasp pin, Align with hole, Insert fully]
+  success: Grasp the pin, align it with the hole, and insert it fully.
+  reset: Remove the pin, restore its starting pose, and check both occupied board cells.
+  image: spring_3d.png