petkopetkov commited on
Commit
01171b7
·
verified ·
1 Parent(s): 4b7925f

LADDER RoboLab-Long for LeRobot EnvHub (LADDER v1.0.0)

Browse files
This view is limited to 50 files because it contains too many changes.   See raw diff
Files changed (50) hide show
  1. .gitignore +2 -0
  2. LICENSE +21 -0
  3. README.md +76 -0
  4. _ladder_envhub.py +493 -0
  5. env.py +273 -0
  6. ladder/components/inference/api/core/action.py +228 -0
  7. ladder/components/inference/api/core/instructions.py +100 -0
  8. ladder/components/inference/api/core/observation.py +166 -0
  9. ladder/components/inference/api/core/privileged_geometry.py +218 -0
  10. ladder/components/inference/api/core/privileged_state.py +192 -0
  11. ladder/components/inference/api/core/request_reply.py +262 -0
  12. ladder/components/inference/api/core/requests.py +21 -0
  13. ladder/components/inference/api/core/serialization.py +15 -0
  14. ladder/components/inference/robots/robolab/README.md +167 -0
  15. ladder/components/inference/robots/robolab/composition/README.md +146 -0
  16. ladder/components/inference/robots/robolab/composition/catalog.py +113 -0
  17. ladder/components/inference/robots/robolab/composition/check_scene_rendered.py +145 -0
  18. ladder/components/inference/robots/robolab/composition/decomp_cache.json +500 -0
  19. ladder/components/inference/robots/robolab/composition/entities.py +41 -0
  20. ladder/components/inference/robots/robolab/composition/export_scenes.py +194 -0
  21. ladder/components/inference/robots/robolab/composition/factory.py +378 -0
  22. ladder/components/inference/robots/robolab/composition/layout.py +182 -0
  23. ladder/components/inference/robots/robolab/composition/specs.py +656 -0
  24. ladder/components/inference/robots/robolab/composition/tasks.py +9 -0
  25. ladder/components/inference/robots/robolab/droid_conversions.py +161 -0
  26. ladder/components/inference/robots/robolab/env_server.py +553 -0
  27. ladder/components/inference/robots/robolab/export_robolab_results.py +56 -0
  28. ladder/components/inference/robots/robolab/franka_kinematics.py +72 -0
  29. ladder/components/inference/robots/robolab/oracle.py +145 -0
  30. ladder/components/inference/robots/robolab/privileged.py +151 -0
  31. ladder/components/urdf/robots/panda/robot.urdf +440 -0
  32. ladder/core/common/logger/__init__.py +13 -0
  33. ladder/core/common/logger/colorize.py +27 -0
  34. ladder/core/common/logger/logger.py +223 -0
  35. ladder/core/common/logger/stdout.py +39 -0
  36. ladder/core/common/platform.py +121 -0
  37. ladder/core/databib/__init__.py +0 -0
  38. ladder/core/databib/config/__init__.py +16 -0
  39. ladder/core/databib/config/auto_config.py +142 -0
  40. ladder/core/databib/config/config.py +780 -0
  41. ladder/core/databib/config/config_iterables.py +60 -0
  42. ladder/core/databib/config/config_parser.py +148 -0
  43. ladder/core/databib/config/yaml_util.py +253 -0
  44. ladder/core/databib/dataclasses/__init__.py +16 -0
  45. ladder/core/databib/dataclasses/dataclass.py +391 -0
  46. ladder/core/databib/dataclasses/dataclass_dict.py +192 -0
  47. ladder/core/databib/dataclasses/dataclass_interface.py +46 -0
  48. ladder/core/databib/dataclasses/dataclass_list.py +171 -0
  49. ladder/core/databib/dataclasses/dataclass_utils.py +63 -0
  50. ladder/core/databib/utils/classproperty.py +47 -0
.gitignore ADDED
@@ -0,0 +1,2 @@
 
 
 
1
+ __pycache__/
2
+ *.pyc
LICENSE ADDED
@@ -0,0 +1,21 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ MIT License
2
+
3
+ Copyright (c) 2026 INSAIT
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
README.md ADDED
@@ -0,0 +1,76 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ license: mit
3
+ library_name: lerobot
4
+ tags: [lerobot, envhub, robotics, simulation, benchmark, long-horizon, isaac-sim, isaac-lab, franka, droid, ladder]
5
+ ---
6
+
7
+ # LADDER RoboLab-Long
8
+
9
+ The RoboLab-Long suite of [LADDER](https://ladderrobotics.ai), a long-horizon robot manipulation benchmark, as a LeRobot [EnvHub](https://huggingface.co/docs/lerobot/envhub) environment. It has 44 tasks of 1 to 10 subgoals for a Franka arm with a Robotiq gripper (the DROID setup), built on [RoboLab](https://github.com/NVlabs/RoboLab) and Isaac Sim 6 / Isaac Lab 3.
10
+
11
+ The two other suites are separate repositories, because each simulator needs its own Python environment:
12
+
13
+ | Suite | Repository | Simulator | Robot | Tasks | Episodes per task |
14
+ |---|---|---|---|---|---|
15
+ | RoboLab-Long | this one | Isaac Sim 6 / Isaac Lab 3 | Franka (DROID) | 44 | 8 |
16
+ | SimplerEnv-Long | [`INSAIT-Institute/LADDER-SimplerEnv-Long`](https://huggingface.co/INSAIT-Institute/LADDER-SimplerEnv-Long) | SAPIEN 3 / ManiSkill 3 | WidowX | 54 | 24 |
17
+ | RobotArena-∞-Long | [`INSAIT-Institute/LADDER-RobotArena-Long`](https://huggingface.co/INSAIT-Institute/LADDER-RobotArena-Long) | Genesis | WidowX | 47 | 8 |
18
+
19
+ ## Evaluate a policy
20
+
21
+ Serve it with the LeRobot simulator server, from a LeRobot checkout, with Docker and the NVIDIA Container Toolkit, on an NVIDIA RTX GPU with 48 GB for 8 parallel episodes. Isaac Sim 6 needs NumPy 2.3, which LeRobot itself does not accept, so like LeRobot's own RoboLab integration it runs only in the server, apart from your policy's environment:
22
+
23
+ ```bash
24
+ pip install -e ".[dataset,evaluation,remote]" # plus your policy's extra, e.g. ".[pi]"
25
+ lerobot-env-server --envhub=INSAIT-Institute/LADDER-RoboLab-Long@v1.0.0 --docker=true
26
+ lerobot-eval --policy.path=<your DROID checkpoint> \
27
+ --env.type=envhub --env.hub_path=INSAIT-Institute/LADDER-RoboLab-Long@v1.0.0 \
28
+ --env.server.endpoint=tcp/127.0.0.1:7448 \
29
+ --env.task=comp_bin_2 --eval.batch_size=8 --eval.n_episodes=8 --eval.use_async_envs=false
30
+ ```
31
+
32
+ - `--env.task` takes one task, a comma-separated list (run one after another: keep `--env.max_parallel_tasks=1`), or nothing for all 44. [TASKS.md](https://github.com/insait-institute/ladder/blob/main/TASKS.md) lists them.
33
+ - Each task is one Isaac Lab world of 8 parallel envs: keep `--eval.batch_size` at 8 (2 on a 24 GB GPU) and `--eval.use_async_envs=false`. The server downloads the assets and starts Isaac Sim (compiling its shaders on a new machine) before it reports ready; each task's world is then built when the client opens it.
34
+ - `@v1.0.0` pins this repository to its release for LADDER v1.0.0 (or pin a commit): LeRobot runs its `env.py`.
35
+
36
+ ## Observations, actions and scores
37
+
38
+ | | |
39
+ |---|---|
40
+ | Observation | `pixels.main`: the over-the-shoulder camera and `pixels.wrist`: the wrist camera, 224x224 RGB; `agent_pos`: 7 joint positions and the gripper (0 open, 1 closed) |
41
+ | Action | 7 absolute joint positions and the gripper (above 0.5 closes it), as LADDER runs pi0.5 (`pi05_droid_jointpos`) |
42
+ | Control rate | 15 Hz |
43
+ | Step budget | the task's own budget, from RoboLab's episode length |
44
+ | Instruction | `task_description`, the task's instruction |
45
+ | Success | `info["is_success"]`: LADDER's task success (`pc_success` in LeRobot) |
46
+ | Progress | `info["metrics"]["subgoal_progress"]` (and `subgoals_done`): LADDER's subgoal score at the end of the episode, each subgoal met in the final state and, for an object moved twice, in order; all of them once the task succeeded. `reward` is its change at each step, so `avg_sum_reward` in LeRobot is the mean final progress |
47
+
48
+ Options, passed as `--sim.kwargs='{make_env_kwargs: {...}}'` to the server: `observation_height`, `observation_width` (default 224x224, as LADDER runs pi0.5), `front_camera_name` (default `main`), `wrist_camera_name` (default `wrist`).
49
+
50
+ ## How it relates to LADDER
51
+
52
+ `ladder/` is LADDER's own code at release [`v1.0.0`](https://github.com/insait-institute/ladder/releases/tag/v1.0.0), unchanged: the task definitions, scene layouts and success predicates. `env.py` builds the suite's environment with the settings of LADDER's own RoboLab server (`env_server.py`). `requirements.txt` is LADDER's own lock of that environment, every package pinned to its version, less Isaac Lab and two packages only Isaac Lab needs. Isaac Lab's wheel (the version LADDER pins), RoboLab's source (the commit LADDER pins, with LADDER's one-line asset-directory patch), openpi's client and the RoboLab assets are downloaded on first use (about 1 GB, checked by sha256) into `~/.cache/ladder/envhub` (`LADDER_CACHE` moves it). Isaac Lab is loaded from its wheel rather than installed because its metadata pins `transformers==4.57.6`, for an image encoder RoboLab never uses, and that version needs a `huggingface-hub` older than the LeRobot server accepts.
53
+
54
+ The full suite is all 44 tasks with 8 episodes each. LADDER's own harness (`scripts/eval.sh`) stays the reference for leaderboard results; see [EVALUATION.md](https://github.com/insait-institute/ladder/blob/main/EVALUATION.md).
55
+
56
+ ## Checked against LADDER
57
+
58
+ - The reset frames match LADDER's recorded episodes (34.5 dB PSNR on the main camera, 33.2 dB on the wrist camera).
59
+ - pi0.5 (`pi05_droid_jointpos`, LADDER's checkpoint), run through this repository's Docker image with LADDER's own client settings, on 4 tasks (`comp_bin_2`, `comp_transfer_3`, `comp_bin_6`, `comp_route_3`; 32 episodes), succeeded in 19 and 16 of 32 episodes in two runs. LADDER's published episodes of the same tasks: 21 of 32, and LADDER's earlier runs of pi0.5 on them vary as much (`comp_bin_6`: 3 and 5 of 8).
60
+ - In a new container the server is ready after about 5 minutes (downloads, Isaac Sim's first start, one world built to compile shaders); a client's first reset then takes about 20 seconds.
61
+
62
+ ## Citation
63
+
64
+ ```bibtex
65
+ @article{ladder2026,
66
+ title = {{LADDER}: A Long-Horizon Robot Manipulation Benchmark},
67
+ author = {Petkov, Petko and Albanese, Giuliano and Nikolov, Nikolay and Van Gool, Luc and Tremblay, Jonathan and Paudel, Danda Pani},
68
+ journal = {arXiv preprint arXiv:2610.18053},
69
+ year = {2026},
70
+ url = {https://arxiv.org/abs/2610.18053}
71
+ }
72
+ ```
73
+
74
+ ## License
75
+
76
+ MIT, as LADDER. RoboLab is Apache-2.0 (NVIDIA); the RoboLab assets are mostly CC BY-NC-SA 4.0. The downloaded files keep their own licenses (see LADDER's [THIRD_PARTY_NOTICES.md](https://github.com/insait-institute/ladder/blob/main/THIRD_PARTY_NOTICES.md)). **Isaac Sim** is distributed under the [NVIDIA Isaac Sim license](https://docs.isaacsim.omniverse.nvidia.com/latest/common/NVIDIA_Omniverse_License_Agreement.html); `env.py` sets `OMNI_KIT_ACCEPT_EULA=YES`, so running this environment means you accept it.
_ladder_envhub.py ADDED
@@ -0,0 +1,493 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2026 INSAIT. MIT License (see LICENSE).
2
+ """Code shared by the three LADDER EnvHub repositories.
3
+
4
+ LADDER (https://github.com/insait-institute/ladder) is a long-horizon manipulation benchmark with three
5
+ suites, each on its own simulator. Each suite is published as its own EnvHub repository, because the
6
+ three simulators need incompatible Python environments. This module holds what they share: fetching the
7
+ pinned benchmark files, the batched ``gym.vector.VectorEnv`` around a LADDER task, and the action and
8
+ observation conversions.
9
+
10
+ The benchmark's own code (task definitions, scene layouts, success predicates) is the ``ladder/``
11
+ package next to this file, copied unchanged from the LADDER release named in ``LADDER_RELEASE``.
12
+ Third-party code and the simulation assets are downloaded from that release on first use and checked
13
+ against their sha256.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import contextlib
19
+ import fcntl
20
+ import hashlib
21
+ import logging
22
+ import os
23
+ import shutil
24
+ import sys
25
+ import tarfile
26
+ import tempfile
27
+ import urllib.request
28
+ import zipfile
29
+ from dataclasses import dataclass
30
+ from pathlib import Path
31
+ from typing import Any
32
+
33
+ import gymnasium as gym
34
+ import numpy as np
35
+ from gymnasium import spaces
36
+ from gymnasium.vector.utils import batch_space
37
+
38
+ logger = logging.getLogger(__name__)
39
+
40
+ LADDER_RELEASE = "v1.0.0"
41
+ LADDER_COMMIT = "6c88eeadc8f5666fdf65f10b9c06bb7bdf1f7ca4"
42
+ _RELEASE_URL = f"https://github.com/insait-institute/ladder/releases/download/{LADDER_RELEASE}"
43
+
44
+
45
+ @dataclass(frozen=True)
46
+ class Download:
47
+ """One pinned archive. ``strip`` drops a leading directory, ``prefix`` places the files under one."""
48
+
49
+ url: str
50
+ sha256: str
51
+ strip: str = ""
52
+ prefix: str = ""
53
+
54
+
55
+ DOWNLOADS: dict[str, Download] = {
56
+ "simpler_assets": Download(
57
+ f"{_RELEASE_URL}/simpler_assets.tar.gz",
58
+ "dfa45de8a2670cc6f05bb9db28cdf16b6ebabc24f41fe10a3cbe0ff1bde53a9f",
59
+ ),
60
+ # ManiSkill's WidowX model, from its upstream repository (it has no license to redistribute it).
61
+ "widowx": Download(
62
+ "https://github.com/haosulab/ManiSkill-WidowX250S/archive/6a12bb745d964aab9fc897f0999cad53aa29000c.tar.gz",
63
+ "c440d733291e28fd257d0e6a6fb71b8575d155fd7bde92f6779743a52d8fedd0",
64
+ strip="ManiSkill-WidowX250S-6a12bb745d964aab9fc897f0999cad53aa29000c",
65
+ prefix="data/robots/widowx",
66
+ ),
67
+ "sapien_physx": Download(
68
+ f"{_RELEASE_URL}/sapien_physx_gpu_linux.zip",
69
+ "0353b3b0c5d45d3ad85136de38ac89c216ddfea8f2306966bfafb93cd6cd839c",
70
+ ),
71
+ "robot_arena_assets": Download(
72
+ f"{_RELEASE_URL}/robot_arena_assets.tar.gz",
73
+ "4e9ab964bc1fe2dd71570307265dc0ab0e7edb8466ddfe46056db7d90c0b2187",
74
+ strip="robot_arena_data",
75
+ ),
76
+ "robolab_assets": Download(
77
+ f"{_RELEASE_URL}/robolab_assets.tar.gz",
78
+ "19da3abcc8d94126791a78c3cb06cb3b78776e8513c73be2ad0961206b209d8d",
79
+ ),
80
+ "robolab_src": Download(
81
+ f"{_RELEASE_URL}/robolab_src.tar.gz",
82
+ "ffcd150871ead600dd84b9302459a66b9a1e59f4ed2cc7a07a44ac6c0b27b4a5",
83
+ strip="RoboLab-27b6212df31799f72883bd79c8629607d89782de",
84
+ ),
85
+ # Isaac Lab's own wheel, as LADDER pins it. It is loaded from here rather than installed: its metadata pins
86
+ # transformers==4.57.6 (for an optional Theia image encoder RoboLab never imports), which needs
87
+ # huggingface-hub<1, and the LeRobot server needs huggingface-hub>=1.31.
88
+ "isaaclab": Download(
89
+ "https://pypi.nvidia.com/isaaclab/isaaclab-3.0.0b2-py3-none-any.whl",
90
+ "386fcbe043ae98c880468f30872ffcdbfb37f26dc6756b9dc2bbe0226947eb11",
91
+ ),
92
+ "openpi_src": Download(
93
+ f"{_RELEASE_URL}/openpi_src.tar.gz",
94
+ "2e36927c2c77ffaf111a16e5533d6d4ac26ea00fb47c1650f95a96e5d9f078de",
95
+ strip="openpi-aa6420561529593114160d05e5ad155792b272f3",
96
+ ),
97
+ }
98
+
99
+
100
+ def cache_dir() -> Path:
101
+ """Where downloads are kept: ``$LADDER_CACHE``, else ``~/.cache/ladder/envhub``."""
102
+ root = os.environ.get("LADDER_CACHE") or os.path.join(os.path.expanduser("~"), ".cache", "ladder", "envhub")
103
+ return Path(root) / LADDER_RELEASE
104
+
105
+
106
+ def _sha256(path: Path) -> str:
107
+ digest = hashlib.sha256()
108
+ with path.open("rb") as f:
109
+ for block in iter(lambda: f.read(1 << 20), b""):
110
+ digest.update(block)
111
+ return digest.hexdigest()
112
+
113
+
114
+ def fetch(name: str) -> Path:
115
+ """Return the extracted directory of a pinned download, downloading it once per machine.
116
+
117
+ Concurrent processes (e.g. several eval lanes) wait on a file lock and reuse one copy.
118
+ """
119
+ spec = DOWNLOADS[name]
120
+ target = cache_dir() / name
121
+ if (target / ".complete").exists():
122
+ return target
123
+ target.parent.mkdir(parents=True, exist_ok=True)
124
+ with open(target.parent / f".{name}.lock", "w") as lock:
125
+ fcntl.flock(lock, fcntl.LOCK_EX)
126
+ if (target / ".complete").exists():
127
+ return target
128
+ with tempfile.TemporaryDirectory(dir=target.parent, prefix=f".{name}.") as tmp:
129
+ archive = Path(tmp) / spec.url.rsplit("/", 1)[-1]
130
+ logger.info("LADDER: downloading %s", spec.url)
131
+ with urllib.request.urlopen(spec.url, timeout=60) as response, archive.open("wb") as out:
132
+ shutil.copyfileobj(response, out, length=1 << 20)
133
+ actual = _sha256(archive)
134
+ if actual != spec.sha256:
135
+ raise RuntimeError(f"{spec.url}: sha256 {actual}, expected {spec.sha256}")
136
+ extracted = Path(tmp) / "x"
137
+ if archive.suffix in (".zip", ".whl"):
138
+ with zipfile.ZipFile(archive) as z:
139
+ z.extractall(extracted)
140
+ else:
141
+ with tarfile.open(archive) as t:
142
+ t.extractall(extracted, filter="data")
143
+ archive.unlink()
144
+ root = extracted / spec.strip if spec.strip else extracted
145
+ staged = Path(tmp) / "staged"
146
+ destination = staged / spec.prefix if spec.prefix else staged
147
+ destination.parent.mkdir(parents=True, exist_ok=True)
148
+ root.rename(destination)
149
+ (staged / ".complete").touch()
150
+ shutil.rmtree(target, ignore_errors=True)
151
+ staged.rename(target)
152
+ return target
153
+
154
+
155
+ def add_to_path(*paths: Path) -> None:
156
+ for path in paths:
157
+ if str(path) not in sys.path:
158
+ sys.path.insert(0, str(path))
159
+
160
+
161
+ # ---------------------------------------------------------------------------------------------- poses
162
+
163
+ # LADDER's poses are in its canonical end-effector frame. For the WidowX, observations and actions use the
164
+ # BridgeData v2 end-effector frame instead, as LADDER's Bridge policy does: the canonical frame turned 180 degrees
165
+ # about its x axis (CANONICAL_TO_BRIDGE_ROTATION in LADDER's vlam_robot_inference.py).
166
+ CANONICAL_TO_BRIDGE = np.diag([1.0, -1.0, -1.0])
167
+
168
+ def axisangle_to_matrix(rotvec: np.ndarray) -> np.ndarray:
169
+ rv = np.asarray(rotvec, dtype=np.float64).reshape(3)
170
+ theta = float(np.linalg.norm(rv))
171
+ if theta < 1e-12:
172
+ return np.eye(3)
173
+ kx, ky, kz = rv / theta
174
+ k = np.array([[0.0, -kz, ky], [kz, 0.0, -kx], [-ky, kx, 0.0]])
175
+ return np.eye(3) + np.sin(theta) * k + (1.0 - np.cos(theta)) * (k @ k)
176
+
177
+
178
+ def matrix_to_axisangle(rot: np.ndarray) -> np.ndarray:
179
+ r = np.asarray(rot, dtype=np.float64).reshape(3, 3)
180
+ theta = float(np.arccos(np.clip((np.trace(r) - 1.0) * 0.5, -1.0, 1.0)))
181
+ if theta < 1e-7:
182
+ return np.zeros(3, dtype=np.float32)
183
+ axis = np.array([r[2, 1] - r[1, 2], r[0, 2] - r[2, 0], r[1, 0] - r[0, 1]])
184
+ norm = float(np.linalg.norm(axis))
185
+ return ((axis / norm) * theta).astype(np.float32) if norm >= 1e-12 else np.zeros(3, dtype=np.float32)
186
+
187
+
188
+ WIDOWX_STATE_NAMES = ("x", "y", "z", "rx", "ry", "rz", "gripper")
189
+ WIDOWX_DELTA_ACTION_NAMES = ("dx", "dy", "dz", "drx", "dry", "drz", "gripper")
190
+ DROID_JOINT_NAMES = (*(f"joint_{i}.pos" for i in range(7)), "gripper.pos")
191
+
192
+
193
+ def in_env_server() -> bool:
194
+ """Whether this process is LeRobot's env server (`lerobot-env-server`), not an in-process evaluation.
195
+
196
+ The server opens a task within a client's 120 s deadline, so slow first builds are worth doing before it reports
197
+ ready; in-process there is no deadline and LeRobot passes no task, so they would only add start-up time.
198
+ """
199
+ return "lerobot_env_server" in sys.argv[0] or "lerobot-env-server" in sys.argv[0]
200
+
201
+
202
+ def one_task(task: str | None, known: list[str]) -> str:
203
+ """The single task ``make_env`` builds: the suite's simulator keeps one scene per process."""
204
+ names = select_tasks(task, known) if task else []
205
+ if len(names) != 1:
206
+ raise ValueError(
207
+ "make_env builds one task (pass task=<name>, --env.task=<name>); LeRobot's default path "
208
+ f"(vector_env_fns) runs several, one after another. Available: {known}"
209
+ )
210
+ return names[0]
211
+
212
+
213
+ def select_tasks(task: str | None, known: list[str]) -> list[str]:
214
+ """``task`` is a task name, a comma-separated list, or empty/"all" for every task."""
215
+ if not task or task in ("all", "*"):
216
+ return list(known)
217
+ names = [t.strip() for t in task.split(",") if t.strip()]
218
+ unknown = [n for n in names if n not in known]
219
+ if unknown:
220
+ raise ValueError(f"Unknown LADDER tasks {unknown}. Available: {known}")
221
+ return names
222
+
223
+
224
+ # ---------------------------------------------------------------------------------------------- env
225
+
226
+
227
+ class LadderVectorEnv(gym.vector.VectorEnv):
228
+ """``n_envs`` parallel episodes of one LADDER task, stepped as one batch by the suite's simulator.
229
+
230
+ Observations follow LeRobot's EnvHub conventions: ``pixels`` (one image per camera) and
231
+ ``agent_pos``. ``info["is_success"]`` is LADDER's task success, latched once reached.
232
+ ``info["metrics"]`` holds LADDER's subgoal score of the current state (``subgoals_done``, and
233
+ ``subgoal_progress``, its fraction), which LeRobot reads at the end of each episode; ``reward`` is
234
+ the change in ``subgoal_progress``, so an episode's rewards sum to its final progress.
235
+ Episode ``i`` of rollout ``r`` is LADDER episode ``r * n_envs + i``.
236
+
237
+ Subclasses implement ``_backend_reset(episode_ids)`` and ``_backend_step(actions)`` with the
238
+ suite's own LADDER environment; both return one LADDER ``RobotObservation`` (or its dict) per env.
239
+ """
240
+
241
+ suite: str = ""
242
+ robot: str = "widowx" # or "franka"
243
+ default_image_size: tuple[int, int] = (480, 640)
244
+ resizable: bool = True # whether the simulator renders at observation_height x observation_width
245
+ episodes_per_task: int = 8 # distinct LADDER episodes; later rollouts repeat them
246
+ fps: int = 5
247
+
248
+ def __init__(
249
+ self,
250
+ task: str,
251
+ n_envs: int = 1,
252
+ max_episode_steps: int | None = None,
253
+ observation_height: int | None = None,
254
+ observation_width: int | None = None,
255
+ front_camera_name: str = "main",
256
+ wrist_camera_name: str = "wrist",
257
+ seed: int = 42,
258
+ ) -> None:
259
+ if not self.resizable and (observation_height or observation_width):
260
+ raise ValueError(f"{self.suite} renders at {self.default_image_size}; resize the frames in your policy")
261
+ self.task = task
262
+ self.task_description = task
263
+ self.num_envs = int(n_envs)
264
+ self._max_episode_steps = int(max_episode_steps or self.task_budget(task))
265
+ self._front = front_camera_name
266
+ self._wrist = wrist_camera_name
267
+ self._seed = int(seed)
268
+ self._frame = CANONICAL_TO_BRIDGE if self.robot == "widowx" else np.eye(3)
269
+ self._h = int(observation_height or self.default_image_size[0])
270
+ self._w = int(observation_width or self.default_image_size[1])
271
+ self.metadata = {
272
+ "render_modes": ["rgb_array"],
273
+ "render_fps": self.fps,
274
+ "autoreset_mode": gym.vector.AutoresetMode.DISABLED,
275
+ }
276
+ self.render_mode = "rgb_array"
277
+ self.closed = False
278
+
279
+ image = spaces.Box(0, 255, shape=(self._h, self._w, 3), dtype=np.uint8)
280
+ cameras = {self._front: image}
281
+ if self.robot == "franka":
282
+ cameras[self._wrist] = image
283
+ state_dim = 8 if self.robot == "franka" else 7
284
+ self.single_observation_space = spaces.Dict(
285
+ {
286
+ "pixels": spaces.Dict(cameras),
287
+ "agent_pos": spaces.Box(-np.inf, np.inf, shape=(state_dim,), dtype=np.float32),
288
+ }
289
+ )
290
+ # Franka: absolute joint targets and the gripper; WidowX: pose deltas and the gripper.
291
+ self.single_action_space = spaces.Box(-np.inf, np.inf, shape=(state_dim,), dtype=np.float32)
292
+ self.observation_space = batch_space(self.single_observation_space, self.num_envs)
293
+ self.action_space = batch_space(self.single_action_space, self.num_envs)
294
+
295
+ self._rollout = 0
296
+ self._step_count = 0
297
+ self._target_poses = [np.eye(4, dtype=np.float32) for _ in range(self.num_envs)]
298
+ self._joints: list[np.ndarray | None] = [None] * self.num_envs
299
+ self._frames = [np.zeros((self._h, self._w, 3), dtype=np.uint8) for _ in range(self.num_envs)]
300
+ self._success = np.zeros(self.num_envs, dtype=bool)
301
+ self._progress = np.zeros(self.num_envs, dtype=np.float32)
302
+ self._first_met: list[dict[int, int]] = [{} for _ in range(self.num_envs)]
303
+ self._met_after_ready: list[set[int]] = [set() for _ in range(self.num_envs)]
304
+ self._last_achieved: list[list[bool] | None] = [None] * self.num_envs
305
+
306
+ def goal_sources(self) -> list[str | None] | None:
307
+ """The object each subgoal moves, for LADDER's ordering of an object's legs; None if unordered."""
308
+ return None
309
+
310
+ # Subclass API -------------------------------------------------------------------------------
311
+ @classmethod
312
+ def task_budget(cls, task: str) -> int:
313
+ raise NotImplementedError
314
+
315
+ def _backend_reset(self, episode_ids: list[int]) -> list[Any]:
316
+ raise NotImplementedError
317
+
318
+ def _backend_step(self, actions: list[Any]) -> list[Any]:
319
+ raise NotImplementedError
320
+
321
+ def _backend_close(self) -> None:
322
+ pass
323
+
324
+ # Gymnasium API ------------------------------------------------------------------------------
325
+ def reset(self, *, seed: Any = None, options: dict[str, Any] | None = None):
326
+ episode_ids = [self._rollout * self.num_envs + i for i in range(self.num_envs)]
327
+ if max(episode_ids) >= self.episodes_per_task and not getattr(self, "_warned_repeat", False):
328
+ self._warned_repeat = True
329
+ logger.warning(
330
+ "LADDER %s has %d distinct episodes per task; episodes past them repeat them",
331
+ self.suite, self.episodes_per_task,
332
+ )
333
+ self._rollout += 1
334
+ self._step_count = 0
335
+ self._success[:] = False
336
+ self._progress[:] = 0.0
337
+ self._first_met = [{} for _ in range(self.num_envs)]
338
+ self._met_after_ready = [set() for _ in range(self.num_envs)]
339
+ self._last_achieved = [None] * self.num_envs
340
+ obs, _, _, _, info = self._pack(self._backend_reset(episode_ids))
341
+ return obs, info
342
+
343
+ def step(self, actions: np.ndarray):
344
+ actions = np.asarray(actions, dtype=np.float32).reshape(self.num_envs, -1)
345
+ raw = self._backend_step([self._decode_action(i, a) for i, a in enumerate(actions)])
346
+ self._step_count += 1
347
+ return self._pack(raw)
348
+
349
+ def render(self) -> tuple[np.ndarray, ...]:
350
+ return tuple(self._frames)
351
+
352
+ def call(self, name: str, *args: Any, **kwargs: Any) -> tuple[Any, ...]:
353
+ if name == "render":
354
+ return self.render()
355
+ attr = getattr(self, name)
356
+ value = attr(*args, **kwargs) if callable(attr) else attr
357
+ return (value,) * self.num_envs
358
+
359
+ def get_attr(self, name: str) -> tuple[Any, ...]:
360
+ return (getattr(self, name),) * self.num_envs
361
+
362
+ def close(self, **kwargs: Any) -> None:
363
+ if not self.closed:
364
+ self._backend_close()
365
+ self.closed = True
366
+
367
+ # Conversions --------------------------------------------------------------------------------
368
+ def _pack(self, raw_obs: list[Any]):
369
+ fronts, wrists, states = [], [], []
370
+ progress = np.zeros(self.num_envs, dtype=np.float32)
371
+ truncated = np.zeros(self.num_envs, dtype=bool)
372
+ completed = np.zeros(self.num_envs, dtype=np.int32)
373
+ for i, raw in enumerate(raw_obs):
374
+ if not isinstance(raw, dict):
375
+ raw = {"images": raw.images, "state": vars(raw.state), "metadata": raw.metadata}
376
+ images = {k: np.asarray(v, dtype=np.uint8) for k, v in (raw.get("images") or {}).items()}
377
+ state = raw.get("state") or {}
378
+ meta = raw.get("metadata") or {}
379
+ eef = np.asarray(state.get("eef_pose", np.eye(4)), dtype=np.float32)
380
+ target = state.get("eef_pose_from_target")
381
+ gripper = float(np.asarray(state.get("gripper_state", [1.0])).reshape(-1)[0])
382
+ joints = state.get("joints")
383
+ self._target_poses[i] = np.asarray(target if target is not None else eef, dtype=np.float32)
384
+ self._joints[i] = None if joints is None else np.asarray(joints, dtype=np.float32).reshape(-1)[:7]
385
+
386
+ if meta.get("instruction"):
387
+ self.task_description = str(meta["instruction"]).strip()
388
+ front = images.get("main", next(iter(images.values()), None))
389
+ if front is None:
390
+ front = np.zeros((self._h, self._w, 3), dtype=np.uint8)
391
+ fronts.append(front)
392
+ self._frames[i] = front
393
+ if self.robot == "franka":
394
+ wrists.append(images.get("wrist", np.zeros_like(front)))
395
+ states.append(np.concatenate([self._joints[i], [1.0 - gripper]]).astype(np.float32))
396
+ else:
397
+ states.append(np.concatenate([eef[:3, 3], matrix_to_axisangle(eef[:3, :3] @ self._frame), [gripper]]))
398
+
399
+ self._success[i] |= bool(meta.get("done", False))
400
+ oracle = meta.get("oracle") if isinstance(meta.get("oracle"), dict) else {}
401
+ achieved = [bool(v) for v in oracle.get("achieved", [])]
402
+ completed[i] = self._subgoals_done(i, achieved)
403
+ progress[i] = completed[i] / len(achieved) if achieved else float(self._success[i])
404
+ truncated[i] = bool(meta.get("truncated", False)) or self._step_count >= self._max_episode_steps
405
+
406
+ pixels = {self._front: np.stack(fronts)}
407
+ if self.robot == "franka":
408
+ pixels[self._wrist] = np.stack(wrists)
409
+ obs = {"pixels": pixels, "agent_pos": np.stack(states).astype(np.float32)}
410
+ reward = progress - self._progress
411
+ self._progress = progress
412
+ info = {
413
+ "is_success": self._success.copy(),
414
+ "metrics": {"subgoals_done": completed.astype(np.float32), "subgoal_progress": progress.copy()},
415
+ }
416
+ return obs, reward, self._success.copy(), truncated, info
417
+
418
+ def _subgoals_done(self, i: int, achieved: list[bool]) -> int:
419
+ """LADDER's subgoal score (scripts/leaderboard.py ``subgoals_done``) of the episode so far, ending now.
420
+
421
+ Every subgoal once the task succeeded; otherwise the subgoals met now, each counted only if it was
422
+ met after every earlier subgoal of the same object was first met (a relay's legs are ordered).
423
+ """
424
+ if self._success[i]:
425
+ return len(achieved)
426
+ step, first, after = self._step_count, self._first_met[i], self._met_after_ready[i]
427
+ sources = self.goal_sources() or [None] * len(achieved)
428
+ # LADDER scores its goal trace, which records the steps where the achieved vector changes.
429
+ changed = self._last_achieved[i] != achieved
430
+ self._last_achieved[i] = list(achieved)
431
+ for g, met in enumerate(achieved if changed else []):
432
+ if met:
433
+ first.setdefault(g, step)
434
+ for g, met in enumerate(achieved if changed else []):
435
+ earlier = [leg for leg in range(g) if sources[g] is not None and sources[leg] == sources[g]]
436
+ if met and all(leg in first for leg in earlier) and step > max((first[leg] for leg in earlier), default=-1):
437
+ after.add(g)
438
+ return sum(1 for g, met in enumerate(achieved) if met and g in after)
439
+
440
+ def _decode_action(self, i: int, raw: np.ndarray) -> Any:
441
+ from ladder.components.inference.api.core.action import (
442
+ EndEffectorPoseAction,
443
+ JointAnglesAction,
444
+ ManipulatorAction,
445
+ )
446
+
447
+ if self.robot == "franka":
448
+ # As LADDER runs pi05_droid_jointpos: 7 joint targets, and the gripper closed above 0.5.
449
+ return ManipulatorAction(
450
+ arm_action=JointAnglesAction(angles=raw[:7].astype(np.float32)),
451
+ gripper_action=0.0 if float(raw[7]) > 0.5 else 1.0,
452
+ )
453
+ # As LADDER's clients run the Bridge policy: the rotation in the end-effector frame, the translation in the
454
+ # base frame, both applied to the commanded pose rather than the observed one
455
+ # (EndEffectorPoseDeltaMode.ROT_EEF_TRANS_BASE), in the BridgeData end-effector frame.
456
+ frame = self._frame
457
+ target = self._target_poses[i].astype(np.float64)
458
+ new_target = np.eye(4, dtype=np.float32)
459
+ new_target[:3, 3] = target[:3, 3] + raw[:3].astype(np.float64)
460
+ new_target[:3, :3] = target[:3, :3] @ frame @ axisangle_to_matrix(raw[3:6]) @ frame.T
461
+ self._target_poses[i] = new_target
462
+ return ManipulatorAction(
463
+ arm_action=EndEffectorPoseAction(translation=new_target[:3, 3].copy(), rotation=new_target[:3, :3].copy()),
464
+ gripper_action=float(np.clip(raw[6], 0.0, 1.0)),
465
+ )
466
+
467
+
468
+ def lerobot_sim(robot: str, fps: int) -> dict[str, Any]:
469
+ """The ``LEROBOT_SIM`` description of a suite."""
470
+ if robot == "franka":
471
+ names = list(DROID_JOINT_NAMES)
472
+ return {"fps": fps, "control_mode": "position", "state_names": names, "action_names": names}
473
+ return {
474
+ "fps": fps,
475
+ "control_mode": "delta",
476
+ "state_names": list(WIDOWX_STATE_NAMES),
477
+ "action_names": list(WIDOWX_DELTA_ACTION_NAMES),
478
+ }
479
+
480
+
481
+ @contextlib.contextmanager
482
+ def ignore_signal_in_thread():
483
+ """Isaac Sim installs signal handlers, which only the main thread may do."""
484
+ import signal
485
+ import threading
486
+
487
+ original = signal.signal
488
+ if threading.current_thread() is not threading.main_thread():
489
+ signal.signal = lambda *a, **kw: None # type: ignore[assignment]
490
+ try:
491
+ yield
492
+ finally:
493
+ signal.signal = original # type: ignore[assignment]
env.py ADDED
@@ -0,0 +1,273 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2026 INSAIT. MIT License (see LICENSE).
2
+ """LADDER RoboLab-Long for LeRobot EnvHub: 44 long-horizon Franka (DROID) tasks on Isaac Sim 6 / Isaac Lab 3.
3
+
4
+ Each task is one suite of LeRobot's ``{suite: {task_id: env}}``; its 8 episodes run as 8 parallel envs
5
+ in one Isaac Lab world. Isaac Sim starts once per process. See README.md.
6
+ """
7
+
8
+ import os
9
+ import re
10
+ import sys
11
+
12
+ REPO_ID = "INSAIT-Institute/LADDER-RoboLab-Long"
13
+
14
+ _HERE = os.path.dirname(os.path.abspath(__file__))
15
+ if not os.path.exists(os.path.join(_HERE, "_ladder_envhub.py")):
16
+ # `make_env("<repo>")` downloads only this file: fetch the rest of the same revision.
17
+ from huggingface_hub import snapshot_download
18
+
19
+ _revision = os.path.basename(_HERE)
20
+ _HERE = snapshot_download(REPO_ID, revision=_revision if re.fullmatch(r"[0-9a-f]{40}", _revision) else None)
21
+ if _HERE not in sys.path:
22
+ sys.path.insert(0, _HERE)
23
+
24
+ import atexit # noqa: E402
25
+ import logging # noqa: E402
26
+ from concurrent.futures import ThreadPoolExecutor # noqa: E402
27
+ from functools import partial # noqa: E402
28
+ from typing import Any # noqa: E402
29
+
30
+ import _ladder_envhub as lh # noqa: E402
31
+
32
+ EPISODES_PER_TASK = 8
33
+ CONTROL_HZ = 15
34
+ LEROBOT_SIM = lh.lerobot_sim("franka", fps=CONTROL_HZ)
35
+
36
+
37
+ def _add_sources() -> None:
38
+ """Isaac Lab, RoboLab (patched to read its assets from ROBOLAB_ASSET_DIR) and openpi_client, as LADDER pins them."""
39
+ if _Isaac.sources:
40
+ return
41
+ robolab = lh.fetch("robolab_src")
42
+ constants = robolab / "robolab" / "constants.py"
43
+ text = constants.read_text()
44
+ patched = 'ASSET_DIR = os.environ.get("ROBOLAB_ASSET_DIR") or os.path.join(PACKAGE_DIR, "assets")'
45
+ if patched not in text:
46
+ # LADDER's build_support/python/patches/robolab_constants_asset_dir.patch.
47
+ text = text.replace('ASSET_DIR = os.path.join(PACKAGE_DIR, "assets")', patched, 1)
48
+ text = text.replace(
49
+ " return os.path.join(PACKAGE_DIR, relative_path)",
50
+ ' normalized = relative_path.replace(os.sep, "/")\n'
51
+ ' if normalized.startswith("assets/"):\n'
52
+ ' return os.path.join(ASSET_DIR, *normalized[len("assets/"):].split("/"))\n'
53
+ " return os.path.join(PACKAGE_DIR, relative_path)",
54
+ 1,
55
+ )
56
+ # Atomically: another process may be importing it.
57
+ staged = constants.with_name(f".constants.{os.getpid()}.py")
58
+ staged.write_text(text)
59
+ os.replace(staged, constants)
60
+ if patched not in constants.read_text():
61
+ raise RuntimeError(f"{constants}: LADDER's asset-directory patch no longer applies")
62
+ # The extracted wheel is an installed package on sys.path, with its dist-info (see _ladder_envhub.DOWNLOADS).
63
+ lh.add_to_path(lh.fetch("isaaclab"), robolab, lh.fetch("openpi_src") / "packages" / "openpi-client" / "src")
64
+ os.environ.setdefault("ROBOLAB_ASSET_DIR", str(lh.fetch("robolab_assets") / "assets"))
65
+ _Isaac.sources = True
66
+
67
+
68
+ def task_names() -> list[str]:
69
+ """The suite's task names, from LADDER's own registry."""
70
+ from ladder.components.inference.robots.robolab.composition.specs import SPECS
71
+
72
+ return sorted(SPECS)
73
+
74
+
75
+ class _Isaac:
76
+ """Isaac Sim starts once per process and runs on one thread; one task's world is kept at a time."""
77
+
78
+ thread = ThreadPoolExecutor(max_workers=1, thread_name_prefix="ladder-isaac")
79
+ sources = False
80
+ app: Any = None
81
+ env: Any = None
82
+ env_cfg: Any = None
83
+ oracle: Any = None
84
+ key: Any = None
85
+
86
+
87
+ def _start_isaac() -> None:
88
+ if _Isaac.app is not None:
89
+ return
90
+ _add_sources()
91
+ # Running this environment accepts the NVIDIA Isaac Sim EULA (see README); Kit asks on stdin otherwise.
92
+ os.environ.setdefault("OMNI_KIT_ACCEPT_EULA", "YES")
93
+ os.environ.setdefault("ACCEPT_EULA", "Y")
94
+ import cv2 # noqa: F401
95
+ from isaaclab.app import AppLauncher
96
+
97
+ root = logging.getLogger()
98
+ levels = {handler: handler.level for handler in root.handlers}
99
+ with lh.ignore_signal_in_thread():
100
+ _Isaac.app = AppLauncher(headless=True, enable_cameras=True).app
101
+ for handler, level in levels.items(): # Kit lowers the levels of existing handlers
102
+ handler.setLevel(level)
103
+ # Kit hangs in its own shutdown; leave without it, keeping the exit status.
104
+ atexit.register(
105
+ lambda: (
106
+ sys.stdout.flush(),
107
+ sys.stderr.flush(),
108
+ os._exit(0 if getattr(sys, "last_value", None) is None else 1),
109
+ )
110
+ )
111
+ import carb.settings
112
+ import robolab.constants
113
+
114
+ # As LADDER's env_server.py: LADDER scores subgoals itself, and renderer failures stay visible.
115
+ robolab.constants.ENABLE_SUBTASK_PROGRESS_CHECKING = False
116
+ carb.settings.get_settings().set("/persistent/app/usd/muteUsdDiagnostics", False)
117
+
118
+
119
+ class RoboLabLong(lh.LadderVectorEnv):
120
+ suite = "robolab"
121
+ robot = "franka"
122
+ default_image_size = (224, 224)
123
+ episodes_per_task = EPISODES_PER_TASK
124
+ fps = CONTROL_HZ
125
+
126
+ @classmethod
127
+ def task_budget(cls, task: str) -> int:
128
+ from ladder.components.inference.robots.robolab.composition.specs import SPECS
129
+
130
+ return int(SPECS[task].episode_length_s * CONTROL_HZ)
131
+
132
+ def __init__(self, *args: Any, **kwargs: Any) -> None:
133
+ super().__init__(*args, **kwargs)
134
+ self._env = None
135
+ self._raw = None
136
+ self._converter = None
137
+ # LeRobot's server builds an env (one env of the first task) before it reports ready. Isaac Sim starts here,
138
+ # and the first env of a process builds its world here too: that compiles the shaders and loads the assets
139
+ # every task shares, which on a new machine or container would otherwise fall in a client's first open.
140
+ # A client's own batch size gets its world on its first reset.
141
+ self._fresh = _Isaac.thread.submit(self._start).result()
142
+
143
+ def _start(self) -> bool:
144
+ _start_isaac()
145
+ return _Isaac.env is None and self._build()
146
+
147
+ def goal_sources(self) -> list[str | None] | None:
148
+ # The object each goal places (a relay's legs are separate goals), as LADDER's privileged.py names it.
149
+ return [
150
+ next((geometry[0] for _, geometry in reversed(list(goal.legs)) if geometry is not None), None)
151
+ for goal in _Isaac.oracle or []
152
+ ]
153
+
154
+ def _backend_reset(self, episode_ids: list[int]) -> list[Any]:
155
+ return _Isaac.thread.submit(self._reset).result()
156
+
157
+ def _backend_step(self, actions: list[Any]) -> list[Any]:
158
+ if _Isaac.env is not self._env:
159
+ raise RuntimeError("Another task's world replaced this one: run one task at a time (--env.max_parallel_tasks=1)")
160
+ return _Isaac.thread.submit(self._step, actions).result()
161
+
162
+ def _build(self) -> bool:
163
+ """Build this task's world at this batch size, unless the process holds it; True if it was built."""
164
+ from ladder.components.inference.robots.robolab.composition.specs import task_class_name, task_target
165
+ from ladder.components.inference.robots.robolab.oracle import build_oracle
166
+ from robolab.core.environments.runtime import create_env
167
+ from robolab.registrations.droid.auto_env_registrations_jointpos import auto_register_droid_envs
168
+
169
+ self._class_name = task_class_name(self.task)
170
+ key = (self._class_name, self.num_envs)
171
+ if _Isaac.key == key:
172
+ return False
173
+ if _Isaac.env is not None:
174
+ _Isaac.env.close()
175
+ _Isaac.env = _Isaac.key = None
176
+ auto_register_droid_envs(task_dirs=None, task=[task_target(self.task)], cameras=None)
177
+ # The defaults of LADDER's env_server.py (RoboLab's add_common_eval_args).
178
+ _Isaac.env, _Isaac.env_cfg = create_env(
179
+ self._class_name,
180
+ device="cuda:0",
181
+ num_envs=self.num_envs,
182
+ instruction_type="default",
183
+ policy="ladder_runner",
184
+ renderer="realtime",
185
+ rendering_mode="balanced",
186
+ )
187
+ _Isaac.oracle = build_oracle(getattr(_Isaac.env.cfg, "subtasks", None), _Isaac.env_cfg.instruction)
188
+ _Isaac.key = key
189
+ if int(_Isaac.env.max_episode_length) != self._max_episode_steps:
190
+ logging.getLogger(__name__).warning(
191
+ "%s: Isaac Lab budget %d steps, expected %d", self.task, _Isaac.env.max_episode_length,
192
+ self._max_episode_steps,
193
+ )
194
+ return True
195
+
196
+ def _reset(self) -> list[Any]:
197
+ from ladder.components.inference.robots.robolab.droid_conversions import DroidJointposConverter
198
+
199
+ # As LADDER's env_server.py: a new world is reset as it is, a kept one first unfreezes its finished envs.
200
+ if not self._build() and not self._fresh:
201
+ _Isaac.env.reset_eval_state()
202
+ self._fresh = False
203
+ self._env = _Isaac.env
204
+ self._env.reset()
205
+ self._raw, _ = self._env.reset() # RoboLab's own double reset (robolab.eval.episode.run_episode)
206
+ # DroidJointposConverter takes (width, height), as LADDER's --image-size.
207
+ self._converter = DroidJointposConverter(num_envs=self.num_envs, image_size=(self._w, self._h))
208
+ return self._observations()
209
+
210
+ def _step(self, actions: list[Any]) -> list[Any]:
211
+ import omni.kit.app
212
+ import omni.timeline
213
+ import torch
214
+
215
+ joints = self._raw["proprio_obs"]["arm_joint_pos"].detach().cpu().numpy()
216
+ commands = self._converter.actions_to_jointpos(actions, joints)
217
+ timeline, kit = omni.timeline.get_timeline_interface(), omni.kit.app.get_app()
218
+ while not timeline.is_playing():
219
+ kit.update()
220
+ self._raw, _, _, _, _ = self._env.step(torch.as_tensor(commands, device=self._env.device))
221
+ return self._observations()
222
+
223
+ def _observations(self) -> list[Any]:
224
+ images, proprio = self._raw["image_obs"], self._raw["proprio_obs"]
225
+ results = self._env.get_env_results()
226
+ active = set(self._env.active_env_ids)
227
+ # During a step, _step_count is not yet incremented; LADDER's server counts the step first.
228
+ out_of_time = self._step_count + 1 >= int(self._env.max_episode_length)
229
+ achieved = None
230
+ if _Isaac.oracle:
231
+ achieved = [[bool(g.check(self._env, env_id=i)) for g in _Isaac.oracle] for i in range(self.num_envs)]
232
+ observations = []
233
+ for i in range(self.num_envs):
234
+ success = bool(results[i]["success"])
235
+ metadata = {
236
+ "env_name": self._class_name,
237
+ "robot_name": "franka",
238
+ "instruction": _Isaac.env_cfg.instruction,
239
+ "done": success,
240
+ "truncated": out_of_time or i not in active,
241
+ "oracle": {"achieved": achieved[i] if achieved is not None else [success]},
242
+ }
243
+ observations.append(
244
+ self._converter.observation_dict(
245
+ env_i=i,
246
+ main_image=images["over_shoulder_left_camera"][i].detach().cpu().numpy(),
247
+ wrist_image=images["wrist_cam"][i].detach().cpu().numpy(),
248
+ joints=proprio["arm_joint_pos"][i].detach().cpu().numpy(),
249
+ gripper_position=proprio["gripper_pos"][i].detach().cpu().numpy(),
250
+ metadata=metadata,
251
+ )
252
+ )
253
+ return observations
254
+
255
+
256
+ def vector_env_fns(
257
+ task: str = "",
258
+ n_envs: int = EPISODES_PER_TASK,
259
+ **options: Any,
260
+ ) -> dict[str, dict[int, Any]]:
261
+ """One factory per task, ``{task: {0: factory}}``: every task, or the comma-separated ``task``.
262
+
263
+ LeRobot builds only the tasks it runs (``--env.task``), so listing all 44 costs nothing.
264
+ """
265
+ names = lh.select_tasks(task, task_names())
266
+ _add_sources() # download before the server reports ready
267
+ return {name: {0: partial(RoboLabLong, name, n_envs, **options)} for name in names}
268
+
269
+
270
+ def make_env(n_envs: int = EPISODES_PER_TASK, use_async_envs: bool = False, task: str = "", **options: Any):
271
+ """One task as a batched vector env (``--env.use_native_batch``); LeRobot otherwise uses ``vector_env_fns``."""
272
+ name = lh.one_task(task, task_names())
273
+ return {name: {0: vector_env_fns(name, n_envs, **options)[name][0]()}}
ladder/components/inference/api/core/action.py ADDED
@@ -0,0 +1,228 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from dataclasses import dataclass
2
+ from enum import Enum
3
+ from typing import Any, Dict, List, Optional, Tuple
4
+
5
+ import numpy as np
6
+ import numpy.typing as npt
7
+
8
+ from ladder.components.inference.api.core.observation import EFFECTOR_NAMES
9
+
10
+
11
+ class ArmActionType(str, Enum):
12
+ NONE = "none"
13
+ JOINT_ANGLES = "joint_angles"
14
+ JOINT_VELOCITIES = "joint_velocities"
15
+ END_EFFECTOR_POSE = "end_effector_pose"
16
+
17
+
18
+ class EndEffectorPoseDeltaMode(str, Enum):
19
+ ROT_EEF_TRANS_BASE = "rot_eef_trans_base"
20
+ ROT_EEF_TRANS_EEF = "rot_eef_trans_eef"
21
+ ROT_EEF_BASE_ALIGNED_TRANS_BASE = "rot_eef_base_aligned_trans_base"
22
+
23
+
24
+ @dataclass(kw_only=True)
25
+ class ArmAction:
26
+ type: ArmActionType = ArmActionType.NONE
27
+
28
+ def __post_init__(self):
29
+ assert self.type != ArmActionType.NONE
30
+
31
+ @staticmethod
32
+ def from_dict(arm_action_dict: Dict[str, Any]) -> "ArmAction":
33
+ try:
34
+ action_type = ArmActionType(arm_action_dict["type"])
35
+ except KeyError:
36
+ raise ValueError("Action type not specified.")
37
+ except ValueError:
38
+ raise ValueError(f"Invalid action type. {arm_action_dict['type']}")
39
+
40
+ try:
41
+ action_cls = {
42
+ ArmActionType.JOINT_ANGLES: JointAnglesAction,
43
+ ArmActionType.JOINT_VELOCITIES: JointVelocitiesAction,
44
+ ArmActionType.END_EFFECTOR_POSE: EndEffectorPoseAction,
45
+ }.get(action_type)
46
+ except KeyError:
47
+ raise ValueError(f"No action class found for action type {action_type}")
48
+ return action_cls(**arm_action_dict)
49
+
50
+
51
+ @dataclass(kw_only=True)
52
+ class JointAnglesAction(ArmAction):
53
+ type: ArmActionType = ArmActionType.JOINT_ANGLES
54
+ angles: npt.NDArray[np.float32] # [num_dofs]
55
+
56
+
57
+ @dataclass(kw_only=True)
58
+ class JointVelocitiesAction(ArmAction):
59
+ type: ArmActionType = ArmActionType.JOINT_VELOCITIES
60
+ velocities: npt.NDArray[np.float32] # [num_dofs]
61
+
62
+
63
+ @dataclass(kw_only=True)
64
+ class EndEffectorPoseAction(ArmAction):
65
+ """
66
+ The end effector absolute pose is always with respect
67
+ to the robot base frame.
68
+ """
69
+
70
+ type: ArmActionType = ArmActionType.END_EFFECTOR_POSE
71
+ translation: npt.NDArray[np.float32] # [3]
72
+ rotation: npt.NDArray[np.float32] # [3, 3]
73
+
74
+ def __post_init__(self):
75
+ super().__post_init__()
76
+ assert self.rotation.shape == (3, 3)
77
+ assert self.translation.shape == (3,)
78
+
79
+ def to_homogeneous_matrix(self) -> npt.NDArray[np.float32]:
80
+ return np.block([[self.rotation, self.translation.reshape(3, 1)], [0, 0, 0, 1]])
81
+
82
+ @staticmethod
83
+ def from_homogeneous_matrix(matrix: npt.NDArray[np.float32]) -> "EndEffectorPoseAction":
84
+ return EndEffectorPoseAction(translation=matrix[:3, 3], rotation=matrix[:3, :3])
85
+
86
+ def apply_delta(
87
+ self,
88
+ delta_rotation: npt.NDArray[np.float32],
89
+ delta_translation: npt.NDArray[np.float32],
90
+ delta_mode: str | EndEffectorPoseDeltaMode,
91
+ ) -> "EndEffectorPoseAction":
92
+ """
93
+ Constructs a new pose action by applying a delta rotation and a delta translation
94
+ (in the specified reference frame) to the current end effector pose.
95
+
96
+ In the following we refer to `self.rotation` and `self.translation` as R_be and t_be.
97
+
98
+ Let [R_be, t_be] be the current rotation and translation of the end effector frame with respect
99
+ to the robot base frame, i.e. the arguments passed `apply_delta`.
100
+
101
+ Case 1: delta_mode == EndEffectorPoseDeltaMode.ROT_EEF_TRANS_BASE
102
+
103
+ The delta pose is [DR, Dt], where DR represents a rotations in the current end effector frame and
104
+ Dt represents a translation in the robot base frame.
105
+ Then, `apply_delta` will return:
106
+
107
+ [R, t] = [R_be @ DR, t_be + Dt]
108
+
109
+ Case 2: translation_reference_frame == EndEffectorPoseDeltaMode.ROT_EEF_TRANS_EEF
110
+
111
+ The delta pose is [R_e_e1, t_e], where t_e represents a translation in the end effector frame.
112
+ Then, `apply_delta` will return:
113
+
114
+ [R, t] = [R_be @ R_e_e1, t_be + R_be @ t_e]
115
+
116
+ Case 3: delta_mode == EndEffectorPoseDeltaMode.ROT_EEF_BASE_ALIGNED_TRANS_BASE
117
+
118
+ The delta pose is [DR, Dt], where DR represents a rotation in the axis aligned end effector
119
+ frame and Dt represents a translation in the robot base frame.
120
+
121
+ Then, `apply_delta` will return:
122
+
123
+ [R, t] = [DR @ R_be, t_be + Dt]
124
+
125
+ Args:
126
+ delta_rotation: The delta rotation of the end effector.
127
+ delta_translation: The delta translation of the end effector.
128
+ delta_mode: The mode of the delta pose.
129
+
130
+ Returns:
131
+ A new pose action representing the end effector pose after applying the delta pose.
132
+ """
133
+ delta_mode = EndEffectorPoseDeltaMode(delta_mode)
134
+
135
+ if delta_mode == EndEffectorPoseDeltaMode.ROT_EEF_TRANS_BASE:
136
+ rotation = self.rotation @ delta_rotation
137
+ translation = delta_translation + self.translation
138
+ elif delta_mode == EndEffectorPoseDeltaMode.ROT_EEF_TRANS_EEF:
139
+ rotation = self.rotation @ delta_rotation
140
+ translation = self.rotation @ delta_translation + self.translation
141
+ elif delta_mode == EndEffectorPoseDeltaMode.ROT_EEF_BASE_ALIGNED_TRANS_BASE:
142
+ rotation = delta_rotation @ self.rotation
143
+ translation = delta_translation + self.translation
144
+ else:
145
+ raise ValueError(f"Invalid delta mode: {delta_mode}")
146
+ return EndEffectorPoseAction(translation=translation, rotation=rotation)
147
+
148
+
149
+ class RobotActionType(str, Enum):
150
+ NONE = "none"
151
+ SINGLE_MANIPULATOR = "single_manipulator"
152
+ DUAL_MANIPULATOR = "dual_manipulator"
153
+
154
+
155
+ @dataclass(kw_only=True)
156
+ class RobotAction:
157
+ type: RobotActionType = RobotActionType.NONE
158
+
159
+ def __post_init__(self):
160
+ assert self.type != RobotActionType.NONE
161
+
162
+ @staticmethod
163
+ def from_dict(action_dict: Dict[str, Any]) -> "RobotAction":
164
+ try:
165
+ action_type = RobotActionType(action_dict["type"])
166
+ except KeyError:
167
+ raise ValueError("Robot action type not specified.")
168
+ except ValueError:
169
+ raise ValueError(f"Invalid robot action type. {action_dict['type']}")
170
+ action_cls = {
171
+ RobotActionType.SINGLE_MANIPULATOR: ManipulatorAction,
172
+ RobotActionType.DUAL_MANIPULATOR: DualManipulatorAction,
173
+ }.get(action_type)
174
+ if action_cls is None:
175
+ raise ValueError(f"No action class found for robot action type {action_type}")
176
+ return action_cls.from_dict(action_dict)
177
+
178
+
179
+ @dataclass(kw_only=True)
180
+ class ManipulatorAction(RobotAction):
181
+ """A single arm + its gripper (the former RobotAction)."""
182
+
183
+ type: RobotActionType = RobotActionType.SINGLE_MANIPULATOR
184
+ arm_action: Optional[ArmAction] = None
185
+ gripper_action: Optional[float] = None
186
+
187
+ def __post_init__(self):
188
+ super().__post_init__()
189
+ if self.arm_action is None and self.gripper_action is None:
190
+ raise ValueError("At least arm_action or gripper_action must be specified.")
191
+
192
+ @staticmethod
193
+ def from_dict(action_dict: Dict[str, Any]) -> "ManipulatorAction":
194
+ arm_action = None
195
+ if arm_action_dict := action_dict.get("arm_action", None):
196
+ arm_action = ArmAction.from_dict(arm_action_dict)
197
+ return ManipulatorAction(
198
+ arm_action=arm_action,
199
+ gripper_action=action_dict.get("gripper_action", None),
200
+ )
201
+
202
+
203
+ @dataclass(kw_only=True)
204
+ class DualManipulatorAction(RobotAction):
205
+ type: RobotActionType = RobotActionType.DUAL_MANIPULATOR
206
+ right: ManipulatorAction
207
+ left: ManipulatorAction
208
+
209
+ @staticmethod
210
+ def from_dict(action_dict: Dict[str, Any]) -> "DualManipulatorAction":
211
+ return DualManipulatorAction(
212
+ right=ManipulatorAction.from_dict(action_dict["right"]),
213
+ left=ManipulatorAction.from_dict(action_dict["left"]),
214
+ )
215
+
216
+
217
+ def effector_actions(action: RobotAction) -> List[ManipulatorAction]:
218
+ """One entry per effector, right before left, mirroring
219
+ :func:`ladder.components.inference.api.core.observation.effector_states`."""
220
+ if isinstance(action, DualManipulatorAction):
221
+ return [action.right, action.left]
222
+ assert isinstance(action, ManipulatorAction), f"{type(action).__name__} commands no manipulator"
223
+ return [action]
224
+
225
+
226
+ def named_effector_actions(action: RobotAction) -> List[Tuple[str, ManipulatorAction]]:
227
+ """:func:`effector_actions` paired with the effector names."""
228
+ return list(zip(EFFECTOR_NAMES, effector_actions(action), strict=False))
ladder/components/inference/api/core/instructions.py ADDED
@@ -0,0 +1,100 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import dataclasses
2
+ from collections import OrderedDict
3
+ from typing import List, Optional, Sequence, Tuple
4
+
5
+ IN = "in"
6
+ ON = "on"
7
+
8
+ _NUMBER = {
9
+ 1: "one",
10
+ 2: "two",
11
+ 3: "three",
12
+ 4: "four",
13
+ 5: "five",
14
+ 6: "six",
15
+ 7: "seven",
16
+ 8: "eight",
17
+ 9: "nine",
18
+ 10: "ten",
19
+ }
20
+
21
+
22
+ @dataclasses.dataclass(frozen=True)
23
+ class Placement:
24
+ """One leg: which object, and where it has to end up."""
25
+
26
+ noun: str
27
+ preposition: str # ON or IN, per the receptacle
28
+ receptacle: str
29
+
30
+
31
+ def _join(phrases: Sequence[str]) -> str:
32
+ if len(phrases) == 1:
33
+ return phrases[0]
34
+ return ", ".join(phrases[:-1]) + " and " + phrases[-1]
35
+
36
+
37
+ def _quantify(noun: str, count: int, definite: bool = True) -> str:
38
+ if not definite: # the same type is wanted in two places, so "the spoon" would name one twice
39
+ return f"{_NUMBER[count]} {noun}" + ("" if count == 1 else "s")
40
+ if count == 1:
41
+ return f"the {noun}"
42
+ if count == 2:
43
+ return f"both {noun}s"
44
+ return f"the {_NUMBER.get(count, str(count))} {noun}s"
45
+
46
+
47
+ def _clauses(placements: Sequence[Placement]) -> List[Tuple[str, str, str]]:
48
+ """(objects, preposition, receptacle) per destination, in first-mention order."""
49
+ grouped: "OrderedDict[Tuple[str, str], OrderedDict[str, int]]" = OrderedDict()
50
+ for p in placements:
51
+ key = (p.receptacle, p.preposition)
52
+ grouped.setdefault(key, OrderedDict())
53
+ grouped[key][p.noun] = grouped[key].get(p.noun, 0) + 1
54
+ spread = {
55
+ noun
56
+ for noun in {n for counts in grouped.values() for n in counts}
57
+ if sum(noun in counts for counts in grouped.values()) > 1
58
+ }
59
+ return [
60
+ (_join([_quantify(n, c, n not in spread) for n, c in counts.items()]), preposition, receptacle)
61
+ for (receptacle, preposition), counts in grouped.items()
62
+ ]
63
+
64
+
65
+ def compose(
66
+ placements: Sequence[Placement],
67
+ *,
68
+ sequential: bool = False,
69
+ source: Optional[str] = None,
70
+ excluded: Sequence[str] = (),
71
+ ) -> str:
72
+ """A composition task's instruction, in the style all three benchmarks share.
73
+
74
+ Objects are named except where the task hands the system objects to leave alone: resolving
75
+ "everything except the red block" against the scene is what a scope task tests, while a bare
76
+ "everything" reads the same at two objects as at ten. ``sequential`` keeps one clause per leg,
77
+ for a task scored on the order or on the route taken.
78
+ """
79
+ if excluded:
80
+ counts: "OrderedDict[str, int]" = OrderedDict()
81
+ for noun in excluded:
82
+ counts[noun] = counts.get(noun, 0) + 1
83
+ what = "everything except " + _join([_quantify(n, c) for n, c in counts.items()])
84
+ _, preposition, receptacle = _clauses(placements)[0]
85
+ body = f"put {what} {preposition} the {receptacle}"
86
+ elif source is not None:
87
+ what, _, receptacle = _clauses(placements)[0]
88
+ body = f"move {what} from the {source} to the {receptacle}"
89
+ elif sequential:
90
+ steps = [f"put the {p.noun} {p.preposition} the {p.receptacle}" for p in placements]
91
+ body = steps[0] if len(steps) == 1 else "first " + ", then ".join(steps)
92
+ else:
93
+ body = _join([f"put {what} {prep} the {where}" for what, prep, where in _clauses(placements)])
94
+ # A one-leg task's instruction IS its only subtask, so the two match rather than differ by a stop.
95
+ return f"{body}." if len(placements) == 1 else body
96
+
97
+
98
+ def subtask(placement: Placement) -> str:
99
+ """One commanded goal, the unit an orchestrator hands the policy."""
100
+ return compose([placement])
ladder/components/inference/api/core/observation.py ADDED
@@ -0,0 +1,166 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import dataclasses
2
+ import functools
3
+ from enum import Enum
4
+ from typing import Any, Dict, List, Optional, Tuple
5
+
6
+ import numpy as np
7
+ import numpy.typing as npt
8
+
9
+
10
+ class RobotStateType(str, Enum):
11
+ NONE = "none"
12
+ SINGLE_MANIPULATOR = "single_manipulator"
13
+ DUAL_MANIPULATOR = "dual_manipulator"
14
+
15
+
16
+ @dataclasses.dataclass(kw_only=True, frozen=True)
17
+ class RobotState:
18
+ type: RobotStateType = RobotStateType.NONE
19
+
20
+ def __post_init__(self):
21
+ assert self.type != RobotStateType.NONE
22
+
23
+ @staticmethod
24
+ def from_dict(state_dict: Dict[str, Any]) -> "RobotState":
25
+ try:
26
+ state_type = RobotStateType(state_dict["type"])
27
+ except KeyError:
28
+ raise ValueError("Robot state type not specified.")
29
+ except ValueError:
30
+ raise ValueError(f"Invalid robot state type. {state_dict['type']}")
31
+ state_cls = {
32
+ RobotStateType.SINGLE_MANIPULATOR: ManipulatorState,
33
+ RobotStateType.DUAL_MANIPULATOR: DualManipulatorState,
34
+ }.get(state_type)
35
+ if state_cls is None:
36
+ raise ValueError(f"No state class found for robot state type {state_type}")
37
+ return state_cls.from_dict(state_dict)
38
+
39
+
40
+ @dataclasses.dataclass(kw_only=True, frozen=True)
41
+ class ManipulatorState(RobotState):
42
+ """State of a single arm + its gripper (the former flat RobotObservation fields)."""
43
+
44
+ type: RobotStateType = RobotStateType.SINGLE_MANIPULATOR
45
+ eef_pose: Optional[npt.NDArray[np.float32]] = None # [4, 4]
46
+ eef_pose_from_target: Optional[npt.NDArray[np.float32]] = None # [4, 4]
47
+ gripper_state: Optional[npt.NDArray[np.float32]] = None # [1]
48
+ joints: Optional[npt.NDArray[np.float32]] = None # [num_dofs]
49
+
50
+ @staticmethod
51
+ def from_dict(state_dict: Dict[str, Any]) -> "ManipulatorState":
52
+ return ManipulatorState(
53
+ eef_pose=state_dict.get("eef_pose"),
54
+ eef_pose_from_target=state_dict.get("eef_pose_from_target"),
55
+ gripper_state=state_dict.get("gripper_state"),
56
+ joints=state_dict.get("joints"),
57
+ )
58
+
59
+
60
+ @dataclasses.dataclass(kw_only=True, frozen=True)
61
+ class DualManipulatorState(RobotState):
62
+ type: RobotStateType = RobotStateType.DUAL_MANIPULATOR
63
+ right: ManipulatorState
64
+ left: ManipulatorState
65
+
66
+ @staticmethod
67
+ def from_dict(state_dict: Dict[str, Any]) -> "DualManipulatorState":
68
+ return DualManipulatorState(
69
+ right=ManipulatorState.from_dict(state_dict["right"]),
70
+ left=ManipulatorState.from_dict(state_dict["left"]),
71
+ )
72
+
73
+
74
+ EFFECTOR_NAMES: Tuple[str, ...] = ("right", "left")
75
+
76
+
77
+ def effector_states(state: RobotState) -> List[ManipulatorState]:
78
+ """One entry per effector. A single manipulator is one effector"""
79
+ if isinstance(state, DualManipulatorState):
80
+ return [state.right, state.left]
81
+ assert isinstance(
82
+ state, ManipulatorState
83
+ ), f"{type(state).__name__} carries no manipulator to drive a VLAM with"
84
+ return [state]
85
+
86
+
87
+ def named_effector_states(state: RobotState) -> List[Tuple[str, ManipulatorState]]:
88
+ """:func:`effector_states` paired with :data:`EFFECTOR_NAMES`, so a single arm is ``right``."""
89
+ return list(zip(EFFECTOR_NAMES, effector_states(state), strict=False))
90
+
91
+
92
+ @dataclasses.dataclass(kw_only=True, frozen=True)
93
+ class RobotObservation:
94
+ images: Optional[Dict[str, npt.NDArray[np.uint8]]] # images are [h, w, c]
95
+ state: RobotState
96
+ timestamps: Optional[npt.NDArray[np.float64]] # [1]
97
+ metadata: Dict[str, Any] = dataclasses.field(default_factory=dict)
98
+
99
+ @staticmethod
100
+ def from_dict(obs_dict: Dict[str, Any]) -> "RobotObservation":
101
+ return RobotObservation(
102
+ images=obs_dict.get("images"),
103
+ state=RobotState.from_dict(obs_dict["state"]),
104
+ timestamps=obs_dict.get("timestamps"),
105
+ metadata=obs_dict.get("metadata", {}),
106
+ )
107
+
108
+ @functools.cached_property
109
+ def cameras(self) -> Dict[str, "CameraFrame"]:
110
+ """The depth cameras, decoded from the plain dicts that crossed the msgpack wire."""
111
+ payload = self.metadata.get(METADATA_CAMERAS_KEY) or {}
112
+ return {
113
+ str(name): CameraFrame(
114
+ depth_m=np.asarray(raw["depth_m"], dtype=np.float32),
115
+ intrinsics=np.asarray(raw["intrinsics"], dtype=np.float64).reshape(3, 3),
116
+ base_from_camera=np.asarray(raw["base_from_camera"], dtype=np.float64).reshape(4, 4),
117
+ )
118
+ for name, raw in payload.items()
119
+ }
120
+
121
+
122
+ # Camera frames in ``RobotObservation.metadata``, keyed by camera name.
123
+ METADATA_CAMERAS_KEY = "cameras"
124
+
125
+
126
+ def encode_camera(depth_m: Any, intrinsics: Any, base_from_camera: Any) -> Dict[str, Any]:
127
+ """One depth camera's frame and calibration, for ``METADATA_CAMERAS_KEY``.
128
+
129
+ ``depth_m`` is metres along the optical axis (not ray length), NaN where the sensor returned
130
+ nothing. ``intrinsics`` is a 3x3 pinhole matrix in pixels, OpenCV convention (+Z forward, +Y
131
+ down). ``base_from_camera`` takes camera points into the frame the policy commands in.
132
+ """
133
+ return {
134
+ "depth_m": np.asarray(depth_m, dtype=np.float32),
135
+ "intrinsics": np.asarray(intrinsics, dtype=np.float32).reshape(3, 3),
136
+ "base_from_camera": np.asarray(base_from_camera, dtype=np.float32).reshape(4, 4),
137
+ }
138
+
139
+
140
+ @dataclasses.dataclass(frozen=True)
141
+ class CameraFrame:
142
+ depth_m: np.ndarray # [H, W] float32 metres, NaN where invalid
143
+ intrinsics: np.ndarray # [3, 3] pinhole, pixels
144
+ base_from_camera: np.ndarray # [4, 4] camera frame into the canonical robot base frame
145
+
146
+ @property
147
+ def shape(self) -> tuple:
148
+ return tuple(np.asarray(self.depth_m).shape[:2])
149
+
150
+ def unproject_camera(self, pixels_xy: np.ndarray) -> np.ndarray:
151
+ """Points in the camera's own frame, which is the frame a grasp sampler works in."""
152
+ pixels = np.asarray(pixels_xy, dtype=np.float64).reshape(-1, 2)
153
+ depth = np.asarray(self.depth_m, dtype=np.float64)
154
+ columns = np.clip(np.round(pixels[:, 0]).astype(int), 0, depth.shape[1] - 1)
155
+ rows = np.clip(np.round(pixels[:, 1]).astype(int), 0, depth.shape[0] - 1)
156
+ z = depth[rows, columns]
157
+ intrinsics = np.asarray(self.intrinsics, dtype=np.float64)
158
+ fx, fy = intrinsics[0, 0], intrinsics[1, 1]
159
+ cx, cy = intrinsics[0, 2], intrinsics[1, 2]
160
+ camera = np.stack([(pixels[:, 0] - cx) * z / fx, (pixels[:, 1] - cy) * z / fy, z], axis=1)
161
+ return np.where((np.isfinite(z) & (z > 0.0))[:, None], camera, np.nan)
162
+
163
+ def unproject(self, pixels_xy: np.ndarray) -> np.ndarray:
164
+ camera = self.unproject_camera(pixels_xy)
165
+ transform = np.asarray(self.base_from_camera, dtype=np.float64)
166
+ return camera @ transform[:3, :3].T + transform[:3, 3]
ladder/components/inference/api/core/privileged_geometry.py ADDED
@@ -0,0 +1,218 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from typing import Any, Dict, List, Optional, Sequence, Tuple
2
+
3
+ import numpy as np
4
+
5
+ from ladder.components.inference.api.core.privileged_state import (
6
+ encode_condition,
7
+ encode_object,
8
+ encode_state,
9
+ )
10
+
11
+ _NEIGHBOUR_GAP_M = 0.005 # so two objects sharing a destination do not touch
12
+ _IN_CLEARANCE_M = 0.005 # drop height above a container's floor
13
+
14
+
15
+ def to_base(world_to_base: np.ndarray, points: np.ndarray) -> np.ndarray:
16
+ """Map world-frame points ``[..., 3]`` into the robot base frame the policy commands in."""
17
+ flat = np.asarray(points, dtype=np.float64).reshape(-1, 3)
18
+ homogeneous = np.concatenate([flat, np.ones((len(flat), 1))], axis=1)
19
+ return (homogeneous @ np.asarray(world_to_base, dtype=np.float64).T)[:, :3].reshape(points.shape)
20
+
21
+
22
+ def spread_offsets(
23
+ half_extents: Sequence[np.ndarray], dest_half: np.ndarray
24
+ ) -> Tuple[np.ndarray, np.ndarray]:
25
+ """Where to lay N objects on one destination, as XY offsets plus the layer each one sits in.
26
+
27
+ Piling is a real failure mode: every arrival dropped on the same point knocks the last one off.
28
+ The constraint is each object's FOOTPRINT, not its centre. A grid that only keeps centres
29
+ inside the destination still aims every object so its own body overhangs the rim, which for a
30
+ container means setting it down on the wall, where a delivery is credited and then lost.
31
+
32
+ When a grid sized for the largest object cannot hold them all, each object's own footprint is
33
+ laid in rows along the destination's longer side instead, and what still does not fit piles on
34
+ the floor. Stacked layers are avoided because they aim each later arrival higher above the
35
+ destination, and an object dropped from that height bounces out of a container.
36
+ """
37
+ count = len(half_extents)
38
+ offsets = np.zeros((count, 2))
39
+ layers = np.zeros(count, dtype=int)
40
+ if count <= 1:
41
+ return offsets, layers
42
+
43
+ source_half = np.array([max(h[0] for h in half_extents), max(h[1] for h in half_extents)])
44
+ step = 2.0 * source_half + _NEIGHBOUR_GAP_M
45
+ # The centre of an object at the extreme cell must sit this far in for its edge to clear the rim.
46
+ usable = np.maximum(np.asarray(dest_half[:2], dtype=np.float64) - _NEIGHBOUR_GAP_M - source_half, 0.0)
47
+ cells = np.maximum(np.floor(2.0 * usable / step).astype(int) + 1, 1)
48
+
49
+ per_layer = int(cells[0] * cells[1])
50
+ if count > per_layer:
51
+ return _row_offsets(half_extents, np.asarray(dest_half[:2], dtype=np.float64)), layers
52
+ for index in range(count):
53
+ cell, layers[index] = index % per_layer, index // per_layer
54
+ grid_xy = np.array([cell % cells[0], cell // cells[0]], dtype=np.float64)
55
+ offsets[index] = (grid_xy - (cells - 1) / 2.0) * step
56
+ return offsets, layers
57
+
58
+
59
+ def _row_offsets(half_extents: Sequence[np.ndarray], dest_half: np.ndarray) -> np.ndarray:
60
+ """XY offsets laying each object's own footprint in rows along ``dest_half``'s longer axis."""
61
+ along = 0 if dest_half[0] >= dest_half[1] else 1
62
+ across = 1 - along
63
+ length = 2.0 * float(dest_half[along]) - _NEIGHBOUR_GAP_M
64
+ rows: List[List[int]] = [[]]
65
+ used = 0.0
66
+ for index, half in enumerate(half_extents):
67
+ width = 2.0 * float(half[along]) + _NEIGHBOUR_GAP_M
68
+ if rows[-1] and used + width > length:
69
+ rows.append([])
70
+ used = 0.0
71
+ rows[-1].append(index)
72
+ used += width
73
+ depths = [max(2.0 * float(half_extents[i][across]) for i in row) + _NEIGHBOUR_GAP_M for row in rows]
74
+ offsets = np.zeros((len(half_extents), 2))
75
+ row_start = -0.5 * sum(depths)
76
+ for row, depth in zip(rows, depths, strict=True):
77
+ widths = [2.0 * float(half_extents[i][along]) + _NEIGHBOUR_GAP_M for i in row]
78
+ start = -0.5 * sum(widths)
79
+ for index, width in zip(row, widths, strict=True):
80
+ offsets[index, along] = start + 0.5 * width
81
+ offsets[index, across] = row_start + 0.5 * depth
82
+ start += width
83
+ row_start += depth
84
+ # Rows past the destination's edge are pulled back in: those objects pile on the others.
85
+ limit = np.maximum(dest_half[None, :] - np.asarray(half_extents)[:, :2] - _NEIGHBOUR_GAP_M, 0.0)
86
+ return np.clip(offsets, -limit, limit)
87
+
88
+
89
+ def goal_point(
90
+ relation: str,
91
+ dest_center: np.ndarray,
92
+ dest_min: np.ndarray,
93
+ dest_max: np.ndarray,
94
+ source_half: np.ndarray,
95
+ offset_xy: np.ndarray,
96
+ layer: int = 0,
97
+ ) -> Tuple[np.ndarray, float]:
98
+ """Where a source object's CENTRE must end up, and the EEF height to release it at.
99
+
100
+ ``on`` rests it on the destination's top face; ``in`` drops it just above the floor of the
101
+ container, which is what ``is_inside`` scores. Those differ for a walled destination: the object
102
+ must END at the floor, but it must be RELEASED above the rim, since carrying it down inside fouls the
103
+ gripper on the wall and on anything already delivered. Releasing above the rim lets it fall the
104
+ last centimetres, which is how the container gets loaded.
105
+ """
106
+ # "on" rests the object on the top face; "in" aims just above the container's AABB floor,
107
+ # which ``is_inside`` credits.
108
+ rim_z = float(dest_max[2]) + float(source_half[2])
109
+ z = rim_z
110
+ if relation == "in":
111
+ z = float(dest_min[2]) + float(source_half[2]) + _IN_CLEARANCE_M
112
+ # A stacked layer rests on the layer below it.
113
+ z += layer * 2.0 * float(source_half[2])
114
+ point = np.array([dest_center[0] + offset_xy[0], dest_center[1] + offset_xy[1], z], dtype=np.float32)
115
+ return point, max(rim_z, z)
116
+
117
+
118
+ def build_payloads(
119
+ *,
120
+ names: Sequence[str],
121
+ centers: np.ndarray,
122
+ mins: np.ndarray,
123
+ maxs: np.ndarray,
124
+ grasped: np.ndarray,
125
+ goals: Sequence[Dict[str, Any]],
126
+ n_envs: int,
127
+ long_axis_yaws: Optional[np.ndarray] = None,
128
+ ) -> List[Dict[str, Any]]:
129
+ """One privileged payload per env. Arrays are ``[n_objects, n_envs, 3]`` in the base frame.
130
+
131
+ Each entry of ``goals`` is ``{"source": idx, "destination": idx | None, "relation": str,
132
+ "satisfied": [n_envs] bool}``, optionally with ``"predicate"`` (default ``"pick_and_place"``;
133
+ ``pickup``/``grasp``/``reach`` end the motion early) and ``"point"``, an explicit goal
134
+ position, ``[3]`` or ``[n_envs, 3]``, for a goal whose destination is a place rather than an
135
+ object, which is how a region or a relative-placement task states where the object must end up.
136
+ """
137
+ halves = 0.5 * (maxs - mins)
138
+ per_destination: Dict[Optional[int], List[int]] = {}
139
+ for index, goal in enumerate(goals):
140
+ per_destination.setdefault(goal["destination"], []).append(index)
141
+
142
+ last_destination = {goal["source"]: goal["destination"] for goal in goals}
143
+
144
+ payloads = []
145
+ for env in range(n_envs):
146
+ offsets = {}
147
+ for destination, indices in per_destination.items():
148
+ if destination is None:
149
+ continue
150
+ # One slot per object, not per goal: a relay or revisit brings the same object back to
151
+ # the same destination, and a slot of its own per visit aims it at the rim. Only objects
152
+ # left here need slots side by side; when every visitor moves on again (a relay's pot),
153
+ # they are there one at a time, so each takes the centre.
154
+ sources = list(dict.fromkeys(goals[i]["source"] for i in indices))
155
+ if not any(last_destination[source] == destination for source in sources):
156
+ offsets.update({i: (np.zeros(2), 0) for i in indices})
157
+ continue
158
+ spread, layers = spread_offsets(
159
+ [halves[source, env] for source in sources], halves[destination, env]
160
+ )
161
+ slots = dict(zip(sources, zip(spread, layers, strict=True), strict=True))
162
+ offsets.update({i: slots[goals[i]["source"]] for i in indices})
163
+
164
+ conditions = []
165
+ for index, goal in enumerate(goals):
166
+ source = goal["source"]
167
+ target = encode_object(
168
+ names[source],
169
+ centers[source, env],
170
+ mins[source, env],
171
+ maxs[source, env],
172
+ display_name=names[source],
173
+ grasped=bool(grasped[source, env]),
174
+ long_axis_yaw_rad=(None if long_axis_yaws is None else float(long_axis_yaws[source, env])),
175
+ )
176
+ destination = goal["destination"]
177
+ point, release_z = None, None
178
+ explicit = goal.get("point")
179
+ if explicit is not None:
180
+ explicit = np.asarray(explicit, dtype=np.float64)
181
+ point = explicit[env] if explicit.ndim == 2 else explicit
182
+ release_z = float(point[2])
183
+ elif destination is not None:
184
+ point, release_z = goal_point(
185
+ goal["relation"],
186
+ centers[destination, env],
187
+ mins[destination, env],
188
+ maxs[destination, env],
189
+ halves[source, env],
190
+ offsets[index][0],
191
+ layer=int(offsets[index][1]),
192
+ )
193
+ conditions.append(
194
+ encode_condition(
195
+ goal.get("predicate", "pick_and_place"),
196
+ target,
197
+ relation=goal["relation"],
198
+ goal_point_m=point,
199
+ release_z_m=release_z,
200
+ destination=(names[destination] if destination is not None else None),
201
+ grasped=bool(grasped[source, env]),
202
+ satisfied=bool(goal["satisfied"][env]),
203
+ )
204
+ )
205
+ objects = [
206
+ encode_object(
207
+ name,
208
+ centers[i, env],
209
+ mins[i, env],
210
+ maxs[i, env],
211
+ display_name=name,
212
+ grasped=bool(grasped[i, env]),
213
+ long_axis_yaw_rad=(None if long_axis_yaws is None else float(long_axis_yaws[i, env])),
214
+ )
215
+ for i, name in enumerate(names)
216
+ ]
217
+ payloads.append(encode_state(conditions, objects))
218
+ return payloads
ladder/components/inference/api/core/privileged_state.py ADDED
@@ -0,0 +1,192 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import dataclasses
2
+ from typing import Any, Dict, List, Optional
3
+
4
+ import numpy as np
5
+
6
+ # Key under which the privileged payload lives in ``observation.metadata``.
7
+ METADATA_PRIVILEGED_KEY = "privileged"
8
+
9
+
10
+ @dataclasses.dataclass(frozen=True)
11
+ class PrivilegedObject:
12
+ """A scene object's ground-truth geometry in the canonical base frame."""
13
+
14
+ name: str
15
+ center_m: np.ndarray # [3] object center (canonical frame)
16
+ aabb_min_m: np.ndarray # [3] axis-aligned bounding-box min corner
17
+ aabb_max_m: np.ndarray # [3] axis-aligned bounding-box max corner
18
+ # Name as the instructions refer to it, for grounding a free-text subtask.
19
+ display_name: str = ""
20
+ grasped: bool = False # privileged: is THIS object currently grasped
21
+ # Direction of the object's longest horizontal extent (radians about base Z, modulo pi), where the
22
+ # server publishes it. The AABB cannot say it for an object lying diagonally.
23
+ long_axis_yaw_rad: Optional[float] = None
24
+
25
+ @property
26
+ def top_z_m(self) -> float:
27
+ """Z of the object's top surface (for placing another object on it)."""
28
+ return float(self.aabb_max_m[2])
29
+
30
+ @property
31
+ def half_extent_m(self) -> np.ndarray:
32
+ return 0.5 * (self.aabb_max_m - self.aabb_min_m)
33
+
34
+ @property
35
+ def height_m(self) -> float:
36
+ return float(self.aabb_max_m[2] - self.aabb_min_m[2])
37
+
38
+
39
+ @dataclasses.dataclass(frozen=True)
40
+ class PrivilegedCondition:
41
+ """One success condition with its target/goal resolved to ground truth.
42
+
43
+ A canonical (single-condition) task has exactly one of these; a long-horizon
44
+ task has one per sub-goal, evaluated in order against ``satisfied``.
45
+ """
46
+
47
+ predicate: str # e.g. "pick_and_place", "stack", "reach", "pickup"
48
+ relation: Optional[str] # "on" | "in" | "left" | ... | None
49
+ target: PrivilegedObject
50
+ # Where the target's centre must end up, base frame. None for reach/grasp/pickup.
51
+ goal_point_m: Optional[np.ndarray]
52
+ grasped: bool # privileged: is the target currently grasped
53
+ satisfied: bool # privileged: does this condition currently hold
54
+ # Lowest release height clearing the destination's walls; above the rim for a walled one,
55
+ # so the object falls in rather than the gripper reaching down inside.
56
+ release_z_m: Optional[float] = None
57
+ # The scene object the target must end up on or in, by name; None for a goal stated as a point.
58
+ destination: Optional[str] = None
59
+
60
+
61
+ @dataclasses.dataclass(frozen=True)
62
+ class PrivilegedState:
63
+ conditions: List[PrivilegedCondition]
64
+ # Every scene object, for grounding a subtask in ``subtask`` mode. Empty when structured.
65
+ objects: List[PrivilegedObject] = dataclasses.field(default_factory=list)
66
+
67
+ def first_unsatisfied(self) -> Optional[PrivilegedCondition]:
68
+ """The first condition not yet satisfied (drives sequential execution)."""
69
+ for condition in self.conditions:
70
+ if not condition.satisfied:
71
+ return condition
72
+ return None
73
+
74
+ def find_object(self, phrase: str) -> Optional[PrivilegedObject]:
75
+ """Resolve a noun phrase from a subtask to a scene object by display name.
76
+
77
+ Prefers an exact display-name match, then the longest display name contained in the phrase
78
+ (so "green block" beats "block"). Returns ``None`` if nothing matches.
79
+ """
80
+ text = phrase.strip().lower()
81
+ exact = [o for o in self.objects if o.display_name and o.display_name.lower() == text]
82
+ if exact:
83
+ return exact[0]
84
+ contained = [o for o in self.objects if o.display_name and o.display_name.lower() in text]
85
+ if contained:
86
+ return max(contained, key=lambda o: len(o.display_name))
87
+ return None
88
+
89
+
90
+ def _arr(value: Any) -> np.ndarray:
91
+ return np.asarray(value, dtype=np.float64).reshape(-1)
92
+
93
+
94
+ def _object_from_dict(data: Dict[str, Any]) -> PrivilegedObject:
95
+ return PrivilegedObject(
96
+ name=str(data["name"]),
97
+ center_m=_arr(data["center_m"]),
98
+ aabb_min_m=_arr(data["aabb_min_m"]),
99
+ aabb_max_m=_arr(data["aabb_max_m"]),
100
+ display_name=str(data.get("display_name", "")),
101
+ grasped=bool(data.get("grasped", False)),
102
+ long_axis_yaw_rad=(
103
+ float(data["long_axis_yaw_rad"]) if data.get("long_axis_yaw_rad") is not None else None
104
+ ),
105
+ )
106
+
107
+
108
+ def from_metadata(metadata: Optional[Dict[str, Any]]) -> Optional[PrivilegedState]:
109
+ """Parse the privileged payload from observation metadata, or ``None`` if absent.
110
+
111
+ ``None`` lets the policy fail loudly when privileged state was expected but the
112
+ server did not emit it (a misconfiguration), rather than silently no-op.
113
+ """
114
+ if not metadata:
115
+ return None
116
+ payload = metadata.get(METADATA_PRIVILEGED_KEY)
117
+ if not payload:
118
+ return None
119
+ conditions: List[PrivilegedCondition] = []
120
+ for raw in payload["conditions"]:
121
+ goal = raw.get("goal_point_m")
122
+ conditions.append(
123
+ PrivilegedCondition(
124
+ predicate=str(raw["predicate"]),
125
+ relation=(str(raw["relation"]) if raw.get("relation") is not None else None),
126
+ target=_object_from_dict(raw["target"]),
127
+ goal_point_m=(_arr(goal) if goal is not None else None),
128
+ release_z_m=(float(raw["release_z_m"]) if raw.get("release_z_m") is not None else None),
129
+ destination=(str(raw["destination"]) if raw.get("destination") else None),
130
+ grasped=bool(raw["grasped"]),
131
+ satisfied=bool(raw["satisfied"]),
132
+ )
133
+ )
134
+ objects = [_object_from_dict(o) for o in payload.get("objects", [])]
135
+ return PrivilegedState(conditions=conditions, objects=objects)
136
+
137
+
138
+ def encode_object(
139
+ name: str,
140
+ center_m: np.ndarray,
141
+ aabb_min_m: np.ndarray,
142
+ aabb_max_m: np.ndarray,
143
+ *,
144
+ display_name: str = "",
145
+ grasped: bool = False,
146
+ long_axis_yaw_rad: Optional[float] = None,
147
+ ) -> Dict[str, Any]:
148
+ """Build the msgpack-safe dict for one object (poses in canonical frame)."""
149
+ encoded = {
150
+ "name": str(name),
151
+ "center_m": np.asarray(center_m, dtype=np.float32).reshape(3),
152
+ "aabb_min_m": np.asarray(aabb_min_m, dtype=np.float32).reshape(3),
153
+ "aabb_max_m": np.asarray(aabb_max_m, dtype=np.float32).reshape(3),
154
+ "display_name": str(display_name),
155
+ "grasped": bool(grasped),
156
+ }
157
+ if long_axis_yaw_rad is not None and np.isfinite(long_axis_yaw_rad):
158
+ encoded["long_axis_yaw_rad"] = float(long_axis_yaw_rad)
159
+ return encoded
160
+
161
+
162
+ def encode_condition(
163
+ predicate: str,
164
+ target: Dict[str, Any],
165
+ *,
166
+ relation: Optional[str] = None,
167
+ goal_point_m: Optional[np.ndarray] = None,
168
+ release_z_m: Optional[float] = None,
169
+ destination: Optional[str] = None,
170
+ grasped: bool = False,
171
+ satisfied: bool = False,
172
+ ) -> Dict[str, Any]:
173
+ """Build the msgpack-safe dict for one success condition."""
174
+ return {
175
+ "predicate": str(predicate),
176
+ "relation": (str(relation) if relation is not None else None),
177
+ "target": target,
178
+ "goal_point_m": (
179
+ None if goal_point_m is None else np.asarray(goal_point_m, dtype=np.float32).reshape(3)
180
+ ),
181
+ "release_z_m": (None if release_z_m is None else float(release_z_m)),
182
+ "destination": (str(destination) if destination is not None else None),
183
+ "grasped": bool(grasped),
184
+ "satisfied": bool(satisfied),
185
+ }
186
+
187
+
188
+ def encode_state(
189
+ conditions: List[Dict[str, Any]], objects: Optional[List[Dict[str, Any]]] = None
190
+ ) -> Dict[str, Any]:
191
+ """Build the full privileged payload for ``metadata[METADATA_PRIVILEGED_KEY]``."""
192
+ return {"conditions": list(conditions), "objects": list(objects or [])}
ladder/components/inference/api/core/request_reply.py ADDED
@@ -0,0 +1,262 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from abc import abstractmethod
2
+ from typing import Any, Dict, Optional, TypeVar
3
+
4
+ import zmq
5
+ from typing_extensions import Protocol
6
+
7
+ from ladder.components.inference.api.core.requests import RequestType, parse_request_type
8
+ from ladder.components.inference.api.core.serialization import deserialize, serialize
9
+ from ladder.core.common.logger import get_logger
10
+ from ladder.core.databib.config import Config, Configurable
11
+
12
+ LOGGER = get_logger(__name__)
13
+
14
+
15
+ class CallbackProtocol(Protocol):
16
+ def __call__(self, message: Dict) -> Dict:
17
+ ...
18
+
19
+
20
+ class RequestReplyServerConfig(Config):
21
+ pass
22
+
23
+
24
+ RequestReplyServerConfigT = TypeVar('RequestReplyServerConfigT', bound=RequestReplyServerConfig)
25
+
26
+
27
+ class RequestReplyServer(Configurable[RequestReplyServerConfigT]):
28
+ """
29
+ Abstract base class for a request-reply server that listens
30
+ for requests, dispatches them to the provided callback, and
31
+ sends the output back to the client.
32
+
33
+ Methods:
34
+ start(on_request_cb: CallbackProtocol): Begins listening for requests
35
+ """
36
+
37
+ @abstractmethod
38
+ def start(self, on_request_cb: CallbackProtocol) -> None:
39
+ pass
40
+
41
+
42
+ class RequestReplyClientConfig(Config):
43
+ pass
44
+
45
+
46
+ RequestReplyClientConfigT = TypeVar('RequestReplyClientConfigT', bound=RequestReplyClientConfig)
47
+
48
+
49
+ class RequestReplyClient(Configurable[RequestReplyClientConfigT]):
50
+ """
51
+ Abstract base class for a request-reply client that sends
52
+ requests to the server and receives the output from the server.
53
+
54
+ Methods:
55
+ send(request: Dict) -> Optional[Dict]: Send a request to the server.
56
+ """
57
+
58
+ @abstractmethod
59
+ def send(self, request: Dict[str, Any]) -> Optional[Dict[str, Any]]:
60
+ pass
61
+
62
+
63
+ class ZmqRequestReplyServerConfig(RequestReplyServerConfig):
64
+ port: int # Port number to listen on
65
+ recv_timeout_ms: int = 5000 # Timeout in milliseconds for calls to socket.recv
66
+
67
+
68
+ class ZmqRequestReplyServer(RequestReplyServer[ZmqRequestReplyServerConfig]):
69
+ """
70
+ ZeroMQ-based implementation of RequestReplyServer.
71
+
72
+ Methods:
73
+ start(on_request_cb: CallbackProtocol): Begins listening for requests.
74
+
75
+ Notes:
76
+ Designed to be used in conjunction with the ZmqRequestReplyClient class.
77
+ """
78
+
79
+ def __init__(self, config: ZmqRequestReplyServerConfig):
80
+ super().__init__(config)
81
+ self._context = zmq.Context()
82
+ self._init_socket()
83
+
84
+ def _init_socket(self):
85
+ self.socket = self._context.socket(zmq.REP)
86
+ self.socket.bind(f"tcp://*:{self.config.port}")
87
+ self.socket.setsockopt(zmq.SNDHWM, 5)
88
+ self.socket.setsockopt(zmq.LINGER, 0)
89
+ self.socket.setsockopt(zmq.RCVTIMEO, self.config.recv_timeout_ms)
90
+
91
+ def start(self, on_request_cb: CallbackProtocol) -> None:
92
+ """
93
+ Starts listening for requests over the socket, blocking on the current thread.
94
+ When a request is received, the on_request_cb function is called with the request
95
+ as an argument, and the output is sent back as a reply to the client.
96
+
97
+ Args:
98
+ on_request_cb (CallbackProtocol): Function to be called when a request is received.
99
+
100
+ Notes: this function is blocking
101
+ """
102
+ LOGGER.info("Starting ZMQ request reply server")
103
+ while True:
104
+ LOGGER.debug("Waiting for new request")
105
+ try:
106
+ message = self.socket.recv()
107
+ except zmq.Again:
108
+ LOGGER.warn("ZMQ receive timeout. Continuing.")
109
+ continue
110
+ except zmq.ZMQError as e:
111
+ LOGGER.error(f"A ZMQ error occured while receiving. Error: {e}")
112
+ raise e
113
+ LOGGER.debug(f"Received new request")
114
+
115
+ LOGGER.debug(f"Processing new request")
116
+ message = deserialize(message)
117
+ res = on_request_cb(message)
118
+ res = serialize(res)
119
+ LOGGER.debug(f"Request processed")
120
+
121
+ LOGGER.debug(f"Sending reply")
122
+ try:
123
+ self.socket.send(res)
124
+ except zmq.ZMQError as e:
125
+ LOGGER.error(f"A ZMQ error occured while sending. Error: {e}")
126
+ raise e
127
+ LOGGER.debug(f"Reply sent")
128
+
129
+ # If the request is an exit request, we stop the loop and
130
+ # let the process exit gracefully.
131
+ if parse_request_type(message) == RequestType.EXIT:
132
+ LOGGER.info("Received EXIT request. Stopping server.")
133
+ break
134
+
135
+ def __del__(self):
136
+ if self.socket:
137
+ self.socket.close()
138
+ self._context.term()
139
+
140
+
141
+ class ZmqRequestReplyClientConfig(RequestReplyClientConfig):
142
+ ip: str # IP address of the server
143
+ port: int # Port number of the server
144
+ recv_timeout_ms: int = 15000 # Timeout in milliseconds for calls to socket.recv
145
+ send_num_retries: int = 3 # Number of times to retry sending a message
146
+ # If True, recv timeouts are raised as ``zmq.Again`` to the caller after the broken
147
+ # REQ socket has been reset. Use when a timeout indicates the worker should fail and
148
+ # be respawned by its supervisor (e.g. a remote inference client). Default False
149
+ # keeps the "log and return None" behaviour.
150
+ propagate_timeout: bool = False
151
+
152
+
153
+ class ZmqRequestReplyClient(RequestReplyClient[ZmqRequestReplyClientConfig]):
154
+ """
155
+ ZeroMQ-based implementation of RequestReplyClient.
156
+
157
+ It communicates with the server using a ZeroMQ in REQ mode.
158
+
159
+ Methods:
160
+ send(request: dict) -> Optional[Dict]: Send a request to the server and
161
+ receive a reply.
162
+
163
+ Notes:
164
+ This class is designed to be used in conjunction with the
165
+ ZmqRequestReplyServer class.
166
+ """
167
+
168
+ def __init__(self, config: ZmqRequestReplyClientConfig):
169
+ super().__init__(config)
170
+ self._closed = False
171
+ self.context = zmq.Context()
172
+ self.socket = None
173
+ self._init_socket()
174
+
175
+ def _init_socket(self):
176
+ """
177
+ Reset the socket connection, this is needed when REQ is in a broken state.
178
+ """
179
+ if self.socket:
180
+ LOGGER.info(f"Closing and deleting existing socket")
181
+ self.socket.close()
182
+ del self.socket
183
+ self.socket = self.context.socket(zmq.REQ)
184
+ self.socket.setsockopt(zmq.RCVTIMEO, self.config.recv_timeout_ms)
185
+ # this option is needed, among other things, to prevent context.term()
186
+ # from handing if socket.recv() is interrupted e.g. by a KeyboardInterrupt
187
+ self.socket.setsockopt(zmq.LINGER, 0)
188
+
189
+ LOGGER.info(f"Connecting to {self.config.ip}:{self.config.port}")
190
+ self.socket.connect(f"tcp://{self.config.ip}:{self.config.port}")
191
+ LOGGER.info(f"Connected to {self.config.ip}:{self.config.port}")
192
+
193
+ def send(self, request: Dict[str, Any]) -> Optional[Dict[str, Any]]:
194
+ if self.socket is None or self.socket.closed:
195
+ LOGGER.error(f"The socket is closed, request not sent.")
196
+ return None
197
+
198
+ try:
199
+ LOGGER.debug(f"Sending request")
200
+ sent = False
201
+ request_serialized = serialize(request)
202
+ for i in range(self.config.send_num_retries):
203
+ try:
204
+ self.socket.send(request_serialized)
205
+ sent = True
206
+ LOGGER.debug(f"Request sent.")
207
+ break
208
+ except zmq.ZMQError as e:
209
+ LOGGER.error(
210
+ f"Failed to send message to {self.config.ip}:{self.config.port}. Error: {e}."
211
+ )
212
+
213
+ LOGGER.debug(f"Attempt {i} failed. Retrying.")
214
+
215
+ if not sent:
216
+ LOGGER.warn("Number of retries exceeded. Aborting.")
217
+ return None
218
+
219
+ # If the request is an exit request, we don't wait for a reply.
220
+ if request.get("type") == RequestType.EXIT:
221
+ return None
222
+
223
+ LOGGER.debug(f"Waiting for reply")
224
+ try:
225
+ message = self.socket.recv()
226
+ except zmq.Again:
227
+ # REQ socket is now stuck in "waiting for reply", so any subsequent send
228
+ # would fail with ZMQError. Reset before deciding how to surface the timeout.
229
+ self._init_socket()
230
+ if self.config.propagate_timeout:
231
+ raise
232
+ LOGGER.warn("ZMQ receive timeout. Aborting.")
233
+ return None
234
+ except zmq.ZMQError as e:
235
+ LOGGER.error(f"A ZMQ error occured while receiving. Error: {e}.")
236
+ raise e
237
+
238
+ return deserialize(message)
239
+
240
+ except KeyboardInterrupt:
241
+ # Ctrl+C might be sent mid-episode. In this case, if the exception is raised inside the try
242
+ # block, the socket will fall into a broken state. Here we reinitialize it to keep the
243
+ # communication working.
244
+ self._init_socket()
245
+ raise
246
+
247
+ def close(self) -> None:
248
+ """Idempotently tear down the socket and ZMQ context. Safe to call multiple times."""
249
+ if self._closed:
250
+ return
251
+ if self.socket:
252
+ try:
253
+ self.socket.disconnect(f"tcp://{self.config.ip}:{self.config.port}")
254
+ except zmq.ZMQError:
255
+ # Socket already disconnected (e.g. _init_socket re-created it after a timeout).
256
+ pass
257
+ self.socket.close()
258
+ self.context.term()
259
+ self._closed = True
260
+
261
+ def __del__(self):
262
+ self.close()
ladder/components/inference/api/core/requests.py ADDED
@@ -0,0 +1,21 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from enum import Enum
2
+ from typing import Any, Dict
3
+
4
+
5
+ class RequestType(str, Enum):
6
+ RESET = "reset"
7
+ GET_OBSERVATIONS = "get_observations"
8
+ EXEC_ACTION = "exec_action"
9
+ CONNECT = "connect"
10
+ EXIT = "exit"
11
+
12
+
13
+ def parse_request_type(request: Dict[str, Any]) -> RequestType:
14
+ try:
15
+ request_type = RequestType(request["type"])
16
+ except KeyError:
17
+ raise ValueError("Invalid request: request type not specified.")
18
+ except ValueError:
19
+ raise ValueError("Invalid request type.")
20
+
21
+ return request_type
ladder/components/inference/api/core/serialization.py ADDED
@@ -0,0 +1,15 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from typing import Any, Dict
2
+
3
+ import msgpack
4
+ import msgpack_numpy
5
+
6
+ # apply msgpack_numpy monkey-patch to enable automatic numpy serialization
7
+ msgpack_numpy.patch()
8
+
9
+
10
+ def serialize(data: Dict[str, Any]) -> bytes:
11
+ return msgpack.packb(data)
12
+
13
+
14
+ def deserialize(message: bytes) -> Dict[str, Any]:
15
+ return msgpack.unpackb(message)
ladder/components/inference/robots/robolab/README.md ADDED
@@ -0,0 +1,167 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # RoboLab benchmark integration
2
+
3
+ Bazel-packages NVIDIA's [RoboLab](https://github.com/NVlabs/RoboLab) manipulation benchmark
4
+ (DROID/Franka), from [a fork](https://github.com/psi-robotics/RoboLab) that upgrades it to Isaac Sim
5
+ 6.0.0.1 and Isaac Lab 3.0.0b2.
6
+
7
+ - **`env_server.py`** serves RoboLab envs over
8
+ ladder's RobotServer ZMQ protocol to the standard `run_model` + `SimplerEpisodeRunner` stack,
9
+ so runner-side features (HLC configs, RecorderWrapper, dashboard-format outputs)
10
+ apply to RoboLab exactly as to RobotArena/SimplerEnv. One Isaac app serves the whole
11
+ (task x run) sweep. Model/behavior config:
12
+ `models/vlams/configs/robolab/vlam_robolab.yaml`. It lives with the other per-benchmark `run_model`
13
+ configs (`vlam_simpler.yaml`, `vlam_robot_arena_*.yaml`) because `run_model`'s bazel target
14
+ packages that directory and the config imports `vlam_simpler.yaml`.
15
+
16
+ The launcher takes any policy, not only our checkpoints. Two variables cover one that holds its
17
+ own model (an external model under `models/external/`, or the scripted policy): `RUN_MODEL` names
18
+ the `run_model` target to launch, which is the model's own when it brings its own pip environment,
19
+ and `INFERENCE_SERVER=0` says there is nothing to serve. Everything else is identical, so a policy
20
+ either way is scored by the same checker, recorder and metric layer, and pairs with the HLC systems
21
+ below.
22
+
23
+ RoboLab runs in a py3.12 + isaac env (numpy 2.x) and the model in the vlams torch env, so the
24
+ path from env to policy crosses one ZMQ socket into `run_model` (which talks to the shared
25
+ `batch_inference_server`), mirroring RobotArena's process layout.
26
+
27
+ `droid_conversions.py` owns the DROID conventions (gripper inversion both directions,
28
+ maintained EE targets with `controls_on_targets`, `resize_with_pad(224)` matching RoboLab's own
29
+ client, and a `pytorch_kinematics` Franka FK/IK in `franka_kinematics.py` over ladder's panda
30
+ URDF (torch/numpy-2 native). RoboLab publishes `base_link`/`eef_frame` poses offset
31
+ from ladder's canonical `panda_link8`, so staying in joint space + the canonical flange frame
32
+ keeps the integration frame-convention-free.
33
+
34
+ ## Packaging (see `http-assets.MODULE.bazel`)
35
+
36
+ - **Code**: `@robolab_repo`: the RoboLab source archive (sha256-pinned, code only). A `constants.py`
37
+ patch makes it resolve assets from `ROBOLAB_ASSET_DIR`.
38
+ - **Assets**: `@robolab_assets_archive`: the ~1 GB asset tree the tasks load, staged into
39
+ `assets/` by `copy_to_directory`. First build on a fresh machine fetches it once.
40
+ - **openpi client**: `@openpi_client_repo` vendors `openpi_client` as source (its `numpy<2` pin
41
+ conflicts with isaacsim's numpy 2.x; the source runs fine on 2.x).
42
+
43
+ ## Running an eval
44
+
45
+ `scripts/vlam_robolab.sh` (env-var driven, ports auto-allocated). GPU node with RT cores;
46
+ Isaac Sim 6 needs driver 595.
47
+
48
+ ```bash
49
+ # one of our checkpoints, behind the shared inference server (the default)
50
+ SESSION_NAME=sess_... CKPT_NAME=model-checkpoint-ema-050000.pt \
51
+ TASKS="BananaOnPlateTask" NUM_ENVS=8 NUM_RUNS=1 \
52
+ ./ladder/components/inference/robots/robolab/scripts/vlam_robolab.sh
53
+ # an external model -- one model per lane, no inference server
54
+ RUN_MODEL=models/external/openpi:run_model INFERENCE_SERVER=0 TASKS="comp_bin_2" \
55
+ LADDER_CONFIG=ladder/components/inference/models/external/openpi/configs/robolab/composition/openpi_robolab_composition.yaml \
56
+ ./ladder/components/inference/robots/robolab/scripts/vlam_robolab.sh
57
+ ```
58
+
59
+ Manual invocation of the individual pieces (the launcher does all of this for you):
60
+
61
+ ```bash
62
+ # env server: serves RoboLab envs over the RobotServer ZMQ protocol
63
+ bazel run //ladder/components/inference/robots/robolab:env_server -- \
64
+ --port 5556 --task BananaOnPlateTask --num-envs 8 --num-runs 1 --headless
65
+ # dashboard export: map a run to episode_results.jsonl
66
+ bazel run //ladder/components/inference/robots/robolab:export_robolab_results -- \
67
+ --episode-log <run_dir>/all/episode_log.yaml --output-dir <run_dir>
68
+ ```
69
+
70
+ Runs write `results.yaml`, `episode_log.yaml` and per-env mp4s, and
71
+ (via `export_robolab_results.py`, run automatically at the end of a run) RoboLab's
72
+ `episode_results.jsonl`, so RoboLab's dashboard can read the results too. Env-side diagnostics (hdf5
73
+ trajectories, SPARC/path-length metrics, event streams) are the one thing only RoboLab's own runner
74
+ ever wrote.
75
+
76
+ An external model runs in its own pip environment, which bazel provisions, and holds one copy of
77
+ the weights per lane rather than one per card. That costs roughly a lane's worth of VRAM, so run
78
+ fewer lanes per card. Its own package documents its caches
79
+ (`models/external/openpi/README.md` for pi0.5).
80
+
81
+ ## Hierarchical eval systems
82
+
83
+ The ladder path drives the shared HLC stack (`api/client/hlc`), the same one RobotArena and
84
+ SimplerEnv use, so a system is defined ONCE in `api/client/hlc/configs/` and each benchmark ships
85
+ one eval config per system, **named after it**. `LADDER_CONFIG` selects the system; the RoboLab
86
+ configs live in `models/vlams/configs/robolab/composition/` and each imports its shared system plus
87
+ this benchmark's plan cache and RoboLab's own timing:
88
+
89
+ | `LADDER_CONFIG` (`…/configs/robolab/composition/`) | Shared system | Plan | Switches on |
90
+ |---|---|---|---|
91
+ | `vlam_robolab_composition.yaml` | none (flat, no HLC) | none (raw instruction) | n/a |
92
+ | `…_oracle.yaml` | `oracle` | from the env | per-goal `achieved` |
93
+ | `…_plan_gripper.yaml` | `plan_gripper` | cached | the gripper cycle |
94
+ | `…_plan_periodic.yaml` | `plan_periodic` | cached | a step clock (no feedback) |
95
+ | `…_plan_verifier.yaml` | `plan_verifier` | cached | a VLM check |
96
+ | `…_plan_verifier_interval.yaml` | `plan_verifier_interval` | cached | a VLM check on a clock |
97
+ | `…_plan_verifier_local.yaml` | `plan_verifier_local` | cached | a VLM check, in-process Qwen3-VL |
98
+ | `…_plan_verifier_local_interval.yaml` | `plan_verifier_local` | cached | the local check, on a clock |
99
+ | `…_plan_verifier_noretry.yaml` | `plan_verifier_noretry` | cached | a VLM check, no retry |
100
+ | `…_plan_verifier_retry.yaml` | `plan_verifier_retry` | cached | a VLM check, retry in place |
101
+ | `…_stepwise_gripper.yaml` | `stepwise_gripper` | none (one at a time) | the gripper cycle |
102
+ | `…_stepwise_interval.yaml` | `stepwise_interval` | none (one at a time) | a step clock |
103
+ | `…_volo.yaml` | `volo` | cached | VoLo's own tool loop |
104
+
105
+ `…_plan_verifier_live.yaml` is the one file that is not a system: it is `_plan_verifier` with
106
+ `cache_path` omitted, so the VLM decomposes the reset frame. This is the pass that mints a plan for a newly
107
+ added task. `composition/language/` holds the same paraphrase probes the other two benchmarks ship.
108
+ This is the same set, file for file, as SimplerEnv's and RobotArena's composition configs, so a
109
+ system compares across all three.
110
+
111
+ ```bash
112
+ SESSION_NAME=sess_... CKPT_NAME=model-checkpoint-ema-015000.pt \
113
+ LADDER_CONFIG=ladder/components/inference/models/vlams/configs/robolab/composition/vlam_robolab_composition_plan_verifier.yaml \
114
+ TASKS="comp_bin_2" ./ladder/components/inference/robots/robolab/scripts/vlam_robolab.sh
115
+ ```
116
+
117
+ **Plans are a config concern, not the launcher's.** Only the `_plan_*` systems read
118
+ `composition/decomp_cache.json` (zero API calls at eval time), via `hlc_config.source.cache_path`.
119
+ Flat and `_oracle` need no plans at all and the `_stepwise_*` systems hold none by design. The cache
120
+ sits beside the composition package exactly as it does on the other two benchmarks; RoboLab's is keyed
121
+ by task class name (`CompBin4Task`).
122
+
123
+ The oracle needs no cache: `oracle.py` synthesizes the per-goal `metadata['oracle']` signal from the
124
+ task's OWN subtask spec: one `(command, check)` pair per score-carrying goal, rendered from the
125
+ goal's terminating predicate (verb + object/target nouns). It is the RoboLab-side analogue of SimplerEnv's
126
+ `oracle_subtasks`. Commands and `achieved` are built in one pass so `oracle.achieved[i]` lines up
127
+ with commanded subtask `i` by construction.
128
+
129
+ RoboLab's timescale is the one thing that does not carry over from the other two benchmarks: a Franka
130
+ pick-and-place takes ~250 steps against ~50 on SimplerEnv/RA, so every advancer window
131
+ (`stuck_patience_steps`, `attempt_stall_steps`, `interval`, `verify_interval`) is set from RoboLab's
132
+ own measured median subtask rather than inherited. A window shorter than one placement abandons every
133
+ goal mid-reach and reads as a difficulty wall that is not there.
134
+
135
+ ## Throughput
136
+
137
+ `NUM_ENVS` parallel Isaac envs are stacked into one batched model forward per decode, sharing the
138
+ fixed model cost across N episodes. Raise it for throughput (`MAX_BATCH_SIZE >= NUM_ENVS`).
139
+ Per-step wall is dominated by the upstream Isaac render, not the model.
140
+
141
+ ## Parity contract vs the native runner
142
+
143
+ Validated against RoboLab's native runner:
144
+ clean-start success 86.4% ladder vs 86.7% native; frame-level camera/action-input equivalence
145
+ verified; the ladder path ran as fast as native or up to 30% faster.
146
+
147
+ Identical by construction (any change here must keep both paths in lockstep):
148
+ - Task iteration = `run_evaluation`'s loop: `create_env` per task (same args, seed 0 default),
149
+ `reset_eval_state` between runs, double `env.reset()`, timeline pump before each step.
150
+ - Env-side semantics untouched: success predicates, frozen envs, per-task episode caps,
151
+ the ep_len<=2 physics-artifact re-reset.
152
+ - Model I/O: same frames (`resize_with_pad(224)`, both cameras), gripper flips + binarize,
153
+ maintained-EE-target + clamped IK (`droid_conversions.py`), same `ActionChunkingController`
154
+ cadence.
155
+
156
+ Known, deliberate differences:
157
+ - Native-only features: `--num-episodes-adaptive` sampling; resume-skip of completed cells
158
+ (the ladder runner appends); hdf5 trajectories + event streams. Trajectory metrics
159
+ (`ee_sparc`, `joint_sparc_mean`, `ee_isj`, `joint_isj`, `ee_path_length`, `joint_rmse_mean`,
160
+ `ee_speed_max/mean`) are native-parity: the env server samples the same articulation state
161
+ the native hdf5 recorder writes and calls robolab's own `compute_episode_metrics` at each
162
+ env's terminal step, so `export_robolab_results.py` fills `metrics`; `events`/`timing` stay
163
+ empty.
164
+ - The ladder runner queries the model for frozen envs too (results-neutral; the batched
165
+ server amortizes it, and the ladder path is still faster than native overall).
166
+ - Ladder videos are the 224x224 letterboxed model-input frames (native records 720p half-scale);
167
+ each env's recording ends at its own terminal step.
ladder/components/inference/robots/robolab/composition/README.md ADDED
@@ -0,0 +1,146 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # RoboLab long-horizon composition benchmark
2
+
3
+ Systematic long-horizon manipulation tasks for RoboLab, mirroring the extended SimplerEnv / RobotArena
4
+ composition benchmarks: the same task-type families (single-destination, split across receptacles,
5
+ distractors, ordered sequence) scaled along an N-goal axis (2 → 10), to measure how flat VLAs,
6
+ a privileged oracle, and the HLC orchestrators degrade as the horizon grows.
7
+
8
+ ## Design
9
+
10
+ Every composition task is one `CompositionSpec` (`specs.py`): a subset of the object catalog
11
+ (`catalog.py`), each object assigned to a receptacle, with an optional ordering constraint. The N-goal
12
+ count is `len(goals)`. `factory.make_task(spec_name)` turns a spec into a RoboLab `Task`
13
+ subclass, and `tasks.py` defines one such class per spec. RoboLab addresses a single one of them as
14
+ `<path to tasks.py>::<ClassName>` (`specs.task_target`), so a spec name is all a caller passes.
15
+
16
+ ## The task set
17
+
18
+ **44 tasks, and `SPECS` is the whole benchmark.** There is no calibration tier, no easy/hard split
19
+ and no held-out set: one list, pinned name by name in `test/test_composition_benchmark.py`, so a task
20
+ cannot enter or leave the suite as a side effect of editing a generator.
21
+
22
+ | family | tasks | goals |
23
+ |---|---|---|
24
+ | single pick-and-place (bin, plate) | 2 | 1 |
25
+ | single-destination into a bin | 3 | 2, 6, 10 |
26
+ | distractor (`everything except ...`) | 2 | 2, 4 |
27
+ | route (two receptacles, plate + bin) | 10 | 2-10 |
28
+ | split to a plate | 7 | 2-8 |
29
+ | ordered into a bin | 9 | 2-10 |
30
+ | relay (table → plate → bin) | 4 | 4, 6, 8, 10 |
31
+ | revisit | 3 | 3, 6, 9 |
32
+ | transfer (off the plate into the bin) | 2 | 2, 3 |
33
+ | identical instances (counting) | 2 | 2, 4 |
34
+
35
+ Every task names the objects it asks for. A collective phrasing (`put everything in the bin`) is word
36
+ for word identical at two objects and at ten, so a ladder built on it measures how many placements
37
+ fit in the step budget rather than whether the instruction was understood.
38
+
39
+ `FRUIT_LADDER` is the object order the N-goal tasks draw from, and the pomegranate is deliberately
40
+ last: it is the only object that both a DROID-trained checkpoint and π0.5 fail on, so at any
41
+ earlier position it would cap every longer rung by the asset rather than by the horizon. The rest of
42
+ the order is deliberately NOT ranked by any one model's per-object success rates, so the benchmark is
43
+ not fitted to a particular model under test.
44
+
45
+ ## Where objects start
46
+
47
+ A graspable's distance from the robot base matters more than anything else in this suite: objects
48
+ far from the base are often out of comfortable reach.
49
+
50
+ `_scatter` maximises the minimum separation between objects, which on its own pushes objects to the
51
+ far edge of `_OBJ_RECT` (0.83 m), out of comfortable reach. The pairwise constraint already
52
+ guarantees nothing overlaps at worst-case jitter, so every spec is also laid out against
53
+ `layout.REACH_MAX` (0.62 m) at worst-case jitter. Transfer and relay lay their objects out on a
54
+ receptacle, so their source is slid toward the base until it complies instead of being positioned by
55
+ hand. Worst start distance across the registry: 0.619 m.
56
+
57
+ The bound is on an object's CENTRE, which makes it exactly invariant to the reset's full-yaw
58
+ randomization (yaw rotates an object about its own centre). Position jitter is handled by evaluating
59
+ at the far corner of the jitter box, so the bound holds for every episode rather than on average. The
60
+ price is per-episode variation at the long rungs: jitter tapers from 0.07 m at one to three goals down
61
+ to 0.02 m at eight to ten, since the tighter band holds less.
62
+
63
+ `factory._author_usda` writes one scene USD per task into `$TMPDIR/robolab_composition_scenes/`:
64
+ a bare tabletop rig (`fixtures/table_oak.usd` + `fixtures/franka_table.usd`, ground plane, physics
65
+ material) with every graspable and receptacle attached as a direct child of `world` through a USD
66
+ **payload**. Nothing is hand-authored and no asset is re-vendored: the payloads point straight into
67
+ RoboLab's own `ASSET_DIR`, so the whole benchmark stays a ladder-side addition with no fork edit.
68
+
69
+ Composing the scene rather than selecting movers out of a pre-made one is what makes the per-object
70
+ scoring possible: `import_scene` scrapes those direct children as single rigid bodies, so a contact
71
+ sensor resolves one body per name. A runtime spawn of a raw catalog USD nests its bodies instead,
72
+ which breaks the per-object contact filter every goal predicate is built on.
73
+
74
+ The pools the specs draw from, both in `catalog.py`:
75
+
76
+ | pool | entries |
77
+ |---|---|
78
+ | `CATALOG` movers | 10 produce (banana, two oranges, lemon, lime, avocado, pomegranate, lychee, onion, pumpkin) + 2 coloured blocks (red, blue), decoys only |
79
+ | `RECEPTACLE_TYPES` | `bin` (in), `bowl` (in), `plate` (on) |
80
+
81
+ Only known-graspable produce is used as a mover: RoboLab's droid policy is grasp-floored on
82
+ blocks/cans, so a benchmark built from those would measure grasp, not orchestration. Every catalog
83
+ entry is verified single-rigid-body and confirmed to render (`objaverse/apple_01` is excluded because it
84
+ spawns invisible).
85
+
86
+ ## Why the oracle works for free
87
+
88
+ A spec's `subtasks` is one `pick_and_place[_on_surface]` per receptacle group with `logical="all"`.
89
+ `oracle.build_oracle` expands a `logical="all"` group into one goal per object, so the privileged
90
+ plan is exactly the per-object N-goal sequence, with no per-scene oracle authoring. The `_plan_*`
91
+ systems read `composition/decomp_cache.json`, which carries an instruction-echo plan per task;
92
+ `_plan_verifier_live` needs no cache (it decomposes the reset frame live).
93
+
94
+ ## Inspecting
95
+
96
+ `python3 -m ladder.components.inference.robots.robolab.composition.specs`, run from the repo root,
97
+ prints the full task manifest (name, N, family, scene, instruction).
98
+
99
+ ## Running an eval
100
+
101
+ These run through the SAME launcher as RoboLab's own tasks: `TASKS` takes composition task **names**
102
+ (env_server resolves a `comp_*` name to its Task class in `tasks.py`), and
103
+ `LADDER_CONFIG` selects the hierarchical system, exactly the shape `SCENES`/`ENV_NAMES` +
104
+ `RA_CLIENT_CONFIG`/`SIMPLER_CONFIG` have on the RobotArena and SimplerEnv launchers.
105
+
106
+ ```bash
107
+ SESSION_NAME=<droid-subset session> CKPT_NAME=model-checkpoint-ema-015000.pt \
108
+ LADDER_CONFIG=ladder/components/inference/models/vlams/configs/robolab/composition/vlam_robolab_composition_oracle.yaml \
109
+ TASKS="comp_bin_6 comp_split_plate_4" \
110
+ NUM_ENVS=8 NUM_RUNS=1 VIDEO=True \
111
+ bash ladder/components/inference/robots/robolab/scripts/vlam_robolab.sh
112
+ ```
113
+
114
+ `LADDER_CONFIG` selects the system: `vlam_robolab_composition.yaml` is flat (the model gets only the
115
+ composed instruction), and one `_<system>` variant exists per hierarchical system in
116
+ `api/client/hlc/configs/`, named after it: `_oracle`, `_plan_gripper`, `_plan_periodic`,
117
+ `_plan_verifier`, `_plan_verifier_interval`, `_plan_verifier_local`, `_stepwise_gripper`,
118
+ `_stepwise_interval`. `_plan_verifier_live` is not a system of its own: it is `_plan_verifier` with
119
+ `cache_path` omitted, so the VLM decomposes the reset frame. Each writes to its own
120
+ `robolab_composition*/` directory. The full table, including the RoboLab-only variants
121
+ (`_plan_verifier_retry`, `_plan_verifier_noretry`), is in the
122
+ [package README](../README.md#hierarchical-eval-systems).
123
+
124
+ **Task selection.** `TASKS` is the only env control. Pass a subset, or the whole registry:
125
+
126
+ ```bash
127
+ # every composition task, in registry order (44 of them)
128
+ TASKS=$(python3 -c 'from ladder.components.inference.robots.robolab.composition.specs \
129
+ import SPECS; print(" ".join(SPECS))')
130
+
131
+ # longest budget first, which shortens the tail: a lane owns a slice for the life of one Isaac app,
132
+ # so a lane dealt the long tasks finishes last
133
+ TASKS=$(python3 -c 'from ladder.components.inference.robots.robolab.composition.specs \
134
+ import SPECS; print(" ".join(sorted(SPECS, key=lambda n: -SPECS[n].episode_length_s)))')
135
+ ```
136
+
137
+ **Language probes.** Two independent knobs on the runner, the same pair the other two composition
138
+ benchmarks use, in `models/vlams/configs/robolab/composition/language/`.
139
+ `runner_config.instruction_override` rewords the TASK instruction, keyed by the env_name env_server
140
+ reports, i.e. the RoboLab Task CLASS name (`CompBin4Task`, not `comp_bin_4`); a key matching no task is
141
+ silently ignored, so check names against `task_class_name`. RoboLab additionally has an env-side instruction axis
142
+ (`INSTRUCTION_TYPE=collective|enumerated`, from each spec's own `instruction` dict), which is
143
+ independent of both.
144
+
145
+ Per-episode `episode_meta.yaml` records the subtask switches (`instruction_log`), so the dashboard
146
+ shows the subtask timeline.
ladder/components/inference/robots/robolab/composition/catalog.py ADDED
@@ -0,0 +1,113 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import dataclasses
2
+ from typing import Dict, Tuple
3
+
4
+ # How an object satisfies its goal on a receptacle.
5
+ IN = "in" # object_in_container: bins, bowls, boxes
6
+ ON = "on" # object_on_top: plates and other flat surfaces
7
+
8
+
9
+ def verb(kind: str) -> str:
10
+ """The preposition a receptacle of this kind takes."""
11
+ return ON if kind == ON else IN
12
+
13
+
14
+ @dataclasses.dataclass(frozen=True)
15
+ class ObjectType:
16
+ """A graspable catalog object. ``usd`` is relative to the RoboLab ASSET_DIR (the factory
17
+ joins it); ``rest_z`` is the object origin's resting height above the table top (~half the
18
+ bbox height) so it spawns sitting on the surface; ``radius`` is the footprint bounding radius
19
+ (half the larger XY bbox dim, from the sim) used to keep it clear of receptacles and edges after
20
+ jitter. ``category`` drives collective phrasing ("all the fruit") and goal-vs-distractor choice."""
21
+
22
+ usd: str
23
+ noun: str
24
+ rest_z: float
25
+ radius: float
26
+ category: str # fruit | vegetable | block
27
+ # Visual attribute a plan names the object by ("the yellow lemon"); empty when the noun alone
28
+ # is what a viewer would say (an orange, a red block). The reference plans render it.
29
+ colour: str = ""
30
+
31
+
32
+ @dataclasses.dataclass(frozen=True)
33
+ class ReceptacleType:
34
+ usd: str
35
+ kind: str # IN | ON
36
+ noun: str
37
+ rest_z: float
38
+ footprint: Tuple[float, float] # (half_x, half_y) top-surface extent (m), from the sim bbox
39
+ colour: str = ""
40
+
41
+
42
+ # Graspable objects. The DROID VLA is grasp-limited to produce-like objects, so the pool is
43
+ # fruit/veg; blocks are decoys only. ``radius`` / receptacle ``footprint`` are measured from the sim
44
+ # bbox (usd_utils.get_dimensions), so the placement clearances match the real geometry.
45
+ # Every asset here is verified single-rigid-body AND confirmed to render (objaverse/apple_01 is
46
+ # excluded -- it spawns invisible and its nested collision shapes break the per-object contact filter).
47
+ CATALOG: Dict[str, ObjectType] = {
48
+ "banana": ObjectType("objects/ycb/banana.usd", "banana", 0.020, 0.089, "fruit", colour="yellow"),
49
+ "orange": ObjectType("objects/fruits_veggies/orange1.usd", "orange", 0.042, 0.036, "fruit"),
50
+ "lemon": ObjectType("objects/fruits_veggies/lemon1.usd", "lemon", 0.026, 0.038, "fruit", colour="yellow"),
51
+ "lime": ObjectType("objects/fruits_veggies/lime.usd", "lime", 0.030, 0.038, "fruit", colour="green"),
52
+ "avocado": ObjectType("objects/fruits_veggies/avocado.usd", "avocado", 0.046, 0.031, "fruit"),
53
+ "pomegranate": ObjectType(
54
+ "objects/fruits_veggies/pomegranate.usd", "pomegranate", 0.058, 0.058, "fruit", colour="red"
55
+ ),
56
+ "lychee": ObjectType("objects/fruits_veggies/lychee.usd", "lychee", 0.025, 0.021, "fruit"),
57
+ "orange2": ObjectType("objects/fruits_veggies/orange2.usd", "orange", 0.037, 0.036, "fruit"),
58
+ "onion": ObjectType(
59
+ "objects/fruits_veggies/red_onion.usd", "onion", 0.045, 0.030, "vegetable", colour="red"
60
+ ),
61
+ "pumpkin": ObjectType(
62
+ "objects/vomp/pumpkinsmall/pumpkinsmall.usd", "pumpkin", 0.038, 0.038, "vegetable", colour="orange"
63
+ ),
64
+ "red_block": ObjectType("objects/basic/red_block.usd", "red block", 0.024, 0.030, "block"),
65
+ "blue_block": ObjectType("objects/basic/blue_block.usd", "blue block", 0.024, 0.030, "block"),
66
+ }
67
+
68
+ RECEPTACLE_TYPES: Dict[str, ReceptacleType] = {
69
+ # A roomy bin (30x20cm) and a wide 30cm bowl -- both hold a long banana and several fruits.
70
+ # The flat plate is the transfer/relay source (objects resting ON it stay easiest to grasp out).
71
+ "bin": ReceptacleType(
72
+ "objects/vomp/bin_a05/bin_a05.usd", IN, "bin", 0.080, (0.149, 0.100), colour="grey"
73
+ ),
74
+ "bowl": ReceptacleType(
75
+ "objects/vomp/blackandbrassbowl_large/blackandbrassbowl_large.usd",
76
+ IN,
77
+ "bowl",
78
+ 0.075,
79
+ (0.151, 0.151),
80
+ colour="black",
81
+ ),
82
+ "plate": ReceptacleType(
83
+ "objects/vomp/plate_large/plate_large.usd", ON, "plate", 0.013, (0.166, 0.166), colour="white"
84
+ ),
85
+ }
86
+
87
+ # Ladder pool, best-grasp-first. The N-goal single-destination tasks take the first N. Nine distinct
88
+ # produce types plus a second orange for the tenth rung (so N=10 has a "both oranges" duplicate, like
89
+ # RoboLab's own multi-banana tasks).
90
+ FRUIT_LADDER: Tuple[str, ...] = (
91
+ "banana",
92
+ "orange",
93
+ "lemon",
94
+ "lime",
95
+ "avocado",
96
+ "onion",
97
+ "lychee",
98
+ "pumpkin",
99
+ "orange2",
100
+ # Last, because it is the one object that policies consistently fail to place. Earlier in the
101
+ # order it would cap every longer rung by an asset rather than by the horizon the suite exists
102
+ # to measure. The rest of the order is deliberately not ranked by any one model's per-object
103
+ # success rates.
104
+ "pomegranate",
105
+ )
106
+
107
+ # ------------------------------ workspace layout ------------------------------
108
+ # Franka base at world origin, +x forward, table top at z=0. Graspables scatter over a reachable band;
109
+ # receptacles are PINNED at the deep back (the reset randomizes only the free table objects). Authored
110
+ # positions are the per-episode means; the reset jitters each free object in x/y + yaw (see factory).
111
+ # _TABLE is the measured table_oak top extent (from the scene USD); its front ~0.18 m is unreachable
112
+ # behind the mount. Every placement is checked so that, at the WORST jitter+footprint, an object never
113
+ # leaves the table and never enters a receptacle's rectangle -- see _scatter.
ladder/components/inference/robots/robolab/composition/check_scene_rendered.py ADDED
@@ -0,0 +1,145 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ """Flag RoboLab episodes whose scene stopped being rendered.
3
+
4
+ The composition rig composes every object and receptacle onto the base rig as a USD payload, and
5
+ Hydra can evict streamed payload geometry mid-episode: the reset frame shows the full scene, then
6
+ the table, robot and objects vanish while the static room backdrop keeps rendering. Physics is
7
+ unaffected, so nothing errors -- but the recorder writes the same observation the policy is served,
8
+ so the policy is blind for the rest of the episode and the cell scores as an ordinary failure.
9
+
10
+ Frame 0 is the reset frame and is rendered before any step, so it is the per-episode reference:
11
+ an episode is flagged when the table occupies less than `--min-ratio` of the area it occupied then.
12
+ """
13
+ import argparse
14
+ import colorsys
15
+ import glob
16
+ import os
17
+ import subprocess
18
+ import sys
19
+ import tempfile
20
+ from typing import List, Optional, Tuple
21
+
22
+ from PIL import Image
23
+
24
+ # The tabletop, in HSV. The rig's table is the one large light-wood surface in frame; the office
25
+ # backdrop behind it has no comparable region, which is what makes presence separable at all.
26
+ _HUE = (0.03, 0.13)
27
+ _MIN_SAT = 0.30
28
+ _MIN_VAL = 0.30
29
+
30
+
31
+ def table_fraction(path: str) -> float:
32
+ image = Image.open(path).convert("RGB").resize((96, 96))
33
+ hits = 0
34
+ for red, green, blue in image.getdata():
35
+ hue, sat, val = colorsys.rgb_to_hsv(red / 255, green / 255, blue / 255)
36
+ if _HUE[0] <= hue <= _HUE[1] and sat >= _MIN_SAT and val >= _MIN_VAL:
37
+ hits += 1
38
+ return hits / (96 * 96)
39
+
40
+
41
+ def _frame(video: str, index: int, out: str) -> Optional[str]:
42
+ subprocess.run(
43
+ [
44
+ "ffmpeg",
45
+ "-loglevel",
46
+ "error",
47
+ "-y",
48
+ "-i",
49
+ video,
50
+ "-vf",
51
+ f"select=eq(n\\,{index})",
52
+ "-vframes",
53
+ "1",
54
+ out,
55
+ ],
56
+ check=False,
57
+ )
58
+ return out if os.path.exists(out) and os.path.getsize(out) else None
59
+
60
+
61
+ def scan(video: str, samples: int, workdir: str) -> Tuple[float, List[float]]:
62
+ """(reference table fraction at reset, table fraction at each sampled step)."""
63
+ count = subprocess.run(
64
+ [
65
+ "ffprobe",
66
+ "-v",
67
+ "error",
68
+ "-count_frames",
69
+ "-select_streams",
70
+ "v:0",
71
+ "-show_entries",
72
+ "stream=nb_read_frames",
73
+ "-of",
74
+ "csv=p=0",
75
+ video,
76
+ ],
77
+ capture_output=True,
78
+ text=True,
79
+ check=False,
80
+ ).stdout.strip()
81
+ total = int(count) if count.isdigit() else 0
82
+ if total < 2:
83
+ return 0.0, []
84
+ reference = _frame(video, 0, os.path.join(workdir, "ref.png"))
85
+ if reference is None:
86
+ return 0.0, []
87
+ # Skip the first few steps: the payloads are still resolving and a frame there is not evidence.
88
+ indices = [int(total * (i + 1) / (samples + 1)) for i in range(samples)]
89
+ later = []
90
+ for position, index in enumerate(indices):
91
+ path = _frame(video, index, os.path.join(workdir, f"f{position}.png"))
92
+ if path is not None:
93
+ later.append(table_fraction(path))
94
+ return table_fraction(reference), later
95
+
96
+
97
+ def main() -> int:
98
+ parser = argparse.ArgumentParser(description=__doc__)
99
+ parser.add_argument("root", help="campaign directory (scanned for episodes/*/main.mp4)")
100
+ parser.add_argument("--samples", type=int, default=4, help="frames to check per episode")
101
+ parser.add_argument(
102
+ "--min-ratio",
103
+ type=float,
104
+ default=0.30,
105
+ help="flag when the table shrinks below this share of its reset area",
106
+ )
107
+ parser.add_argument(
108
+ "--min-absolute",
109
+ type=float,
110
+ default=0.02,
111
+ help="table area below this is no scene at all, whatever the reset frame showed",
112
+ )
113
+ parser.add_argument("--quiet", action="store_true", help="only print the summary")
114
+ args = parser.parse_args()
115
+
116
+ videos = sorted(glob.glob(os.path.join(args.root, "**", "episodes", "*", "main.mp4"), recursive=True))
117
+ if not videos:
118
+ print(f"no episode videos under {args.root}", file=sys.stderr)
119
+ return 2
120
+
121
+ flagged = []
122
+ with tempfile.TemporaryDirectory() as workdir:
123
+ for video in videos:
124
+ reference, later = scan(video, args.samples, workdir)
125
+ if not later:
126
+ continue
127
+ # Two ways to be blind, and the absolute test is not redundant: an episode whose payloads
128
+ # were already gone at reset has a degenerate REFERENCE, so its ratio looks healthy.
129
+ worst_absolute = min(later)
130
+ worst_ratio = min(later) / reference if reference > 0 else 0.0
131
+ if worst_absolute < args.min_absolute or worst_ratio < args.min_ratio:
132
+ flagged.append((video, worst_absolute))
133
+ if not args.quiet:
134
+ print(
135
+ f"BLIND table={worst_absolute:.3f} ratio={worst_ratio:4.2f} "
136
+ f"{os.path.relpath(video, args.root)}"
137
+ )
138
+ print(
139
+ f"\n{len(flagged)}/{len(videos)} episodes lost their scene ({100 * len(flagged) / len(videos):.1f}%)"
140
+ )
141
+ return 1 if flagged else 0
142
+
143
+
144
+ if __name__ == "__main__":
145
+ sys.exit(main())
ladder/components/inference/robots/robolab/composition/decomp_cache.json ADDED
@@ -0,0 +1,500 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "_meta": {
3
+ "role": "reference plan",
4
+ "model": "ground_truth",
5
+ "generated": "2026-09-09",
6
+ "note": "NOT a model output: the plan per task from specs.decomp_cache_entries(), naming objects by colour and type. Every entry is {subtasks, ordered, revisits}."
7
+ },
8
+ "CompBin10Task": {
9
+ "subtasks": [
10
+ "put the yellow banana in the grey bin.",
11
+ "put the orange in the grey bin.",
12
+ "put the yellow lemon in the grey bin.",
13
+ "put the green lime in the grey bin.",
14
+ "put the avocado in the grey bin.",
15
+ "put the red onion in the grey bin.",
16
+ "put the lychee in the grey bin.",
17
+ "put the orange pumpkin in the grey bin.",
18
+ "put the orange in the grey bin.",
19
+ "put the red pomegranate in the grey bin."
20
+ ],
21
+ "ordered": false,
22
+ "revisits": false
23
+ },
24
+ "CompBin1Task": {
25
+ "subtasks": [
26
+ "put the yellow banana in the grey bin."
27
+ ],
28
+ "ordered": false,
29
+ "revisits": false
30
+ },
31
+ "CompBin2DistractorTask": {
32
+ "subtasks": [
33
+ "put the yellow banana in the grey bin.",
34
+ "put the orange in the grey bin."
35
+ ],
36
+ "ordered": false,
37
+ "revisits": false
38
+ },
39
+ "CompBin2Task": {
40
+ "subtasks": [
41
+ "put the yellow banana in the grey bin.",
42
+ "put the orange in the grey bin."
43
+ ],
44
+ "ordered": false,
45
+ "revisits": false
46
+ },
47
+ "CompBin4DistractorTask": {
48
+ "subtasks": [
49
+ "put the yellow banana in the grey bin.",
50
+ "put the orange in the grey bin.",
51
+ "put the yellow lemon in the grey bin.",
52
+ "put the green lime in the grey bin."
53
+ ],
54
+ "ordered": false,
55
+ "revisits": false
56
+ },
57
+ "CompBin6Task": {
58
+ "subtasks": [
59
+ "put the yellow banana in the grey bin.",
60
+ "put the orange in the grey bin.",
61
+ "put the yellow lemon in the grey bin.",
62
+ "put the green lime in the grey bin.",
63
+ "put the avocado in the grey bin.",
64
+ "put the red onion in the grey bin."
65
+ ],
66
+ "ordered": false,
67
+ "revisits": false
68
+ },
69
+ "CompIdentical2Task": {
70
+ "subtasks": [
71
+ "put the orange in the grey bin.",
72
+ "put the orange in the grey bin."
73
+ ],
74
+ "ordered": false,
75
+ "revisits": false
76
+ },
77
+ "CompIdentical4Task": {
78
+ "subtasks": [
79
+ "put the green lime in the grey bin.",
80
+ "put the green lime in the grey bin.",
81
+ "put the green lime in the grey bin.",
82
+ "put the green lime in the grey bin."
83
+ ],
84
+ "ordered": false,
85
+ "revisits": false
86
+ },
87
+ "CompOrderedBin10Task": {
88
+ "subtasks": [
89
+ "put the orange pumpkin in the grey bin.",
90
+ "put the red onion in the grey bin.",
91
+ "put the green lime in the grey bin.",
92
+ "put the avocado in the grey bin.",
93
+ "put the yellow lemon in the grey bin.",
94
+ "put the red pomegranate in the grey bin.",
95
+ "put the lychee in the grey bin.",
96
+ "put the yellow banana in the grey bin.",
97
+ "put the orange in the grey bin.",
98
+ "put the orange in the grey bin."
99
+ ],
100
+ "ordered": true,
101
+ "revisits": false
102
+ },
103
+ "CompOrderedBin2Task": {
104
+ "subtasks": [
105
+ "put the yellow banana in the grey bin.",
106
+ "put the orange in the grey bin."
107
+ ],
108
+ "ordered": true,
109
+ "revisits": false
110
+ },
111
+ "CompOrderedBin3Task": {
112
+ "subtasks": [
113
+ "put the yellow banana in the grey bin.",
114
+ "put the yellow lemon in the grey bin.",
115
+ "put the orange in the grey bin."
116
+ ],
117
+ "ordered": true,
118
+ "revisits": false
119
+ },
120
+ "CompOrderedBin4Task": {
121
+ "subtasks": [
122
+ "put the orange in the grey bin.",
123
+ "put the yellow lemon in the grey bin.",
124
+ "put the green lime in the grey bin.",
125
+ "put the yellow banana in the grey bin."
126
+ ],
127
+ "ordered": true,
128
+ "revisits": false
129
+ },
130
+ "CompOrderedBin5Task": {
131
+ "subtasks": [
132
+ "put the avocado in the grey bin.",
133
+ "put the orange in the grey bin.",
134
+ "put the yellow lemon in the grey bin.",
135
+ "put the green lime in the grey bin.",
136
+ "put the yellow banana in the grey bin."
137
+ ],
138
+ "ordered": true,
139
+ "revisits": false
140
+ },
141
+ "CompOrderedBin6Task": {
142
+ "subtasks": [
143
+ "put the avocado in the grey bin.",
144
+ "put the orange in the grey bin.",
145
+ "put the yellow lemon in the grey bin.",
146
+ "put the green lime in the grey bin.",
147
+ "put the red onion in the grey bin.",
148
+ "put the yellow banana in the grey bin."
149
+ ],
150
+ "ordered": true,
151
+ "revisits": false
152
+ },
153
+ "CompOrderedBin7Task": {
154
+ "subtasks": [
155
+ "put the avocado in the grey bin.",
156
+ "put the orange in the grey bin.",
157
+ "put the yellow lemon in the grey bin.",
158
+ "put the green lime in the grey bin.",
159
+ "put the red onion in the grey bin.",
160
+ "put the yellow banana in the grey bin.",
161
+ "put the lychee in the grey bin."
162
+ ],
163
+ "ordered": true,
164
+ "revisits": false
165
+ },
166
+ "CompOrderedBin8Task": {
167
+ "subtasks": [
168
+ "put the orange in the grey bin.",
169
+ "put the orange pumpkin in the grey bin.",
170
+ "put the lychee in the grey bin.",
171
+ "put the yellow lemon in the grey bin.",
172
+ "put the green lime in the grey bin.",
173
+ "put the yellow banana in the grey bin.",
174
+ "put the red onion in the grey bin.",
175
+ "put the avocado in the grey bin."
176
+ ],
177
+ "ordered": true,
178
+ "revisits": false
179
+ },
180
+ "CompOrderedBin9Task": {
181
+ "subtasks": [
182
+ "put the red onion in the grey bin.",
183
+ "put the orange in the grey bin.",
184
+ "put the orange pumpkin in the grey bin.",
185
+ "put the lychee in the grey bin.",
186
+ "put the yellow lemon in the grey bin.",
187
+ "put the green lime in the grey bin.",
188
+ "put the yellow banana in the grey bin.",
189
+ "put the avocado in the grey bin.",
190
+ "put the orange in the grey bin."
191
+ ],
192
+ "ordered": true,
193
+ "revisits": false
194
+ },
195
+ "CompPlate1Task": {
196
+ "subtasks": [
197
+ "put the yellow banana on the white plate."
198
+ ],
199
+ "ordered": false,
200
+ "revisits": false
201
+ },
202
+ "CompRelay2Task": {
203
+ "subtasks": [
204
+ "put the yellow lemon on the white plate.",
205
+ "put the yellow lemon in the grey bin.",
206
+ "put the green lime on the white plate.",
207
+ "put the green lime in the grey bin."
208
+ ],
209
+ "ordered": true,
210
+ "revisits": true
211
+ },
212
+ "CompRelay3Task": {
213
+ "subtasks": [
214
+ "put the yellow lemon on the white plate.",
215
+ "put the yellow lemon in the grey bin.",
216
+ "put the green lime on the white plate.",
217
+ "put the green lime in the grey bin.",
218
+ "put the yellow banana on the white plate.",
219
+ "put the yellow banana in the grey bin."
220
+ ],
221
+ "ordered": true,
222
+ "revisits": true
223
+ },
224
+ "CompRelay4Task": {
225
+ "subtasks": [
226
+ "put the yellow lemon on the white plate.",
227
+ "put the yellow lemon in the grey bin.",
228
+ "put the green lime on the white plate.",
229
+ "put the green lime in the grey bin.",
230
+ "put the yellow banana on the white plate.",
231
+ "put the yellow banana in the grey bin.",
232
+ "put the orange on the white plate.",
233
+ "put the orange in the grey bin."
234
+ ],
235
+ "ordered": true,
236
+ "revisits": true
237
+ },
238
+ "CompRelay5Task": {
239
+ "subtasks": [
240
+ "put the yellow lemon on the white plate.",
241
+ "put the yellow lemon in the grey bin.",
242
+ "put the green lime on the white plate.",
243
+ "put the green lime in the grey bin.",
244
+ "put the yellow banana on the white plate.",
245
+ "put the yellow banana in the grey bin.",
246
+ "put the orange on the white plate.",
247
+ "put the orange in the grey bin.",
248
+ "put the avocado on the white plate.",
249
+ "put the avocado in the grey bin."
250
+ ],
251
+ "ordered": true,
252
+ "revisits": true
253
+ },
254
+ "CompRevisit1Task": {
255
+ "subtasks": [
256
+ "put the yellow lemon in the grey bin.",
257
+ "put the yellow lemon on the white plate.",
258
+ "put the yellow lemon in the grey bin."
259
+ ],
260
+ "ordered": true,
261
+ "revisits": true
262
+ },
263
+ "CompRevisit2Task": {
264
+ "subtasks": [
265
+ "put the yellow lemon in the grey bin.",
266
+ "put the yellow lemon on the white plate.",
267
+ "put the yellow lemon in the grey bin.",
268
+ "put the green lime in the grey bin.",
269
+ "put the green lime on the white plate.",
270
+ "put the green lime in the grey bin."
271
+ ],
272
+ "ordered": true,
273
+ "revisits": true
274
+ },
275
+ "CompRevisit3Task": {
276
+ "subtasks": [
277
+ "put the yellow lemon in the grey bin.",
278
+ "put the yellow lemon on the white plate.",
279
+ "put the yellow lemon in the grey bin.",
280
+ "put the green lime in the grey bin.",
281
+ "put the green lime on the white plate.",
282
+ "put the green lime in the grey bin.",
283
+ "put the yellow banana in the grey bin.",
284
+ "put the yellow banana on the white plate.",
285
+ "put the yellow banana in the grey bin."
286
+ ],
287
+ "ordered": true,
288
+ "revisits": true
289
+ },
290
+ "CompRoute10Task": {
291
+ "subtasks": [
292
+ "put the yellow banana on the white plate.",
293
+ "put the yellow lemon on the white plate.",
294
+ "put the green lime on the white plate.",
295
+ "put the orange in the grey bin.",
296
+ "put the avocado in the grey bin.",
297
+ "put the red onion in the grey bin.",
298
+ "put the lychee in the grey bin.",
299
+ "put the orange pumpkin in the grey bin.",
300
+ "put the orange in the grey bin.",
301
+ "put the red pomegranate in the grey bin."
302
+ ],
303
+ "ordered": false,
304
+ "revisits": false
305
+ },
306
+ "CompRoute2BinfirstTask": {
307
+ "subtasks": [
308
+ "put the orange in the grey bin.",
309
+ "put the yellow lemon on the white plate."
310
+ ],
311
+ "ordered": false,
312
+ "revisits": false
313
+ },
314
+ "CompRoute2Task": {
315
+ "subtasks": [
316
+ "put the yellow lemon on the white plate.",
317
+ "put the orange in the grey bin."
318
+ ],
319
+ "ordered": false,
320
+ "revisits": false
321
+ },
322
+ "CompRoute3Task": {
323
+ "subtasks": [
324
+ "put the yellow lemon on the white plate.",
325
+ "put the green lime on the white plate.",
326
+ "put the orange in the grey bin."
327
+ ],
328
+ "ordered": false,
329
+ "revisits": false
330
+ },
331
+ "CompRoute4Task": {
332
+ "subtasks": [
333
+ "put the yellow lemon on the white plate.",
334
+ "put the green lime on the white plate.",
335
+ "put the orange in the grey bin.",
336
+ "put the avocado in the grey bin."
337
+ ],
338
+ "ordered": false,
339
+ "revisits": false
340
+ },
341
+ "CompRoute5Task": {
342
+ "subtasks": [
343
+ "put the yellow lemon on the white plate.",
344
+ "put the green lime on the white plate.",
345
+ "put the yellow banana on the white plate.",
346
+ "put the orange in the grey bin.",
347
+ "put the avocado in the grey bin."
348
+ ],
349
+ "ordered": false,
350
+ "revisits": false
351
+ },
352
+ "CompRoute6Task": {
353
+ "subtasks": [
354
+ "put the yellow lemon on the white plate.",
355
+ "put the green lime on the white plate.",
356
+ "put the yellow banana on the white plate.",
357
+ "put the orange in the grey bin.",
358
+ "put the avocado in the grey bin.",
359
+ "put the red onion in the grey bin."
360
+ ],
361
+ "ordered": false,
362
+ "revisits": false
363
+ },
364
+ "CompRoute7Task": {
365
+ "subtasks": [
366
+ "put the yellow banana on the white plate.",
367
+ "put the yellow lemon on the white plate.",
368
+ "put the green lime on the white plate.",
369
+ "put the orange in the grey bin.",
370
+ "put the avocado in the grey bin.",
371
+ "put the red onion in the grey bin.",
372
+ "put the lychee in the grey bin."
373
+ ],
374
+ "ordered": false,
375
+ "revisits": false
376
+ },
377
+ "CompRoute8Task": {
378
+ "subtasks": [
379
+ "put the yellow banana on the white plate.",
380
+ "put the yellow lemon on the white plate.",
381
+ "put the green lime on the white plate.",
382
+ "put the orange in the grey bin.",
383
+ "put the avocado in the grey bin.",
384
+ "put the red onion in the grey bin.",
385
+ "put the lychee in the grey bin.",
386
+ "put the orange pumpkin in the grey bin."
387
+ ],
388
+ "ordered": false,
389
+ "revisits": false
390
+ },
391
+ "CompRoute9Task": {
392
+ "subtasks": [
393
+ "put the yellow banana on the white plate.",
394
+ "put the yellow lemon on the white plate.",
395
+ "put the green lime on the white plate.",
396
+ "put the orange in the grey bin.",
397
+ "put the avocado in the grey bin.",
398
+ "put the red onion in the grey bin.",
399
+ "put the lychee in the grey bin.",
400
+ "put the orange pumpkin in the grey bin.",
401
+ "put the orange in the grey bin."
402
+ ],
403
+ "ordered": false,
404
+ "revisits": false
405
+ },
406
+ "CompSplitPlate2Task": {
407
+ "subtasks": [
408
+ "put the avocado on the white plate.",
409
+ "put the orange in the grey bin."
410
+ ],
411
+ "ordered": false,
412
+ "revisits": false
413
+ },
414
+ "CompSplitPlate3Task": {
415
+ "subtasks": [
416
+ "put the avocado on the white plate.",
417
+ "put the yellow banana on the white plate.",
418
+ "put the orange in the grey bin."
419
+ ],
420
+ "ordered": false,
421
+ "revisits": false
422
+ },
423
+ "CompSplitPlate4Task": {
424
+ "subtasks": [
425
+ "put the avocado on the white plate.",
426
+ "put the yellow banana on the white plate.",
427
+ "put the orange in the grey bin.",
428
+ "put the green lime in the grey bin."
429
+ ],
430
+ "ordered": false,
431
+ "revisits": false
432
+ },
433
+ "CompSplitPlate5Task": {
434
+ "subtasks": [
435
+ "put the avocado on the white plate.",
436
+ "put the yellow banana on the white plate.",
437
+ "put the orange in the grey bin.",
438
+ "put the red onion in the grey bin.",
439
+ "put the lychee in the grey bin."
440
+ ],
441
+ "ordered": false,
442
+ "revisits": false
443
+ },
444
+ "CompSplitPlate6Task": {
445
+ "subtasks": [
446
+ "put the avocado on the white plate.",
447
+ "put the yellow banana on the white plate.",
448
+ "put the yellow lemon on the white plate.",
449
+ "put the orange in the grey bin.",
450
+ "put the green lime in the grey bin.",
451
+ "put the red onion in the grey bin."
452
+ ],
453
+ "ordered": false,
454
+ "revisits": false
455
+ },
456
+ "CompSplitPlate7Task": {
457
+ "subtasks": [
458
+ "put the avocado on the white plate.",
459
+ "put the yellow banana on the white plate.",
460
+ "put the yellow lemon on the white plate.",
461
+ "put the orange in the grey bin.",
462
+ "put the green lime in the grey bin.",
463
+ "put the red onion in the grey bin.",
464
+ "put the lychee in the grey bin."
465
+ ],
466
+ "ordered": false,
467
+ "revisits": false
468
+ },
469
+ "CompSplitPlate8Task": {
470
+ "subtasks": [
471
+ "put the avocado on the white plate.",
472
+ "put the yellow banana on the white plate.",
473
+ "put the yellow lemon on the white plate.",
474
+ "put the green lime on the white plate.",
475
+ "put the orange in the grey bin.",
476
+ "put the red onion in the grey bin.",
477
+ "put the lychee in the grey bin.",
478
+ "put the orange pumpkin in the grey bin."
479
+ ],
480
+ "ordered": false,
481
+ "revisits": false
482
+ },
483
+ "CompTransfer2Task": {
484
+ "subtasks": [
485
+ "put the orange in the grey bin.",
486
+ "put the yellow lemon in the grey bin."
487
+ ],
488
+ "ordered": false,
489
+ "revisits": false
490
+ },
491
+ "CompTransfer3Task": {
492
+ "subtasks": [
493
+ "put the orange in the grey bin.",
494
+ "put the yellow lemon in the grey bin.",
495
+ "put the green lime in the grey bin."
496
+ ],
497
+ "ordered": false,
498
+ "revisits": false
499
+ }
500
+ }
ladder/components/inference/robots/robolab/composition/entities.py ADDED
@@ -0,0 +1,41 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import dataclasses
2
+ from typing import Optional
3
+
4
+
5
+ @dataclasses.dataclass(frozen=True)
6
+ class PlacedObject:
7
+ """A graspable instance: a unique prim name, its catalog type, its authored (x, y), and the
8
+ receptacle prim it must end up on/in (``None`` for a distractor that must be left behind).
9
+ ``start_on`` names a receptacle the object is spawned resting on/in at episode start (transfer
10
+ tasks); ``None`` means it starts on the bare table."""
11
+
12
+ prim: str
13
+ _: dataclasses.KW_ONLY # the rest are keyword-only, so a construction site names what it sets
14
+ type_id: str
15
+ x: float
16
+ y: float
17
+ receptacle: Optional[str] = None
18
+ start_on: Optional[str] = None
19
+
20
+
21
+ @dataclasses.dataclass(frozen=True)
22
+ class PlacedReceptacle:
23
+ prim: str
24
+ _: dataclasses.KW_ONLY
25
+ type_id: str
26
+ x: float
27
+ y: float
28
+
29
+
30
+ @dataclasses.dataclass(frozen=True)
31
+ class Goal:
32
+ obj_id: str
33
+ receptacle: str
34
+ noun: str
35
+
36
+
37
+ @dataclasses.dataclass(frozen=True)
38
+ class Receptacle:
39
+ obj_id: str
40
+ kind: str
41
+ noun: str
ladder/components/inference/robots/robolab/composition/export_scenes.py ADDED
@@ -0,0 +1,194 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import argparse
2
+ import json
3
+ import logging
4
+ import os
5
+ import sys
6
+ import traceback
7
+
8
+ os.environ.setdefault("OMNI_KIT_ACCEPT_EULA", "YES")
9
+ # composition/ is one level under robolab/; the runfiles-staged asset tree is robolab/assets.
10
+ os.environ.setdefault(
11
+ "ROBOLAB_ASSET_DIR",
12
+ os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "assets"),
13
+ )
14
+
15
+ import cv2 # noqa: F401 -- must import before isaaclab. Do not remove
16
+ from isaaclab.app import AppLauncher
17
+
18
+ parser = argparse.ArgumentParser(
19
+ description="Render each RoboLab composition scene's start state from the over-shoulder and wrist "
20
+ "cameras, and write the scene records the decomposition benchmark is assembled from."
21
+ )
22
+ # NOT --out: add_common_eval_args contributes --output-folder-name, which makes a bare --out an
23
+ # ambiguous abbreviation and aborts argument parsing.
24
+ parser.add_argument("--out-dir", required=True, help="Output directory for the PNGs and scenes.json.")
25
+ parser.add_argument(
26
+ "--settle-updates",
27
+ type=int,
28
+ default=8,
29
+ help="Kit updates after reset to let the tiled cameras render a fresh frame.",
30
+ )
31
+ parser.add_argument(
32
+ "--scenes",
33
+ nargs="*",
34
+ default=None,
35
+ help="render only these tasks (Task class names); default renders every composition spec",
36
+ )
37
+
38
+ from robolab.eval.runner import add_common_eval_args # noqa: E402
39
+
40
+ add_common_eval_args(parser)
41
+ AppLauncher.add_app_launcher_args(parser)
42
+
43
+ args_cli, _ = parser.parse_known_args()
44
+ args_cli.enable_cameras = True
45
+
46
+ app_launcher = AppLauncher(args_cli)
47
+ simulation_app = app_launcher.app
48
+
49
+ import numpy as np # noqa: E402
50
+ import robolab.constants # noqa: E402
51
+ import torch # noqa: E402
52
+ from robolab.core.environments.factory import get_envs # noqa: E402
53
+ from robolab.core.environments.runtime import create_env # noqa: E402
54
+ from robolab.registrations.droid.auto_env_registrations_jointpos import auto_register_droid_envs # noqa: E402
55
+
56
+ from ladder.components.inference.robots.robolab.composition.specs import ( # noqa: E402
57
+ SPECS,
58
+ task_class_name,
59
+ task_target,
60
+ )
61
+
62
+ # The composition tasks live in their own modules, so they are registered by target path the way
63
+ # env_server does it. Without this the exporter renders whatever else is registered (RoboLab's
64
+ # own tasks), and every one of them fails the spec lookup below -- frames written, no records.
65
+ # --task-dirs must NOT gate this: it defaults to DEFAULT_TASK_SUBFOLDERS, i.e. it is never empty.
66
+ if not args_cli.task:
67
+ args_cli.task = [task_target(name) for name in SPECS]
68
+
69
+ # stdlib logging, as this package's other composition entry points use: ladder.core.common.logger
70
+ # needs //ladder/core/common:platform, which only env_server's target declares.
71
+ LOGGER = logging.getLogger("export_scenes")
72
+ # The plans the plan_* eval arms are served, so the benchmark's ground truth is what an eval uses.
73
+ CACHE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "decomp_cache.json")
74
+ # The two views env_server publishes to a policy, so a planner scored on these frames sees what it
75
+ # would see at reset in an eval.
76
+ CAMERAS = {"main": "over_shoulder_left_camera", "wrist": "wrist_cam"}
77
+
78
+ robolab.constants.ENABLE_SUBTASK_PROGRESS_CHECKING = False
79
+ # contact sensors ENABLED: env.step()'s termination check needs them (eval keeps them too)
80
+
81
+ try:
82
+ auto_register_droid_envs(task_dirs=args_cli.task_dirs, task=args_cli.task)
83
+ except Exception as exc: # noqa: BLE001 -- diagnostic: registration failing silently loses every task
84
+ print(f"[export_scenes] auto_register raised: {type(exc).__name__}: {exc}", flush=True)
85
+
86
+
87
+ def _to_bgr(image) -> np.ndarray:
88
+ arr = np.asarray(image)
89
+ if arr.dtype != np.uint8: # float renders arrive in [0, 1]
90
+ arr = (np.clip(arr, 0.0, 1.0) * 255).astype(np.uint8)
91
+ return cv2.cvtColor(arr[..., :3], cv2.COLOR_RGB2BGR) # drop alpha if present
92
+
93
+
94
+ def main() -> None:
95
+ with open(CACHE) as handle:
96
+ plans = json.load(handle)
97
+ plans.pop("_meta", None) # provenance header, not a scene
98
+ by_class = {task_class_name(name): spec for name, spec in SPECS.items()}
99
+ os.makedirs(args_cli.out_dir, exist_ok=True)
100
+ # get_envs(task=...) filters REGISTERED NAMES, and the composition tasks are asked for by target
101
+ # path ("tasks.py::CompBin2Task"), which matches no name -- it returns empty rather than raising.
102
+ # auto_register above registered them under their class names, so filter the full registry.
103
+ registered = get_envs()
104
+ tasks = [task for task in registered if task in by_class]
105
+ if args_cli.scenes is not None:
106
+ wanted = set(args_cli.scenes)
107
+ tasks = [task for task in tasks if task in wanted]
108
+ LOGGER.info(f"{len(registered)} env(s) registered, {len(tasks)} of them composition tasks")
109
+ LOGGER.info(f"rendering {len(tasks)} composition task(s): {tasks}")
110
+
111
+ scenes, env = [], None
112
+ for task in tasks:
113
+ try:
114
+ if env is not None:
115
+ env.close()
116
+ env, env_cfg = create_env(
117
+ task,
118
+ device=args_cli.device,
119
+ num_envs=1,
120
+ instruction_type=args_cli.instruction_type,
121
+ policy="ladder_runner",
122
+ renderer=args_cli.renderer,
123
+ rendering_mode=args_cli.rendering_type,
124
+ )
125
+ env.reset()
126
+ obs, _ = env.reset() # native double reset (robolab.eval.episode.run_episode)
127
+ # Step the full render pipeline: the reset-return image can predate the sampled poses.
128
+ hold = torch.zeros_like(env.action_manager.action)
129
+ for _ in range(args_cli.settle_updates):
130
+ obs, _, _, _, _ = env.step(hold)
131
+
132
+ # Frame names, not paths: they sit next to scenes.json, so the directory stays relocatable.
133
+ frames = {label: f"{task}__{label}.png" for label in CAMERAS}
134
+ for label, camera in CAMERAS.items():
135
+ cv2.imwrite(
136
+ os.path.join(args_cli.out_dir, frames[label]),
137
+ _to_bgr(obs["image_obs"][camera][0].detach().cpu().numpy()),
138
+ )
139
+
140
+ spec = by_class[task]
141
+ # A cache value is a plain list or {"subtasks", "ordered"} (see DecomposerConfig);
142
+ # storing the dict whole made len(subtasks) the key count.
143
+ plan = plans[task]
144
+ subtasks = plan["subtasks"] if isinstance(plan, dict) else plan
145
+ scenes.append(
146
+ {
147
+ "id": f"robolab/{task}",
148
+ "benchmark": "robolab_comp",
149
+ "scene": task,
150
+ "instruction": env_cfg.instruction,
151
+ "subtasks": subtasks,
152
+ "n_goals": len(spec.goal_objects),
153
+ "ordered": spec.ordered,
154
+ "revisits": bool(spec.via_legs),
155
+ # Part of the published schema. The registry carries the family directly; a
156
+ # distractor is an object the scene places with no receptacle to reach.
157
+ "family": spec.family,
158
+ "distractors": [o.type_id for o in spec.objects if o.receptacle is None],
159
+ # Scene contents, so a task that changes what it PLACES invalidates samples cut
160
+ # against it. The wording fields cannot see such a change.
161
+ "objects": sorted([o.prim for o in spec.objects] + [r.prim for r in spec.receptacles]),
162
+ "frames": frames,
163
+ }
164
+ )
165
+ LOGGER.info(f"rendered {task} instruction={env_cfg.instruction!r}")
166
+ except Exception: # noqa: BLE001 -- one unrenderable scene must not cost the others
167
+ LOGGER.warning(f"{task}: FAILED {traceback.format_exc(limit=2)}")
168
+
169
+ if env is not None:
170
+ env.close()
171
+ # Each scene is rendered under its own try, so a total failure still reaches here with an
172
+ # empty list and would publish an empty benchmark under a zero exit code.
173
+ if not scenes:
174
+ raise RuntimeError(f"no scene rendered out of {len(tasks)}; see the warnings above")
175
+ manifest = os.path.join(args_cli.out_dir, "scenes.json")
176
+ if args_cli.scenes is not None and os.path.isfile(manifest):
177
+ merged = {record["id"]: record for record in json.load(open(manifest))}
178
+ merged.update({record["id"]: record for record in scenes})
179
+ scenes = sorted(merged.values(), key=lambda record: record["id"])
180
+ with open(manifest, "w") as handle:
181
+ json.dump(scenes, handle, indent=1)
182
+ LOGGER.info(f"{len(scenes)}/{len(tasks)} scene(s) -> {args_cli.out_dir}/scenes.json")
183
+ simulation_app.close()
184
+
185
+
186
+ if __name__ == "__main__":
187
+ logging.basicConfig(level=logging.INFO, force=True)
188
+ try:
189
+ main()
190
+ except Exception as e: # noqa: BLE001 -- top-level handler: close the sim app before exiting
191
+ print(f"[export_scenes] Terminated with error: {e}")
192
+ traceback.print_exc()
193
+ simulation_app.close()
194
+ sys.exit(1)
ladder/components/inference/robots/robolab/composition/factory.py ADDED
@@ -0,0 +1,378 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import functools
2
+ import math
3
+ import os
4
+ import pathlib
5
+ import tempfile
6
+ from collections import OrderedDict
7
+ from typing import Dict, List, Optional
8
+
9
+ import isaaclab.envs.mdp as mdp
10
+ import robolab.constants
11
+ import torch
12
+ from isaaclab.managers import EventTermCfg as EventTerm, TerminationTermCfg as DoneTerm
13
+ from isaaclab.utils import configclass
14
+ from robolab.core.events.reset_pose import reset_pose_uniform
15
+ from robolab.core.scenes.utils import import_scene
16
+ from robolab.core.task.conditionals import (
17
+ object_in_container,
18
+ object_on_top,
19
+ objects_placed_in_container_in_order,
20
+ pick_and_place,
21
+ pick_and_place_on_surface,
22
+ )
23
+ from robolab.core.task.task import Task
24
+ from robolab.core.world.world_state import get_world
25
+
26
+ from ladder.components.inference.robots.robolab.composition.catalog import CATALOG, ON, RECEPTACLE_TYPES
27
+ from ladder.components.inference.robots.robolab.composition.specs import (
28
+ SPECS,
29
+ CompositionSpec,
30
+ advance_legs,
31
+ chain_complete,
32
+ task_class_name,
33
+ )
34
+
35
+ # Authored scene USDs go to a fixed scratch dir, off the read-only bazel-runfiles tree.
36
+ _SCENE_DIR = pathlib.Path(tempfile.gettempdir()) / "robolab_composition_scenes"
37
+
38
+ # A bare tabletop rig (base_empty.usda: table + franka mount + ground + physics) with each graspable
39
+ # and receptacle added as a direct child of `world` via a USD payload. import_scene scrapes exactly
40
+ # those direct children as single rigid bodies, so contact sensors resolve one body per name --
41
+ # unlike a runtime spawn of the raw catalog USD, whose nested bodies break the per-object filters.
42
+ _RIG_TEMPLATE = """#usda 1.0
43
+ (
44
+ defaultPrim = "world"
45
+ metersPerUnit = 1
46
+ upAxis = "Z"
47
+ )
48
+
49
+ def Xform "world"
50
+ {{
51
+ def Material "PhysicsMaterial" (
52
+ prepend apiSchemas = ["PhysicsMaterialAPI", "PhysxMaterialAPI"]
53
+ )
54
+ {{
55
+ float physics:dynamicFriction = 2
56
+ float physics:staticFriction = 2
57
+ uniform token physxMaterial:frictionCombineMode = "max"
58
+ }}
59
+
60
+ def "table" (
61
+ prepend payload = @{fixtures}/table_oak.usd@
62
+ )
63
+ {{
64
+ double3 xformOp:translate = (0.5471367990922231, 0, -0.35)
65
+ uniform token[] xformOpOrder = ["xformOp:translate"]
66
+ }}
67
+
68
+ def "franka_table" (
69
+ prepend payload = @{fixtures}/franka_table.usd@
70
+ )
71
+ {{
72
+ quatd xformOp:orient = (6.123233995736766e-17, 0, 0, 1)
73
+ double3 xformOp:translate = (-0.087, 0, 0)
74
+ uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:orient"]
75
+ }}
76
+
77
+ def Xform "GroundPlane"
78
+ {{
79
+ token visibility = "invisible"
80
+ double3 xformOp:translate = (0, 0, -0.697)
81
+ uniform token[] xformOpOrder = ["xformOp:translate"]
82
+
83
+ def Plane "CollisionPlane" (
84
+ prepend apiSchemas = ["PhysicsCollisionAPI"]
85
+ )
86
+ {{
87
+ uniform token axis = "Z"
88
+ uniform token purpose = "guide"
89
+ }}
90
+ }}
91
+ {objects}}}
92
+ """
93
+
94
+ _OBJECT_TEMPLATE = """ def "{name}" (
95
+ prepend payload = @{usd}@
96
+ )
97
+ {{
98
+ quatf xformOp:orient = (1, 0, 0, 0)
99
+ double3 xformOp:translate = ({x}, {y}, {z})
100
+ uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:orient"]
101
+ }}
102
+ """
103
+
104
+
105
+ def placed(env, obj, receptacle, kind, env_id):
106
+ """Per-object placement predicate: on-top for ON receptacles, containment otherwise."""
107
+ if kind == ON:
108
+ return object_on_top(
109
+ env,
110
+ object=[obj],
111
+ reference_object=receptacle,
112
+ logical="all",
113
+ require_gripper_detached=True,
114
+ env_id=env_id,
115
+ )
116
+ return object_in_container(
117
+ env,
118
+ object=[obj],
119
+ container=receptacle,
120
+ logical="all",
121
+ require_gripper_detached=True,
122
+ env_id=env_id,
123
+ )
124
+
125
+
126
+ def legs_success(env, objects, legs, dest, dest_kind, env_id=None):
127
+ """Every object must have completed ``legs`` IN ORDER (latched, cleared on reset) and currently
128
+ rest in ``dest``. Ordering is what makes the intermediate hops real: without it an object put
129
+ straight into the last receptacle, or one that visits the stops backwards, would pass. A revisit
130
+ names its final receptacle among the legs too, so only the order tells the two visits apart."""
131
+ world = get_world(env)
132
+ objects, legs = list(objects), list(legs)
133
+ state_key = f"legs::{'->'.join(name for name, _ in legs)}->{dest}::{','.join(objects)}"
134
+
135
+ def _make_state():
136
+ latched = {
137
+ o: [torch.zeros(env.num_envs, dtype=torch.bool, device=env.device) for _ in legs] for o in objects
138
+ }
139
+
140
+ def reset(env_ids):
141
+ for flags in latched.values():
142
+ for flag in flags:
143
+ flag[env_ids] = False
144
+
145
+ return {"latched": latched, "__reset__": reset}
146
+
147
+ latched = world.get_or_init_predicate_state(state_key, _make_state)["latched"]
148
+ result = None
149
+ for obj in objects:
150
+ holding = [placed(env, obj, name, kind, None) for name, kind in legs]
151
+ latched[obj] = advance_legs(latched[obj], holding)
152
+ ok = chain_complete(latched[obj], placed(env, obj, dest, dest_kind, None))
153
+ result = ok if result is None else result & ok
154
+ return result if env_id is None else result[env_id]
155
+
156
+
157
+ def _latched(predicate, key: str):
158
+ """Make a placement predicate stay satisfied once achieved, on episode-scoped predicate state.
159
+
160
+ A relay leg is a milestone, not an end state: lifting the object to start leg 2 makes the leg-1
161
+ check false again, so an advancer reading the raw predicate walks back onto a leg it finished and
162
+ the task becomes unwinnable. Terminal goals are deliberately NOT wrapped: an object knocked out
163
+ of its destination must un-achieve so the advancer can repair it. The wrapper carries the inner
164
+ predicate's ``__name__`` and bound nouns, which the oracle renders each subtask's command from."""
165
+ base = getattr(predicate, "func", predicate)
166
+
167
+ def latched(env, env_id=None, **_bound_nouns_for_rendering):
168
+ world = get_world(env)
169
+
170
+ def _make_state():
171
+ flag = torch.zeros(env.num_envs, dtype=torch.bool, device=env.device)
172
+
173
+ def reset(env_ids):
174
+ flag[env_ids] = False
175
+
176
+ return {"flag": flag, "__reset__": reset}
177
+
178
+ flag = world.get_or_init_predicate_state(key, _make_state)["flag"]
179
+ flag |= predicate(env, env_id=None)
180
+ return flag if env_id is None else flag[env_id]
181
+
182
+ latched.__name__ = getattr(base, "__name__", "latched")
183
+ return functools.partial(latched, **(getattr(predicate, "keywords", None) or {}))
184
+
185
+
186
+ def _latch_final_condition(subtask, key: str):
187
+ """Latch each object's score-carrying condition -- the one the oracle publishes as ``achieved``."""
188
+ for obj, conditions in subtask.conditions.items():
189
+ predicate, score = conditions[-1]
190
+ conditions[-1] = (_latched(predicate, f"{key}::{obj}"), score)
191
+ return subtask
192
+
193
+
194
+ def _author_usda(spec: CompositionSpec) -> str:
195
+ """Write the task's scene USD (base rig + one payload prim per object/receptacle) and return it."""
196
+ asset_dir = robolab.constants.ASSET_DIR
197
+ prims = []
198
+ for obj in spec.objects:
199
+ t = CATALOG[obj.type_id]
200
+ z = t.rest_z
201
+ if obj.start_on: # spawn on the source receptacle's rim, dropped slightly so it settles
202
+ z = 2 * RECEPTACLE_TYPES[obj.start_on].rest_z + t.rest_z + 0.02
203
+ prims.append(
204
+ _OBJECT_TEMPLATE.format(name=obj.prim, usd=os.path.join(asset_dir, t.usd), x=obj.x, y=obj.y, z=z)
205
+ )
206
+ for recep in spec.receptacles:
207
+ rt = RECEPTACLE_TYPES[recep.type_id]
208
+ prims.append(
209
+ _OBJECT_TEMPLATE.format(
210
+ name=recep.prim, usd=os.path.join(asset_dir, rt.usd), x=recep.x, y=recep.y, z=rt.rest_z
211
+ )
212
+ )
213
+ usda = _RIG_TEMPLATE.format(fixtures=os.path.join(asset_dir, "fixtures"), objects="".join(prims))
214
+ _SCENE_DIR.mkdir(parents=True, exist_ok=True)
215
+ path = _SCENE_DIR / f"{spec.name}.usda"
216
+ # Publish ATOMICALLY: every process rewrites these on import while running eval processes read
217
+ # them at env-creation time. A reader landing inside a truncating write loads an empty stage
218
+ # (no table, no robot, no objects), which still burns its step budget and scores as a failure.
219
+ tmp = _SCENE_DIR / f".{spec.name}.{os.getpid()}.usda.tmp"
220
+ tmp.write_text(usda)
221
+ os.replace(tmp, path)
222
+ return str(path)
223
+
224
+
225
+ def _events_cls(spec: CompositionSpec):
226
+ """Per-episode reset randomization: every graspable jittered by +/-``spec.jitter`` in x/y with a
227
+ full random yaw, collision-checked. Receptacles are omitted, so ``reset_to_default_otherwise``
228
+ pins them and the clearances the object positions were solved against stay valid."""
229
+ j = spec.jitter
230
+ event = EventTerm(
231
+ func=reset_pose_uniform,
232
+ mode="reset",
233
+ params={
234
+ "pose_range": {"x": (-j, j), "y": (-j, j), "z": (0.0, 0.0), "yaw": (-math.pi, math.pi)},
235
+ "velocity_range": {},
236
+ "asset_cfg": spec.free_object_list,
237
+ "reset_to_default_otherwise": True,
238
+ "use_collision_check": True,
239
+ },
240
+ )
241
+ return configclass(type("CompositionEvents", (), {"randomize_init_pose": event}))
242
+
243
+
244
+ def _grouped_goals(spec: CompositionSpec) -> "OrderedDict[str, List[str]]":
245
+ """receptacle_id -> [object_id, ...], in goal order (also the oracle plan order)."""
246
+ groups: "OrderedDict[str, List[str]]" = OrderedDict()
247
+ for goal in spec.goals:
248
+ groups.setdefault(goal.receptacle, []).append(goal.obj_id)
249
+ return groups
250
+
251
+
252
+ def composition_success(
253
+ env,
254
+ groups: Dict[str, List[str]],
255
+ kinds: Dict[str, str],
256
+ forbidden: Optional[Dict[str, List[str]]] = None,
257
+ env_id=None,
258
+ ):
259
+ """Whole-task success: a conjunction over receptacle groups, each an ``all`` placement check.
260
+ ``forbidden`` (distractor tasks) additionally requires no named decoy ended up in a receptacle."""
261
+ result = None
262
+ for recep_id, objs in groups.items():
263
+ if kinds[recep_id] == ON:
264
+ group_ok = object_on_top(
265
+ env,
266
+ object=objs,
267
+ reference_object=recep_id,
268
+ logical="all",
269
+ require_gripper_detached=True,
270
+ env_id=env_id,
271
+ )
272
+ else:
273
+ group_ok = object_in_container(
274
+ env,
275
+ object=objs,
276
+ container=recep_id,
277
+ logical="all",
278
+ require_gripper_detached=True,
279
+ env_id=env_id,
280
+ )
281
+ result = group_ok if result is None else result & group_ok
282
+ for recep_id, objs in (forbidden or {}).items():
283
+ intruded = object_in_container(env, object=objs, container=recep_id, logical="any", env_id=env_id)
284
+ result = result & (~intruded)
285
+ return result
286
+
287
+
288
+ def _terminations_cls(spec: CompositionSpec):
289
+ groups = _grouped_goals(spec)
290
+ if spec.via_legs:
291
+ rm = spec.receptacle_map
292
+ dest = spec.receptacles_used[0] # single by construction
293
+ success = DoneTerm(
294
+ func=legs_success,
295
+ params={
296
+ "objects": [g.obj_id for g in spec.goals],
297
+ "legs": [(name, rm[name].kind) for name in spec.via_legs],
298
+ "dest": dest,
299
+ "dest_kind": rm[dest].kind,
300
+ },
301
+ )
302
+ elif spec.ordered: # single-receptacle by construction; enforce first-placement order
303
+ success = DoneTerm(
304
+ func=objects_placed_in_container_in_order,
305
+ params={
306
+ "objects": [g.obj_id for g in spec.goals],
307
+ "container": spec.goals[0].receptacle,
308
+ "require_gripper_detached": True,
309
+ },
310
+ )
311
+ else:
312
+ kinds = {recep: spec.receptacle_map[recep].kind for recep in groups}
313
+ params: Dict[str, object] = {"groups": dict(groups), "kinds": kinds}
314
+ distractors = [o.prim for o in spec.distractor_objects]
315
+ if distractors: # single-receptacle by construction; decoys must stay out of it
316
+ params["forbidden"] = {spec.receptacles_used[0]: distractors}
317
+ success = DoneTerm(func=composition_success, params=params)
318
+ return configclass(
319
+ type(
320
+ "CompositionTerminations",
321
+ (),
322
+ {
323
+ "time_out": DoneTerm(func=mdp.time_out, time_out=True),
324
+ "success": success,
325
+ },
326
+ )
327
+ )
328
+
329
+
330
+ def _place_subtask(objs, recep_id, kind, score):
331
+ if kind == ON:
332
+ return pick_and_place_on_surface(object=objs, surface=recep_id, logical="all", score=score)
333
+ return pick_and_place(object=objs, container=recep_id, logical="all", score=score)
334
+
335
+
336
+ def _subtasks(spec: CompositionSpec):
337
+ """The oracle plan: one placement subtask PER GOAL OBJECT, in plan order. A single ``all`` group
338
+ over every object gives the advancer no per-object achieved flag, and the policy then stalls after
339
+ the first object once N >= 3. Relay emits the two-leg sequence (via, then dest) per object."""
340
+ rm = spec.receptacle_map
341
+ if spec.via_legs:
342
+ score = 1.0 / ((1 + len(spec.via_legs)) * len(spec.goals))
343
+ subtasks = []
344
+ for i, g in enumerate(spec.goals):
345
+ for leg, name in enumerate(spec.via_legs):
346
+ # Every leg but the last is LATCHED: starting the next one necessarily undoes it.
347
+ subtasks.append(
348
+ _latch_final_condition(
349
+ _place_subtask([g.obj_id], name, rm[name].kind, score),
350
+ f"{spec.name}::via{i}_{leg}",
351
+ )
352
+ )
353
+ subtasks.append(_place_subtask([g.obj_id], g.receptacle, rm[g.receptacle].kind, score))
354
+ return subtasks
355
+ score = 1.0 / len(spec.goals)
356
+ return [_place_subtask([g.obj_id], g.receptacle, rm[g.receptacle].kind, score) for g in spec.goals]
357
+
358
+
359
+ def make_task(spec_name: str):
360
+ """Build the RoboLab ``Task`` subclass for a composition spec. Called at task-file import time,
361
+ inside the env_server sim process, where the RoboLab asset tree is available."""
362
+ spec = SPECS[spec_name]
363
+ name = task_class_name(spec_name)
364
+ return type(
365
+ name,
366
+ (Task,),
367
+ {
368
+ "scene": import_scene(_author_usda(spec), tuple(spec.contact_object_list)),
369
+ "events": _events_cls(spec),
370
+ "instruction": spec.instruction,
371
+ "terminations": _terminations_cls(spec),
372
+ "subtasks": _subtasks(spec),
373
+ "contact_object_list": spec.contact_object_list,
374
+ "episode_length_s": spec.episode_length_s,
375
+ "attributes": ["composition", spec.family, f"n{spec.n}"],
376
+ "task_name": name,
377
+ },
378
+ )
ladder/components/inference/robots/robolab/composition/layout.py ADDED
@@ -0,0 +1,182 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import math
2
+ from typing import Dict, List, Optional, Tuple
3
+
4
+ _TABLE = (0.197, 0.897, -0.500, 0.500) # xmin, xmax, ymin, ymax of the tabletop
5
+ # Bare table that must stay visible beyond an object's own footprint, even at worst-case jitter. An
6
+ # object sitting at the lip is both very hard to grasp (no room for the fingers to come round it) and
7
+ # a physics hazard -- a nudge tips it off the table and the episode is unwinnable from that moment.
8
+ _EDGE_KEEP = 0.05
9
+ _RECEP_MARGIN = 0.02 # keep free objects this far outside a receptacle footprint beyond (radius + jitter)
10
+ _PAIR_MARGIN = 0.01 # slack beyond touching between two objects at worst-case jitter
11
+ _RIM_KEEP = 0.02 # bare receptacle surface beyond an object resting ON it (transfer sources)
12
+ _OBJ_RECT = (0.33, 0.72, -0.42, 0.42) # arm-reachable band; the front ~0.18 m sits behind the mount
13
+ _WORKSPACE_CENTER = (0.50, 0.0)
14
+ _GRID_NX, _GRID_NY = 33, 41
15
+ RECEP_ANCHOR_1 = (0.70, 0.0) # single receptacle: deep centre
16
+ RECEP_ANCHOR_2A = (0.72, 0.26) # split/transfer/relay: deep, pushed to the back edge to free the band
17
+ RECEP_ANCHOR_2B = (0.72, -0.26)
18
+ # How far from the base a GRASPABLE may start: grasp success drops sharply for objects starting much
19
+ # beyond ~0.63 m. Applies to start positions only; placing INTO a bin at 0.70 m is fine. 0.62 not
20
+ # 0.65 because the greedy placement is not monotone in the bound: 0.65 cannot seat ten objects at any
21
+ # ladder jitter, 0.62 seats them at 0.02.
22
+ REACH_MAX = 0.62
23
+ # Transfer and relay put graspables on a receptacle rather than the table, so the SOURCE has to obey
24
+ # the same bound: at RECEP_ANCHOR_2A the objects would rest at 0.72-0.80 m, out of comfortable reach. The
25
+ # destination stays deep.
26
+ SOURCE_ANCHOR = (0.45, 0.26)
27
+ # Jitter is DERIVED per task: each scene takes the largest value here for which a provably safe layout
28
+ # exists (nothing leaves the table, enters a receptacle or overlaps a neighbour at worst-case jitter).
29
+ JITTER_LADDER = (0.07, 0.06, 0.05, 0.04, 0.03, 0.02)
30
+
31
+ # Episode budget (s) keyed by PICK-PLACE OPERATIONS, taken from RoboLab's own medians over the 95
32
+ # benchmark tasks with a placement conditional. Forward-filled so more work never means less time; the
33
+ # tail past nine extrapolates at the ~33 s/op their large tasks settle to.
34
+ ROBOLAB_BUDGET_S = {
35
+ 1: 60,
36
+ 2: 90,
37
+ 3: 180,
38
+ 4: 180,
39
+ 5: 180,
40
+ 6: 180,
41
+ 7: 240,
42
+ 8: 270,
43
+ 9: 300,
44
+ 10: 330,
45
+ 11: 330,
46
+ 12: 330,
47
+ }
48
+
49
+
50
+ def dist(a: Tuple[float, float], b: Tuple[float, float]) -> float:
51
+ return math.hypot(a[0] - b[0], a[1] - b[1])
52
+
53
+
54
+ def _candidate_cells(
55
+ radius: float, jitter: float, reach_max: Optional[float] = None
56
+ ) -> List[Tuple[float, float]]:
57
+ """Candidate centres for one object: grid points inside the arm-reachable band that are also far
58
+ enough from every table edge that neither the jitter nor the object's own footprint can bring it
59
+ within ``_EDGE_KEEP`` of the lip, and (when ``reach_max`` is given) within that distance of the
60
+ base even at worst-case jitter. Empty when the object cannot be placed safely at all."""
61
+ m = radius + jitter + _EDGE_KEEP
62
+ xmin, xmax = max(_TABLE[0] + m, _OBJ_RECT[0]), min(_TABLE[1] - m, _OBJ_RECT[1])
63
+ ymin, ymax = max(_TABLE[2] + m, _OBJ_RECT[2]), min(_TABLE[3] - m, _OBJ_RECT[3])
64
+ if xmax <= xmin or ymax <= ymin:
65
+ return []
66
+ xs = [xmin + (xmax - xmin) * i / (_GRID_NX - 1) for i in range(_GRID_NX)]
67
+ ys = [ymin + (ymax - ymin) * j / (_GRID_NY - 1) for j in range(_GRID_NY)]
68
+ cells = [(x, y) for x in xs for y in ys]
69
+ if reach_max is None:
70
+ return cells
71
+ return [c for c in cells if math.hypot(abs(c[0]) + jitter, abs(c[1]) + jitter) <= reach_max]
72
+
73
+
74
+ def _clear_of_receptacles(
75
+ c: Tuple[float, float], radius: float, jitter: float, reserved: List[Tuple[float, float, float, float]]
76
+ ) -> bool:
77
+ """The object never overlaps a (pinned) receptacle's rectangular footprint, even at the worst jitter:
78
+ reserved entries are (x, y, half_x, half_y). A rectangular keep-out (not a circle) is what lets
79
+ objects sit beside a wide bin on the open table instead of being excluded from the whole back."""
80
+ for rx, ry, hx, hy in reserved:
81
+ if (
82
+ abs(c[0] - rx) < hx + radius + jitter + _RECEP_MARGIN
83
+ and abs(c[1] - ry) < hy + radius + jitter + _RECEP_MARGIN
84
+ ):
85
+ return False
86
+ return True
87
+
88
+
89
+ def _scatter(
90
+ radii: List[float],
91
+ reserved: List[Tuple[float, float, float, float]],
92
+ jitter: float,
93
+ reach_max: Optional[float] = None,
94
+ ) -> Optional[List[Tuple[float, float]]]:
95
+ """Authored (x, y) per object (indexed as ``radii``) for which NO per-episode jitter can push an
96
+ object off the table, under a pinned receptacle, or into a neighbour. Objects are placed
97
+ largest-first (the banana needs the most room) by farthest-point selection -- start nearest the
98
+ workspace centre, then repeatedly add the candidate maximising the minimum distance to those
99
+ already chosen -- among cells satisfying every hard constraint for that object's own radius.
100
+
101
+ The pairwise bound is what stops the scene from tearing itself apart: two objects can close by
102
+ ``2 * jitter``, so authoring them merely "far apart" (maximising the minimum distance without
103
+ asserting one) lets high-N scenes spawn interpenetrating, and the simulator resolves the overlap
104
+ by ejecting an object, sometimes off the table.
105
+
106
+ Returns None when the scene is over-full at this jitter, so callers can retry lower."""
107
+ placed: Dict[int, Tuple[float, float]] = {}
108
+ for oi in sorted(range(len(radii)), key=lambda i: -radii[i]):
109
+ r = radii[oi]
110
+ cand = [
111
+ c
112
+ for c in _candidate_cells(r, jitter, reach_max)
113
+ if _clear_of_receptacles(c, r, jitter, reserved)
114
+ and all(dist(c, p) >= r + radii[j] + 2 * jitter + _PAIR_MARGIN for j, p in placed.items())
115
+ ]
116
+ if not cand:
117
+ return None
118
+ if not placed:
119
+ placed[oi] = min(cand, key=lambda c: dist(c, _WORKSPACE_CENTER))
120
+ else:
121
+ placed[oi] = max(cand, key=lambda c: min(dist(c, p) for p in placed.values()))
122
+ return [placed[i] for i in range(len(radii))]
123
+
124
+
125
+ def fit_scatter(
126
+ radii: List[float],
127
+ reserved: List[Tuple[float, float, float, float]],
128
+ reach_max: Optional[float] = None,
129
+ ) -> Tuple[float, List[Tuple[float, float]]]:
130
+ """The most per-episode variation this scene can safely carry: the largest jitter on the ladder
131
+ that still admits a provably safe layout, together with that layout."""
132
+ for jitter in JITTER_LADDER:
133
+ positions = _scatter(radii, reserved, jitter, reach_max)
134
+ if positions is not None:
135
+ return jitter, positions
136
+ raise ValueError(
137
+ f"no safe layout for {len(radii)} objects (max radius {max(radii):.3f}) clear of "
138
+ f"{len(reserved)} receptacle(s) within reach {reach_max} at any jitter down to "
139
+ f"{JITTER_LADDER[-1]}"
140
+ )
141
+
142
+
143
+ def pull_into_reach(
144
+ anchor: Tuple[float, float], offsets: List[Tuple[float, float]], jitter: float, reach_max: Optional[float]
145
+ ) -> Tuple[float, float]:
146
+ """Slide a source receptacle straight toward the base until every object resting on it obeys
147
+ ``reach_max`` at worst-case jitter. Objects on a receptacle are laid out by ``fit_on_receptacle``,
148
+ which knows nothing about reach, so a hand-picked anchor would otherwise silently decide how far
149
+ out they start."""
150
+ if reach_max is None:
151
+ return anchor
152
+ scale = 1.0
153
+ for _ in range(200):
154
+ ax, ay = anchor[0] * scale, anchor[1] * scale
155
+ worst = max(math.hypot(abs(ax + dx) + jitter, abs(ay + dy) + jitter) for dx, dy in offsets)
156
+ if worst <= reach_max:
157
+ return (ax, ay)
158
+ scale -= 0.005
159
+ raise ValueError(f"cannot bring {anchor} within reach {reach_max}")
160
+
161
+
162
+ def fit_on_receptacle(
163
+ radii: List[float], footprint: Tuple[float, float]
164
+ ) -> Tuple[float, List[Tuple[float, float]]]:
165
+ """Same idea for objects that start resting ON a receptacle (the transfer sources): offsets from
166
+ the receptacle centre, on a concentric ring, plus the largest jitter for which every object stays
167
+ ``_RIM_KEEP`` inside the rim and no two can overlap. Randomizing these within the source, rather
168
+ than pinning them, keeps the source intact while still giving each episode a fresh draw."""
169
+ n = len(radii)
170
+ for jitter in JITTER_LADDER:
171
+ usable = min(footprint) - _RIM_KEEP - jitter - max(radii)
172
+ if usable <= 0:
173
+ continue
174
+ if n == 1:
175
+ return jitter, [(0.0, 0.0)]
176
+ need = max(radii[i] + radii[j] for i in range(n) for j in range(n) if i != j)
177
+ ring = (need + 2 * jitter + _PAIR_MARGIN) / (2 * math.sin(math.pi / n))
178
+ if ring <= usable:
179
+ return jitter, [
180
+ (ring * math.cos(2 * math.pi * k / n), ring * math.sin(2 * math.pi * k / n)) for k in range(n)
181
+ ]
182
+ raise ValueError(f"cannot fit {n} objects on a {footprint} receptacle with any ladder jitter")
ladder/components/inference/robots/robolab/composition/specs.py ADDED
@@ -0,0 +1,656 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import dataclasses
2
+ import os
3
+ from collections import OrderedDict
4
+ from typing import Dict, List, Optional, Tuple
5
+
6
+ from ladder.components.inference.api.core.instructions import Placement, compose, subtask
7
+ from ladder.components.inference.robots.robolab.composition.catalog import (
8
+ CATALOG,
9
+ FRUIT_LADDER,
10
+ RECEPTACLE_TYPES,
11
+ verb,
12
+ )
13
+ from ladder.components.inference.robots.robolab.composition.entities import (
14
+ Goal,
15
+ PlacedObject,
16
+ PlacedReceptacle,
17
+ Receptacle,
18
+ )
19
+ from ladder.components.inference.robots.robolab.composition.layout import (
20
+ JITTER_LADDER,
21
+ REACH_MAX,
22
+ RECEP_ANCHOR_1,
23
+ RECEP_ANCHOR_2A,
24
+ RECEP_ANCHOR_2B,
25
+ ROBOLAB_BUDGET_S,
26
+ SOURCE_ANCHOR,
27
+ dist,
28
+ fit_on_receptacle,
29
+ fit_scatter,
30
+ pull_into_reach,
31
+ )
32
+
33
+ # The primary N-scaling axis. It starts at 2 because the N=1 rung is SINGLES below, and stops at 10,
34
+ # the longest rung the tabletop scatters within reach.
35
+ #
36
+ # DENSE, deliberately, and it is the CONSTRAINED families that sweep it: route and ordered_bin run
37
+ # every rung from 2 to 10. That is what makes the length curve readable, because a rung's score then
38
+ # varies with length alone rather than with which family happens to reach that far.
39
+ GOAL_LADDER = range(2, 11)
40
+ # The single-destination control family is sparse where the others are dense: short, middle and long.
41
+ # It is the family the direct instruction already handles, so it is the length axis's control rather
42
+ # than a discriminator, and intermediate rungs would add episodes without adding a question.
43
+ BIN_LADDER = (2, 6, 10)
44
+ SINGLES: Tuple[Tuple[str, str], ...] = (("comp_bin_1", "bin"), ("comp_plate_1", "plate"))
45
+
46
+ # ------------------------------ scene instances ------------------------------
47
+
48
+
49
+ def task_class_name(spec_name: str) -> str:
50
+ """comp_bin_6 -> CompBin6Task (the RoboLab Task subclass name / env task_name)."""
51
+ return "".join(part.capitalize() for part in spec_name.split("_")) + "Task"
52
+
53
+
54
+ def task_target(spec_name: str) -> str:
55
+ """The RoboLab task identifier for a spec: the shared tasks module, addressing one class in it.
56
+ A bare path would resolve to whichever Task that module defines first."""
57
+ tasks_module = os.path.join(os.path.dirname(os.path.abspath(__file__)), "tasks.py")
58
+ return f"{tasks_module}::{task_class_name(spec_name)}"
59
+
60
+
61
+ @dataclasses.dataclass(frozen=True)
62
+ class CompositionSpec:
63
+ """One long-horizon composition task, fully described physically: the exact graspable
64
+ instances on the table (goals + distractors), the receptacle instances, and an optional
65
+ ordering constraint. This is the declarative unit the factory turns into a programmatic
66
+ RoboLab ``Task`` (one RigidObjectCfg per instance on a bare tabletop) and the
67
+ oracle/decomposer read as the plan. The visible object count is exactly ``len(objects)``."""
68
+
69
+ name: str
70
+ family: str # single_dest | split | distractor | ordered | transfer | relay | revisit | identical
71
+ objects: Tuple[PlacedObject, ...]
72
+ receptacles: Tuple[PlacedReceptacle, ...]
73
+ ordered: bool = False
74
+ # The receptacles each object passes through BEFORE its final one, in order. A relay names one
75
+ # ("table -> plate -> bin"); a revisit names two, the second of which is the final receptacle
76
+ # again ("table -> bin -> plate -> bin"). Empty for every family that places each object once.
77
+ via_legs: Tuple[str, ...] = ()
78
+ jitter: float = JITTER_LADDER[0] # per-episode uniform x/y jitter (m); DERIVED, see fit_scatter
79
+
80
+ def __post_init__(self) -> None:
81
+ # The reset is ONE event with ONE pose_range for every asset it randomizes, so a spec cannot
82
+ # mix objects scattered on the table with objects confined to a source receptacle -- those
83
+ # need different jitters to stay on their respective surfaces. Every family satisfies this
84
+ # (transfer puts all of its graspables on the source); this keeps it true.
85
+ if len({o.start_on is not None for o in self.objects}) > 1:
86
+ raise ValueError(
87
+ f"{self.name}: mixes table-scattered and source-resting graspables, which cannot "
88
+ f"share one reset jitter"
89
+ )
90
+
91
+ @property
92
+ def source(self) -> Optional[str]:
93
+ """Transfer tasks: the receptacle the objects start resting on (named in the instruction)."""
94
+ return next((o.start_on for o in self.objects if o.start_on), None)
95
+
96
+ @property
97
+ def goal_objects(self) -> List[PlacedObject]:
98
+ return [o for o in self.objects if o.receptacle is not None]
99
+
100
+ @property
101
+ def distractor_objects(self) -> List[PlacedObject]:
102
+ return [o for o in self.objects if o.receptacle is None]
103
+
104
+ @property
105
+ def n(self) -> int:
106
+ return len(self.goal_objects)
107
+
108
+ @property
109
+ def n_ops(self) -> int:
110
+ """Pick-and-place operations, the unit the budget scales on. Each intermediate leg is one
111
+ more move of every object: a relay moves each twice, a revisit three times."""
112
+ return (1 + len(self.via_legs)) * self.n
113
+
114
+ @property
115
+ def episode_length_s(self) -> int:
116
+ """From RoboLab's own benchmark tasks. A larger budget does not convert into more completed
117
+ episodes: horizon length is the binding constraint, not the clock."""
118
+ return ROBOLAB_BUDGET_S[min(self.n_ops, max(ROBOLAB_BUDGET_S))]
119
+
120
+ @property
121
+ def receptacle_map(self) -> Dict[str, Receptacle]:
122
+ return {
123
+ r.prim: Receptacle(r.prim, RECEPTACLE_TYPES[r.type_id].kind, RECEPTACLE_TYPES[r.type_id].noun)
124
+ for r in self.receptacles
125
+ }
126
+
127
+ @property
128
+ def goals(self) -> List[Goal]:
129
+ return [Goal(o.prim, o.receptacle, CATALOG[o.type_id].noun) for o in self.goal_objects]
130
+
131
+ @property
132
+ def receptacles_used(self) -> List[str]:
133
+ seen: List[str] = []
134
+ for g in self.goals:
135
+ if g.receptacle not in seen:
136
+ seen.append(g.receptacle)
137
+ return seen
138
+
139
+ @property
140
+ def contact_object_list(self) -> List[str]:
141
+ """Every entity tracked for pose/contact: graspables then receptacles. No ``table`` -- the
142
+ tabletop is part of the base USD, not a tracked rigid body."""
143
+ return [o.prim for o in self.objects] + [r.prim for r in self.receptacles]
144
+
145
+ @property
146
+ def free_object_list(self) -> List[str]:
147
+ """The graspables the reset randomizes: all of them. The spec's jitter is sized so no draw
148
+ can leave the intended surface. Receptacles are never listed, so they stay pinned."""
149
+ return [o.prim for o in self.objects]
150
+
151
+ @property
152
+ def instruction(self) -> str:
153
+ """The task's command, in the wording shared with SimplerEnv and RobotArena."""
154
+ rm = self.receptacle_map
155
+ stops = [*self.via_legs, self.goals[0].receptacle] if self.via_legs else None
156
+ if stops is not None:
157
+ placements = [
158
+ Placement(g.noun, verb(rm[stop].kind), rm[stop].noun) for g in self.goals for stop in stops
159
+ ]
160
+ else:
161
+ placements = [
162
+ Placement(g.noun, verb(rm[g.receptacle].kind), rm[g.receptacle].noun) for g in self.goals
163
+ ]
164
+ return compose(
165
+ placements,
166
+ sequential=self.ordered or bool(self.via_legs),
167
+ source=rm[self.source].noun if self.source else None,
168
+ excluded=[CATALOG[o.type_id].noun for o in self.distractor_objects],
169
+ )
170
+
171
+
172
+ # ------------------------------ instruction composition ------------------------------
173
+
174
+
175
+ def _instances(
176
+ type_ids: List[str],
177
+ positions: List[Tuple[float, float]],
178
+ receptacle_of: Dict[int, Optional[str]],
179
+ start_on: Optional[str] = None,
180
+ ) -> Tuple[PlacedObject, ...]:
181
+ """Build unique-primed object instances. A type used once keeps its bare name ("orange"); a
182
+ repeated type is suffixed ("orange_1", "orange_2"). Prim names are internal ids only; the
183
+ instruction noun always comes from the catalog, so suffixes never leak into language."""
184
+ counts: Dict[str, int] = {}
185
+ for t in type_ids:
186
+ counts[t] = counts.get(t, 0) + 1
187
+ seen: Dict[str, int] = {}
188
+ objs: List[PlacedObject] = []
189
+ for i, t in enumerate(type_ids):
190
+ if counts[t] == 1:
191
+ prim = t
192
+ else:
193
+ seen[t] = seen.get(t, 0) + 1
194
+ prim = f"{t}_{seen[t]}"
195
+ objs.append(
196
+ PlacedObject(
197
+ prim,
198
+ type_id=t,
199
+ x=positions[i][0],
200
+ y=positions[i][1],
201
+ receptacle=receptacle_of[i],
202
+ start_on=start_on,
203
+ )
204
+ )
205
+ return tuple(objs)
206
+
207
+
208
+ def single_dest(
209
+ name: str,
210
+ n: int,
211
+ receptacle: str = "bin",
212
+ pool: Tuple[str, ...] = FRUIT_LADDER,
213
+ family: str = "single_dest",
214
+ distractor_types: Tuple[str, ...] = (),
215
+ ordered: bool = False,
216
+ reach_max: Optional[float] = None,
217
+ ) -> CompositionSpec:
218
+ """Put the first ``n`` pool objects into one receptacle; optional decoy distractors that must
219
+ stay put. The core N-goal ladder and its distractor variants."""
220
+ rt = RECEPTACLE_TYPES[receptacle]
221
+ recep = PlacedReceptacle(receptacle, type_id=receptacle, x=RECEP_ANCHOR_1[0], y=RECEP_ANCHOR_1[1])
222
+ reserved = [(recep.x, recep.y, rt.footprint[0], rt.footprint[1])]
223
+ type_ids = list(pool[:n]) + list(distractor_types)
224
+ jitter, positions = fit_scatter([CATALOG[t].radius for t in type_ids], reserved, reach_max)
225
+ if ordered:
226
+ # An ordered rung only tests ordering if the required order FIGHTS the policy's own
227
+ # preference, and policies tend to go nearest-first. Requiring the farthest object first
228
+ # makes that prior maximally unhelpful, so a rung measures instruction-following rather than
229
+ # which layout fit_scatter happened to produce. Pairs move together, so every object keeps
230
+ # the slot fit_scatter sized for its radius.
231
+ goals = sorted(zip(type_ids[:n], positions[:n], strict=True), key=lambda tp: -dist(tp[1], (0.0, 0.0)))
232
+ type_ids = [t for t, _ in goals] + list(distractor_types)
233
+ positions = [p for _, p in goals] + list(positions[n:])
234
+ receptacle_of = {i: (receptacle if i < n else None) for i in range(len(type_ids))}
235
+ return CompositionSpec(
236
+ name=name,
237
+ family=family,
238
+ objects=_instances(type_ids, positions, receptacle_of),
239
+ receptacles=(recep,),
240
+ ordered=ordered,
241
+ jitter=jitter,
242
+ )
243
+
244
+
245
+ def split(
246
+ name: str,
247
+ groups: List[Tuple[Tuple[str, ...], str]],
248
+ family: str = "split",
249
+ reach_max: Optional[float] = None,
250
+ anchors: Optional[List[Tuple[float, float]]] = None,
251
+ reserve_as: Optional[Dict[str, str]] = None,
252
+ ) -> CompositionSpec:
253
+ """Objects partitioned across two receptacles. ``groups`` = [(object_types, receptacle_id), ...].
254
+ Receptacles sit at the two back anchors; every object is a goal (no distractors).
255
+
256
+ ``groups`` fixes BOTH the plan order and, by position, which anchor each receptacle takes.
257
+ ``anchors`` decouples them, so a variant can reorder the plan while every receptacle and object
258
+ stays exactly where the base rung puts it.
259
+
260
+ ``reserve_as`` maps a receptacle id to the type whose footprint the scatter should reserve for
261
+ it. Object placement is a function of the reserved boxes, so two rungs differing only in
262
+ receptacle otherwise get different object positions, and the resulting change in transport
263
+ distance would dominate the receptacle effect. Reserving the bowl AS a plate makes the twins
264
+ identical in layout, leaving the receptacle as the only difference. Name the LARGER type: a smaller reservation would let an object spawn overlapping
265
+ the bigger rim. Only the differing slot is remapped, so the shared bin stays where it is."""
266
+ anchors = anchors or [RECEP_ANCHOR_2A, RECEP_ANCHOR_2B]
267
+ receps = tuple(
268
+ PlacedReceptacle(rid, type_id=rid, x=anchors[k][0], y=anchors[k][1])
269
+ for k, (_, rid) in enumerate(groups)
270
+ )
271
+ reserve_as = reserve_as or {}
272
+ reserved = [(r.x, r.y, *RECEPTACLE_TYPES[reserve_as.get(r.type_id, r.type_id)].footprint) for r in receps]
273
+ type_ids: List[str] = []
274
+ recep_ids: List[str] = []
275
+ for types, rid in groups:
276
+ type_ids += list(types)
277
+ recep_ids += [rid] * len(types)
278
+ jitter, positions = fit_scatter([CATALOG[t].radius for t in type_ids], reserved, reach_max)
279
+ receptacle_of = {i: recep_ids[i] for i in range(len(type_ids))}
280
+ return CompositionSpec(
281
+ name=name,
282
+ family=family,
283
+ objects=_instances(type_ids, positions, receptacle_of),
284
+ receptacles=receps,
285
+ jitter=jitter,
286
+ )
287
+
288
+
289
+ def transfer(
290
+ name: str,
291
+ object_types: Tuple[str, ...],
292
+ source: str = "plate",
293
+ dest: str = "bin",
294
+ source_anchor: Tuple[float, float] = RECEP_ANCHOR_2A,
295
+ reach_max: Optional[float] = None,
296
+ ) -> CompositionSpec:
297
+ """Objects start resting ON/IN the ``source`` receptacle and must be moved to ``dest``. Success
298
+ only requires them in ``dest`` (the source is a scene fixture, not a goal); the "from the source"
299
+ is expressed by the initial state + instruction (mirrors SimplerEnv's transfer family). The
300
+ objects are laid out on a ring within the source and re-drawn every episode, with a jitter sized
301
+ so no draw can leave the source's top surface."""
302
+ dst = PlacedReceptacle(dest, type_id=dest, x=RECEP_ANCHOR_2B[0], y=RECEP_ANCHOR_2B[1])
303
+ radii = [CATALOG[t].radius for t in object_types]
304
+ jitter, offsets = fit_on_receptacle(radii, RECEPTACLE_TYPES[source].footprint)
305
+ anchor = pull_into_reach(source_anchor, offsets, jitter, reach_max)
306
+ src = PlacedReceptacle(source, type_id=source, x=anchor[0], y=anchor[1])
307
+ positions = [(src.x + dx, src.y + dy) for dx, dy in offsets]
308
+ objects = _instances(
309
+ list(object_types), positions, {i: dest for i in range(len(object_types))}, start_on=source
310
+ )
311
+ return CompositionSpec(
312
+ name=name, family="transfer", objects=objects, receptacles=(src, dst), jitter=jitter
313
+ )
314
+
315
+
316
+ def relay(
317
+ name: str,
318
+ object_types: Tuple[str, ...],
319
+ via: str = "plate",
320
+ dest: str = "bin",
321
+ via_anchor: Tuple[float, float] = RECEP_ANCHOR_2A,
322
+ reach_max: Optional[float] = None,
323
+ ) -> CompositionSpec:
324
+ """Objects start on the table and must be relayed table -> ``via`` -> ``dest``. Success is a
325
+ latched milestone (each object must pass through ``via`` before its placement in ``dest`` counts),
326
+ so a direct table->dest delivery does not satisfy it (mirrors SimplerEnv's relay family)."""
327
+ via_r = PlacedReceptacle(via, type_id=via, x=via_anchor[0], y=via_anchor[1])
328
+ dst_r = PlacedReceptacle(dest, type_id=dest, x=RECEP_ANCHOR_2B[0], y=RECEP_ANCHOR_2B[1])
329
+ reserved = [
330
+ (via_r.x, via_r.y, *RECEPTACLE_TYPES[via].footprint),
331
+ (dst_r.x, dst_r.y, *RECEPTACLE_TYPES[dest].footprint),
332
+ ]
333
+ jitter, positions = fit_scatter([CATALOG[t].radius for t in object_types], reserved, reach_max)
334
+ objects = _instances(list(object_types), positions, {i: dest for i in range(len(object_types))})
335
+ return CompositionSpec(
336
+ name=name,
337
+ family="relay",
338
+ objects=objects,
339
+ receptacles=(via_r, dst_r),
340
+ ordered=True,
341
+ via_legs=(via,),
342
+ jitter=jitter,
343
+ )
344
+
345
+
346
+ def revisit(
347
+ name: str,
348
+ object_types: Tuple[str, ...],
349
+ home: str = "bin",
350
+ away: str = "plate",
351
+ away_anchor: Tuple[float, float] = RECEP_ANCHOR_2A,
352
+ reach_max: Optional[float] = None,
353
+ ) -> CompositionSpec:
354
+ """Objects go table -> ``home`` -> ``away`` -> ``home``: the last leg returns each object to a
355
+ receptacle it has already left, which no end state can witness, since the first visit is undone
356
+ by the second leg. Only the ORDER separates the two visits to ``home``, so the legs latch in
357
+ sequence (see :func:`advance_legs`)."""
358
+ away_r = PlacedReceptacle(away, type_id=away, x=away_anchor[0], y=away_anchor[1])
359
+ home_r = PlacedReceptacle(home, type_id=home, x=RECEP_ANCHOR_2B[0], y=RECEP_ANCHOR_2B[1])
360
+ reserved = [
361
+ (away_r.x, away_r.y, *RECEPTACLE_TYPES[away].footprint),
362
+ (home_r.x, home_r.y, *RECEPTACLE_TYPES[home].footprint),
363
+ ]
364
+ jitter, positions = fit_scatter([CATALOG[t].radius for t in object_types], reserved, reach_max)
365
+ objects = _instances(list(object_types), positions, {i: home for i in range(len(object_types))})
366
+ return CompositionSpec(
367
+ name=name,
368
+ family="revisit",
369
+ objects=objects,
370
+ receptacles=(away_r, home_r),
371
+ ordered=True,
372
+ via_legs=(home, away),
373
+ jitter=jitter,
374
+ )
375
+
376
+
377
+ def identical(
378
+ name: str, obj_type: str, n: int, receptacle: str = "bin", reach_max: Optional[float] = None
379
+ ) -> CompositionSpec:
380
+ """``n`` instances of the SAME object into one receptacle -- a counting task ("put the 3 lemons in
381
+ the bin"). Tracks multi-instance / matched-count success, as in the SimplerEnv/RobotArena
382
+ extended benchmarks."""
383
+ return single_dest(
384
+ name, n, receptacle=receptacle, pool=(obj_type,) * n, family="identical", reach_max=reach_max
385
+ )
386
+
387
+
388
+ # --------------------------------- benchmark matrix ---------------------------------
389
+
390
+
391
+ def _build_specs() -> "OrderedDict[str, CompositionSpec]":
392
+ specs: List[CompositionSpec] = []
393
+
394
+ for single_name, single_recep in SINGLES:
395
+ specs.append(single_dest(single_name, 1, receptacle=single_recep, reach_max=REACH_MAX))
396
+
397
+ # Family A - single-destination ladder into a bin, the primary N-scaling axis. Three rungs,
398
+ # short/middle/long, rather than every N: this is the family the direct instruction already
399
+ # handles, so it is the length axis's control, not a discriminator, and intermediate rungs add
400
+ # episodes without adding a question.
401
+ for n in BIN_LADDER:
402
+ specs.append(single_dest(f"comp_bin_{n}", n, reach_max=REACH_MAX))
403
+
404
+ # Family B - distractors present: put the fruit in the bin while non-fruit blocks sit on the
405
+ # table and must be left behind (goals are pure fruit so "all the fruit" is unambiguous).
406
+ #
407
+ # Deliberately only TWO rungs. Exclusion reads as a composition constraint but mostly tests
408
+ # low-level grounding (a policy told "put the lemon in the bin" may take the block anyway), and
409
+ # ground-truth subtasks barely help, so more rungs would add floor rather than discrimination.
410
+ specs.append(
411
+ single_dest(
412
+ "comp_bin_2_distractor",
413
+ 2,
414
+ family="distractor",
415
+ distractor_types=("red_block",),
416
+ reach_max=REACH_MAX,
417
+ )
418
+ )
419
+ specs.append(
420
+ single_dest(
421
+ "comp_bin_4_distractor",
422
+ 4,
423
+ family="distractor",
424
+ distractor_types=("red_block", "blue_block"),
425
+ reach_max=REACH_MAX,
426
+ )
427
+ )
428
+
429
+ # Family D - ordered sequence into a bin (distinct objects so the required order is meaningful).
430
+ # The sharpest discriminator the suite has: a flat policy can place every object and still fail
431
+ # by delivering them in an arbitrary order. It spans N rather than sitting at one rung because a
432
+ # policy that ignores
433
+ # the order has an exactly known success rate, 1/N! -- 1/2, 1/6, 1/24, 1/120 -- so the rungs form
434
+ # a null curve that a real ordering capability must beat, and that a decomposing system should
435
+ # hold flat against. N=2 is a weak rung on its own (a coin flip) and is kept as that curve's
436
+ # anchor, not as a test.
437
+ # Swept over the full GOAL_LADDER so the long end of the length axis is not held by one family.
438
+ for n in GOAL_LADDER:
439
+ specs.append(
440
+ single_dest(f"comp_ordered_bin_{n}", n, family="ordered", ordered=True, reach_max=REACH_MAX)
441
+ )
442
+
443
+ # Family E - transfer: objects start on the plate, move them all to the bin.
444
+ for types in (("orange", "lemon"), ("orange", "lemon", "lime")):
445
+ specs.append(
446
+ transfer(
447
+ f"comp_transfer_{len(types)}",
448
+ types,
449
+ source_anchor=SOURCE_ANCHOR,
450
+ reach_max=REACH_MAX,
451
+ )
452
+ )
453
+
454
+ # Family F - relay: table -> plate -> bin, milestone-enforced. The milestone needs an object that
455
+ # RESTS on the plate, which rules out the orange (a sphere), the avocado and the onion (both
456
+ # taller than they are wide). It does NOT rule out the banana: at radius/rest_z 4.45 it is the
457
+ # FLATTEST thing in the catalog, ahead of lemon (1.46) and lime (1.27).
458
+ #
459
+ # A third object does not have to SHARE the plate (the banana's 17.8 cm long axis does not fit
460
+ # beside others on a 16.6 cm plate): advance_legs chains leg k on every earlier leg latching, so
461
+ # an object may be relayed on its own and the plate is only ever asked to hold one. Co-residency
462
+ # is permitted (an early placement that still holds when the leg before it latches counts), not
463
+ # required. So comp_relay_3 is solvable object-by-object, but NOT by the collective reading
464
+ # "first put everything on the plate".
465
+ # NOTE ON THE NAMES: this family is parameterised by OBJECT count while goal counts are
466
+ # placements, so comp_relay_N is a 2N-goal task (comp_revisit_N a 3N-goal one). The names are
467
+ # kept for stability; goal counts are placements everywhere else.
468
+ for objs in (
469
+ ("lemon", "lime"),
470
+ ("lemon", "lime", "banana"),
471
+ ("lemon", "lime", "banana", "orange"),
472
+ ("lemon", "lime", "banana", "orange", "avocado"),
473
+ ):
474
+ specs.append(relay(f"comp_relay_{len(objs)}", objs, via_anchor=SOURCE_ANCHOR, reach_max=REACH_MAX))
475
+ # revisit, as in the SimplerEnv composition benchmark. One object keeps the chain
476
+ # short enough that the budget still covers three moves of it.
477
+ for objs in (("lemon",), ("lemon", "lime")):
478
+ specs.append(
479
+ revisit(f"comp_revisit_{len(objs)}", objs, away_anchor=SOURCE_ANCHOR, reach_max=REACH_MAX)
480
+ )
481
+
482
+ # Family H - routing with the plate side held to objects that rest flat by construction. Family
483
+ # C-b covers the plate/bin split; these vary the goal count on a nested ladder
484
+ # (2 subset 4 subset 6) with the receptacle question already settled.
485
+ for n, (to_plate, to_bin) in (
486
+ (2, (("lemon",), ("orange",))),
487
+ (3, (("lemon", "lime"), ("orange",))),
488
+ (4, (("lemon", "lime"), ("orange", "avocado"))),
489
+ (5, (("lemon", "lime", "banana"), ("orange", "avocado"))),
490
+ (6, (("lemon", "lime", "banana"), ("orange", "avocado", "onion"))),
491
+ ):
492
+ specs.append(
493
+ split(
494
+ f"comp_route_{n}", [(to_plate, "plate"), (to_bin, "bin")], family="route", reach_max=REACH_MAX
495
+ )
496
+ )
497
+
498
+ # The long end of the routing ladder, so the long rungs are not held by comp_bin_N alone. These
499
+ # take FRUIT_LADDER[:n] (the SAME objects comp_bin_n uses at that rung) and split them across two receptacles, so route_n against
500
+ # bin_n is one instruction naming two destinations against one naming a single destination, with
501
+ # the object set held fixed. The plate side is the three objects that rest flat by construction
502
+ # (banana 4.45, lemon 1.46, lime 1.27 on radius/rest_z); everything else goes to the walled bin,
503
+ # where shape does not matter. Nests with comp_route_6, which is already FRUIT_LADDER[:6].
504
+ _PLATE_SAFE = ("banana", "lemon", "lime")
505
+ for n in range(7, 11):
506
+ pool = FRUIT_LADDER[:n]
507
+ to_plate = tuple(o for o in pool if o in _PLATE_SAFE)
508
+ to_bin = tuple(o for o in pool if o not in _PLATE_SAFE)
509
+ specs.append(
510
+ split(
511
+ f"comp_route_{n}",
512
+ [(to_plate, "plate"), (to_bin, "bin")],
513
+ family="route",
514
+ reach_max=REACH_MAX,
515
+ )
516
+ )
517
+
518
+ # comp_route_2 with the PLAN ORDER reversed and nothing else. Explicit anchors undo the swap
519
+ # `groups` would otherwise cause, so both receptacles and both objects stay exactly where
520
+ # comp_route_2 puts them. Isolates whether a completed goal is lost because it sits exposed for
521
+ # the whole of the next subtask, or because the policy re-engages an object it has placed.
522
+ specs.append(
523
+ split(
524
+ "comp_route_2_binfirst",
525
+ [(("orange",), "bin"), (("lemon",), "plate")],
526
+ family="route",
527
+ reach_max=REACH_MAX,
528
+ anchors=[RECEP_ANCHOR_2B, RECEP_ANCHOR_2A],
529
+ )
530
+ )
531
+
532
+ # A third rung for revisit, a family the direct instruction handles poorly.
533
+ specs.append(
534
+ revisit("comp_revisit_3", ("lemon", "lime", "banana"), away_anchor=SOURCE_ANCHOR, reach_max=REACH_MAX)
535
+ )
536
+
537
+ # Family C-b - the SPLIT family on a plate. A bin paired with a BOWL does not measure routing:
538
+ # both receptacles are dark and deep, the scene reads as one container, and policies confuse
539
+ # them. A plate is visually distinct from the bin, so these rungs test routing itself.
540
+ #
541
+ # Rungs 5, 7 and 8 exist to give the LENGTH axis a third routing family: without them 5 and 7
542
+ # carried only comp_ordered_bin_N and comp_route_N, so a step in the ladder there was a step in
543
+ # two families rather than a property of the horizon. The plate group is capped at the four
544
+ # objects that rest stably on a flat unwalled surface (avocado, banana, lemon, lime); everything
545
+ # rounder rolls off and would score the asset rather than the routing. That cap is also why the
546
+ # family stops at eight: nine would need a fifth plate object, and the only candidates left are
547
+ # the pomegranate, which policies rarely place, and orange2, whose subtask renders identically
548
+ # to the first orange's. comp_route_N carries the
549
+ # ladder at nine and ten.
550
+ for n, (to_plate, to_bin) in (
551
+ (2, (("avocado",), ("orange",))),
552
+ (3, (("avocado", "banana"), ("orange",))),
553
+ (4, (("avocado", "banana"), ("orange", "lime"))),
554
+ (5, (("avocado", "banana"), ("orange", "onion", "lychee"))),
555
+ (6, (("avocado", "banana", "lemon"), ("orange", "lime", "onion"))),
556
+ (7, (("avocado", "banana", "lemon"), ("orange", "lime", "onion", "lychee"))),
557
+ (8, (("avocado", "banana", "lemon", "lime"), ("orange", "onion", "lychee", "pumpkin"))),
558
+ ):
559
+ specs.append(
560
+ split(
561
+ f"comp_split_plate_{n}",
562
+ [(to_plate, "plate"), (to_bin, "bin")],
563
+ family="split_plate",
564
+ reach_max=REACH_MAX,
565
+ )
566
+ )
567
+
568
+ # Family G - identical instances (counting): N copies of one object into the bin.
569
+ # TWO RUNGS ONLY, and deliberately. Duplicates is a family the direct instruction already
570
+ # solves about as well as the privileged oracle, so rungs past four would add length to the suite without adding anything an orchestrator could win. A family the
571
+ # flat policy handles reliably serves as a type control, not as a ladder.
572
+ for n, obj in ((2, "orange"), (4, "lime")):
573
+ specs.append(identical(f"comp_identical_{n}", obj, n, reach_max=REACH_MAX))
574
+
575
+ return OrderedDict((s.name, s) for s in specs)
576
+
577
+
578
+ SPECS: "OrderedDict[str, CompositionSpec]" = _build_specs()
579
+
580
+
581
+ def advance_legs(latched, holding):
582
+ """Advance a per-object leg chain by one observation, returning the updated latch flags.
583
+
584
+ ``latched[k]`` says leg k was completed at some earlier step, ``holding[k]`` that its placement
585
+ holds right now. A leg latches only once every leg before it has, which is what separates a
586
+ relay from two unrelated placements: an object dropped straight into the last receptacle never
587
+ passed through the intermediate one, and one that visits them in the wrong order did not either.
588
+ Latches never clear, since finishing leg k+1 necessarily undoes leg k.
589
+
590
+ Operates on anything supporting ``|`` and ``&`` elementwise, so the same rule serves the batched
591
+ boolean tensors the simulator produces and the plain booleans the tests use.
592
+ """
593
+ updated, prior = [], None
594
+ for was, now in zip(latched, holding, strict=True):
595
+ step = (was | now) if prior is None else (was | (now & prior))
596
+ updated.append(step)
597
+ prior = step
598
+ return updated
599
+
600
+
601
+ def chain_complete(latched, holding_final):
602
+ """A leg chain is done when every intermediate leg has latched AND the final placement holds
603
+ NOW: an object knocked back out of its last receptacle has not completed the task."""
604
+ done = holding_final
605
+ for was in latched:
606
+ done = done & was
607
+ return done
608
+
609
+
610
+ def _plan_name(colour: str, noun: str) -> str:
611
+ return f"{colour} {noun}".strip()
612
+
613
+
614
+ def decomp_plan(spec: CompositionSpec) -> Dict[str, object]:
615
+ """The cached plan for a spec, one command per goal in order, naming objects by colour and type.
616
+
617
+ The colour separates look-alikes: told a bare noun, a policy can confuse e.g. the lemon and the
618
+ orange. The task's own instruction stays on plain nouns.
619
+ """
620
+ receptacle_type = {r.prim: RECEPTACLE_TYPES[r.type_id] for r in spec.receptacles}
621
+
622
+ def command(obj: PlacedObject, receptacle_prim: str) -> str:
623
+ source, target = CATALOG[obj.type_id], receptacle_type[receptacle_prim]
624
+ return subtask(
625
+ Placement(
626
+ _plan_name(source.colour, source.noun),
627
+ verb(target.kind),
628
+ _plan_name(target.colour, target.noun),
629
+ )
630
+ )
631
+
632
+ if spec.via_legs:
633
+ legs = [command(o, stop) for o in spec.goal_objects for stop in (*spec.via_legs, o.receptacle)]
634
+ return {"subtasks": legs, "ordered": True, "revisits": True}
635
+ return {
636
+ "subtasks": [command(o, o.receptacle) for o in spec.goal_objects],
637
+ "ordered": bool(spec.ordered),
638
+ "revisits": False,
639
+ }
640
+
641
+
642
+ def decomp_cache_entries() -> Dict[str, object]:
643
+ """{task_class_name: plan} for every composition spec, to merge into decomp_cache.json."""
644
+ return {task_class_name(name): decomp_plan(spec) for name, spec in SPECS.items()}
645
+
646
+
647
+ if __name__ == "__main__":
648
+ for spec in SPECS.values():
649
+ instr = spec.instruction
650
+ objs = ", ".join(f"{o.prim}@({o.x:.2f},{o.y:.2f})" for o in spec.objects)
651
+ print(
652
+ f"{spec.name:22s} n={spec.n:2d} fam={spec.family:11s} "
653
+ f"objs={len(spec.objects):2d} len={spec.episode_length_s:4d}s"
654
+ )
655
+ print(f" instruction: {instr}")
656
+ print(f" layout: {objs}")
ladder/components/inference/robots/robolab/composition/tasks.py ADDED
@@ -0,0 +1,9 @@
 
 
 
 
 
 
 
 
 
 
1
+ from ladder.components.inference.robots.robolab.composition.factory import make_task
2
+ from ladder.components.inference.robots.robolab.composition.specs import SPECS, task_class_name
3
+
4
+ # One RoboLab Task subclass per composition spec, all in this module: RoboLab discovers tasks by
5
+ # scanning a module for Task subclasses, and env_server addresses a single one as
6
+ # "<this file>::<ClassName>" (see specs.task_target). Built from SPECS rather than written out so a
7
+ # spec can never be added without its task.
8
+ for _spec_name in SPECS:
9
+ globals()[task_class_name(_spec_name)] = make_task(_spec_name)
ladder/components/inference/robots/robolab/droid_conversions.py ADDED
@@ -0,0 +1,161 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import time
2
+ from typing import Any, Dict, List, Optional, Tuple
3
+
4
+ import numpy as np
5
+ from openpi_client import image_tools
6
+
7
+ from ladder.components.inference.api.core.action import EndEffectorPoseAction, JointAnglesAction, RobotAction
8
+ from ladder.components.inference.api.core.observation import RobotStateType
9
+ from ladder.components.inference.robots.robolab.franka_kinematics import FrankaKinematics
10
+ from ladder.core.common.logger import get_logger
11
+
12
+ LOGGER = get_logger(__name__)
13
+
14
+
15
+ # Every Franka joint limit is within +-3.1 rad, so anything past this is a diverged articulation
16
+ # that merely has not reached NaN yet. Checking only for non-finite values would let huge joint
17
+ # readings through IK and feed the runaway back into the sim.
18
+ _JOINT_SANE_RAD = 6.5
19
+
20
+
21
+ # Per-env maintained EE target + FK/IK between ladder EE-pose actions and 8-DoF jointpos.
22
+ class DroidJointposConverter:
23
+ def __init__(
24
+ self,
25
+ num_envs: int,
26
+ max_joint_step_rad: float = 0.5,
27
+ image_size: Tuple[int, int] = (224, 224),
28
+ ) -> None:
29
+ self._kinematics = FrankaKinematics()
30
+ self._max_joint_step_rad = max_joint_step_rad
31
+ self._image_width, self._image_height = image_size
32
+ # Per-env maintained EE target (4x4); None => seed from the observed pose.
33
+ self._target_poses: List[Optional[np.ndarray]] = [None] * num_envs
34
+ self._degenerate: List[bool] = [False] * num_envs # logged once per env per episode
35
+ # Last finite in-range joint vector per env: the freeze target for a diverged env.
36
+ # Commanding zeros instead would be a full-authority PD slam toward the upright pose,
37
+ # which can turn a marginal trip into a runaway that carries into the next episode.
38
+ self._last_sane: List[Optional[np.ndarray]] = [None] * num_envs
39
+
40
+ def observation_dict(
41
+ self,
42
+ env_i: int,
43
+ main_image: np.ndarray,
44
+ wrist_image: np.ndarray,
45
+ joints: np.ndarray,
46
+ gripper_position: np.ndarray,
47
+ metadata: Dict[str, Any],
48
+ scene_image: Optional[np.ndarray] = None,
49
+ right_image: Optional[np.ndarray] = None,
50
+ ) -> Dict[str, Any]:
51
+ # RobotObservation field dict (what RobotEnv reconstructs client-side).
52
+ joints = np.asarray(joints, dtype=np.float32)
53
+ eef_pose = self._kinematics.forward(joints).astype(np.float32)
54
+ if self._target_poses[env_i] is None:
55
+ self._target_poses[env_i] = eef_pose
56
+ return {
57
+ # Native-path parity: RoboLab's client resizes with the same call before serving.
58
+ # The size is the consumer's, not the sim's.
59
+ # "scene" is the depth camera's own framing, unpadded: "main" is letterboxed to a
60
+ # square, so image coordinates on it do not map onto the depth frame. A consumer that
61
+ # reads depth through the image needs "scene"; the padded inputs are unchanged.
62
+ "images": {
63
+ "main": image_tools.resize_with_pad(main_image, self._image_height, self._image_width),
64
+ "wrist": image_tools.resize_with_pad(wrist_image, self._image_height, self._image_width),
65
+ **({"scene": scene_image} if scene_image is not None else {}),
66
+ **(
67
+ {}
68
+ if right_image is None
69
+ else {
70
+ "right": image_tools.resize_with_pad(
71
+ right_image, self._image_height, self._image_width
72
+ )
73
+ }
74
+ ),
75
+ },
76
+ "state": {
77
+ "type": RobotStateType.SINGLE_MANIPULATOR.value,
78
+ "eef_pose": eef_pose,
79
+ "eef_pose_from_target": self._target_poses[env_i],
80
+ "gripper_state": 1.0
81
+ - np.atleast_1d(np.asarray(gripper_position, dtype=np.float32)), # RoboLab 0=open
82
+ "joints": joints,
83
+ },
84
+ "timestamps": np.array([time.time()], dtype=np.float64),
85
+ "metadata": metadata,
86
+ }
87
+
88
+ # Ladder action -> [7 clamped joint targets, binary gripper] (RoboLab wire). An end-effector
89
+ # pose is solved with inverse kinematics; joint angles are already the commanded quantity. Both
90
+ # go through the same divergence guard and per-step clamp below.
91
+ def actions_to_jointpos(self, actions: List[RobotAction], current_joints: np.ndarray) -> np.ndarray:
92
+ current = np.asarray(current_joints, dtype=np.float32)
93
+ solve = [
94
+ env_i
95
+ for env_i, action in enumerate(actions)
96
+ if isinstance(action.arm_action, EndEffectorPoseAction)
97
+ and np.all(np.isfinite(current[env_i]))
98
+ and np.abs(current[env_i]).max() <= _JOINT_SANE_RAD
99
+ ]
100
+ inverses = {}
101
+ if solve:
102
+ try:
103
+ poses = np.stack([actions[env_i].arm_action.to_homogeneous_matrix() for env_i in solve])
104
+ inverses = dict(zip(solve, self._kinematics.inverse(poses, current[solve]), strict=True))
105
+ except Exception as error: # noqa: BLE001
106
+ LOGGER.warn(
107
+ f"envs {solve}: IK solve failed ({error!r}); freezing at current joints this step"
108
+ )
109
+ return np.stack(
110
+ [
111
+ self.action_to_jointpos(env_i, action, current[env_i], inverses.get(env_i, current[env_i]))
112
+ for env_i, action in enumerate(actions)
113
+ ]
114
+ )
115
+
116
+ def action_to_jointpos(
117
+ self, env_i: int, action: RobotAction, current_joints: np.ndarray, inverse: np.ndarray
118
+ ) -> np.ndarray:
119
+ arm_action = action.arm_action
120
+ if isinstance(arm_action, JointAnglesAction):
121
+ target_pose = None
122
+ elif isinstance(arm_action, EndEffectorPoseAction):
123
+ target_pose = np.asarray(arm_action.to_homogeneous_matrix(), dtype=np.float64)
124
+ self._target_poses[env_i] = target_pose.astype(np.float32)
125
+ else:
126
+ raise TypeError(f"unsupported arm action: {type(arm_action).__name__}")
127
+ current = np.asarray(current_joints, dtype=np.float32)
128
+ # An exploded env feeds NaN joints -> singular Jacobian -> LinAlgError that would kill the
129
+ # whole multi-env server; command a constant for just that env instead (its episode times
130
+ # out on its own), and freeze it at the current pose on any solver failure.
131
+ if not np.all(np.isfinite(current)) or np.abs(current).max() > _JOINT_SANE_RAD:
132
+ if not self._degenerate[env_i]:
133
+ self._degenerate[env_i] = True
134
+ LOGGER.warn(
135
+ f"env {env_i}: diverged joints (max |q| = {np.nanmax(np.abs(current)):.3g} rad); "
136
+ "freezing at last sane pose until reset"
137
+ )
138
+ LOGGER.warn(
139
+ f"env {env_i}: joint vector at trip: "
140
+ f"{np.array2string(current, precision=2, max_line_width=300)}"
141
+ )
142
+ frozen = self._last_sane[env_i]
143
+ if frozen is None:
144
+ frozen = np.clip(np.nan_to_num(current), -_JOINT_SANE_RAD, _JOINT_SANE_RAD)
145
+ return np.concatenate([frozen, [0.0]]).astype(np.float32)
146
+ self._degenerate[env_i] = False
147
+ self._last_sane[env_i] = current.copy()
148
+ if target_pose is None:
149
+ inverse = np.asarray(arm_action.angles, dtype=np.float32)
150
+ if not np.all(np.isfinite(inverse)):
151
+ LOGGER.warn(f"env {env_i}: IK returned non-finite solution; freezing at current joints this step")
152
+ inverse = current
153
+ joint_step = np.clip(
154
+ inverse - current,
155
+ -self._max_joint_step_rad,
156
+ self._max_joint_step_rad,
157
+ )
158
+ # Native-path parity: the serve flips (ladder 1.0=open -> RoboLab 0=open), then RoboLab's
159
+ # client binarizes the chunk's gripper at 0.5 (Pi0DroidJointposClient._postprocess_chunk).
160
+ gripper = 1.0 if (1.0 - float(action.gripper_action)) > 0.5 else 0.0
161
+ return np.concatenate([current + joint_step, [gripper]]).astype(np.float32)
ladder/components/inference/robots/robolab/env_server.py ADDED
@@ -0,0 +1,553 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import argparse
2
+ import os
3
+ import sys
4
+
5
+ os.environ.setdefault("OMNI_KIT_ACCEPT_EULA", "YES")
6
+ # @robolab_repo ships no assets; point its constants.py at the runfiles-staged tree before any import.
7
+ os.environ.setdefault(
8
+ "ROBOLAB_ASSET_DIR",
9
+ os.path.join(os.path.dirname(os.path.abspath(__file__)), "assets"),
10
+ )
11
+
12
+ import cv2 # must be imported before isaaclab. Do not move
13
+ from isaaclab.app import AppLauncher
14
+
15
+
16
+ def _build_parser() -> argparse.ArgumentParser:
17
+ parser = argparse.ArgumentParser(description="Serve RoboLab envs over ladder's RobotServer protocol.")
18
+ parser.add_argument("--port", type=int, required=True, help="ZMQ request-reply port.")
19
+ parser.add_argument(
20
+ "--expose-privileged",
21
+ action="store_true",
22
+ help="Publish ground-truth composition geometry for the scripted completability policy.",
23
+ )
24
+ parser.add_argument(
25
+ "--publish-depth",
26
+ action="store_true",
27
+ help="Render depth and publish it with the camera calibration, for a camera-based policy.",
28
+ )
29
+ parser.add_argument(
30
+ "--no-render",
31
+ action="store_true",
32
+ help="Render no camera, for a policy that reads no image (the scripted one). Physics is unchanged.",
33
+ )
34
+ parser.add_argument(
35
+ "--exterior-cameras",
36
+ type=int,
37
+ choices=(1, 2),
38
+ default=1,
39
+ help="Exterior views to render and publish; 2 adds the over-shoulder right camera.",
40
+ )
41
+ parser.add_argument(
42
+ "--image-size",
43
+ type=int,
44
+ nargs=2,
45
+ metavar=("WIDTH", "HEIGHT"),
46
+ default=(224, 224),
47
+ help="Size of the published camera images; set it to what the policy was trained on.",
48
+ )
49
+ return parser
50
+
51
+
52
+ # AppLauncher must launch the sim app before the sim-dependent (# noqa: E402) imports below.
53
+ parser = _build_parser()
54
+
55
+ from robolab.eval.runner import add_common_eval_args # noqa: E402
56
+
57
+ add_common_eval_args(parser)
58
+ AppLauncher.add_app_launcher_args(parser)
59
+
60
+ args_cli, _ = parser.parse_known_args()
61
+ args_cli.enable_cameras = True
62
+
63
+ app_launcher = AppLauncher(args_cli)
64
+ simulation_app = app_launcher.app
65
+
66
+ import carb.settings # noqa: E402
67
+ import numpy as np # noqa: E402
68
+ import omni.kit.app # noqa: E402
69
+ import omni.timeline # noqa: E402
70
+ import robolab.constants # noqa: E402
71
+ import torch # noqa: E402
72
+ from robolab.core.environments.factory import get_envs # noqa: E402
73
+ from robolab.core.environments.runtime import create_env # noqa: E402
74
+ from robolab.core.metrics.compute_metrics import compute_episode_metrics # noqa: E402
75
+ from robolab.registrations.droid.auto_env_registrations_jointpos import auto_register_droid_envs # noqa: E402
76
+ from robolab.registrations.droid.camera_presets import WRIST_LEFT, WRIST_LEFT_RIGHT # noqa: E402
77
+ from robolab.variations.camera import with_depth # noqa: E402
78
+
79
+ from ladder.components.inference.api.core.action import RobotAction # noqa: E402
80
+ from ladder.components.inference.api.core.observation import METADATA_CAMERAS_KEY, encode_camera # noqa: E402
81
+ from ladder.components.inference.api.core.privileged_state import METADATA_PRIVILEGED_KEY # noqa: E402
82
+ from ladder.components.inference.api.core.request_reply import ( # noqa: E402
83
+ ZmqRequestReplyServer,
84
+ ZmqRequestReplyServerConfig,
85
+ )
86
+ from ladder.components.inference.api.core.requests import RequestType # noqa: E402
87
+ from ladder.components.inference.robots.robolab.composition.specs import ( # noqa: E402
88
+ SPECS,
89
+ decomp_cache_entries,
90
+ task_class_name,
91
+ task_target,
92
+ )
93
+ from ladder.components.inference.robots.robolab.droid_conversions import DroidJointposConverter # noqa: E402
94
+ from ladder.components.inference.robots.robolab.oracle import build_oracle # noqa: E402
95
+ from ladder.components.inference.robots.robolab.privileged import privileged_state # noqa: E402
96
+ from ladder.core.common.logger import get_logger # noqa: E402
97
+
98
+ LOGGER = get_logger(__name__)
99
+
100
+ # MODE=ladder never uses RoboLab's own per-step subtask recorder: subtask boundaries are logged by
101
+ # ladder's RecorderWrapper (run_model side) and the oracle's per-goal achieved flags are computed here
102
+ # in _get_observations, not by that recorder. Leaving it enabled also crashes on the droid robot
103
+ # (its get_wrong_object_grabbed -> gripper_fully_closed path looks up an articulation named "robot",
104
+ # which world_state does not resolve), so keep it off regardless of the shared --enable-subtask flag.
105
+ robolab.constants.ENABLE_SUBTASK_PROGRESS_CHECKING = False
106
+
107
+ # Kit mutes USD diagnostics by default, which hides renderer failures such as payload geometry
108
+ # being evicted mid-episode.
109
+ carb.settings.get_settings().set("/persistent/app/usd/muteUsdDiagnostics", False)
110
+
111
+ # A composition task is named by its spec (comp_bin_2); everything else is a RoboLab task name or
112
+ # path, passed through. Both register and are then served under the Task class name.
113
+ _requested = args_cli.task or []
114
+ # One view leaves the camera set at robolab's own default; two matches the layout some DROID
115
+ # policies were post-trained on. The second costs GPU, so it is opt-in.
116
+ _CAMERAS = WRIST_LEFT_RIGHT if args_cli.exterior_cameras == 2 else None
117
+ if args_cli.publish_depth:
118
+ # with_depth extends each camera's data_types, leaving the rgb-only registration alone.
119
+ _CAMERAS = [with_depth(camera) for camera in _CAMERAS or WRIST_LEFT]
120
+ auto_register_droid_envs(
121
+ task_dirs=None if _requested and all(t in SPECS for t in _requested) else args_cli.task_dirs,
122
+ task=[task_target(t) if t in SPECS else t for t in _requested] or None,
123
+ cameras=_CAMERAS,
124
+ )
125
+ _TASKS = [task_class_name(t) if t in SPECS else t for t in _requested]
126
+ # Task class name -> whether its spec is scored as a sequence, for the oracle metadata below.
127
+ _ORDERED_TASKS = {task_class_name(name): spec.ordered for name, spec in SPECS.items()}
128
+ # Task class name -> whether a repeated subtask moves the SAME object again (a relay/revisit leg).
129
+ _REVISIT_TASKS = {task_class_name(name): bool(spec.via_legs) for name, spec in SPECS.items()}
130
+ # Task class name -> the spec's own plan. The oracle publishes THIS wording, so the privileged arm
131
+ # and the planner arms (served the same list from decomp_cache.json) command identical text and
132
+ # differ only in where the plan came from.
133
+ _PLAN_SUBTASKS = {name: entry["subtasks"] for name, entry in decomp_cache_entries().items()}
134
+
135
+
136
+ def _half(frame) -> np.ndarray:
137
+ """The camera's own frame at half size and UNPADDED, to pair with the depth it publishes.
138
+
139
+ Only the aspect ratio has to match the depth frame for normalized coordinates to map, and
140
+ halving each side preserves it exactly while quartering what goes over the wire.
141
+ """
142
+ image = frame.detach().cpu().numpy()
143
+ return cv2.resize(image, (image.shape[1] // 2, image.shape[0] // 2), interpolation=cv2.INTER_AREA)
144
+
145
+
146
+ def _transform(position: np.ndarray, quaternion_wxyz: np.ndarray) -> np.ndarray:
147
+ """A 4x4 pose from a position and a wxyz quaternion, the shape Isaac reports."""
148
+ w, x, y, z = (float(v) for v in np.asarray(quaternion_wxyz, dtype=np.float64).reshape(4))
149
+ matrix = np.eye(4)
150
+ matrix[:3, :3] = np.array(
151
+ [
152
+ [1 - 2 * (y * y + z * z), 2 * (x * y - w * z), 2 * (x * z + w * y)],
153
+ [2 * (x * y + w * z), 1 - 2 * (x * x + z * z), 2 * (y * z - w * x)],
154
+ [2 * (x * z - w * y), 2 * (y * z + w * x), 1 - 2 * (x * x + y * y)],
155
+ ]
156
+ )
157
+ matrix[:3, 3] = np.asarray(position, dtype=np.float64).reshape(3)
158
+ return matrix
159
+
160
+
161
+ class RobolabServer:
162
+ def __init__(self, args: argparse.Namespace) -> None:
163
+ self._args = args
164
+ task_envs = get_envs(task=_TASKS) if _TASKS else get_envs()
165
+ self._batches = [(task, run) for task in task_envs for run in range(args.num_runs)]
166
+ self._batch_index = 0
167
+ self._task = None
168
+ self._env = None
169
+ self._env_cfg = None
170
+ self._converter = None
171
+ self._raw_obs = None
172
+ self._step_count = 0
173
+ self._oracle = None # (oracle command strings, per-goal checks) for the current task
174
+ self._prev_achieved = None # last logged privileged achieved vector, per batch
175
+ self._metrics_dt = None
176
+ self._ee_body_index = None
177
+ self._traj = None # per-env post-step trajectory samples for the current batch
178
+ self._metrics = None # per-env computed metric dicts (see _reset)
179
+ self._timeline = omni.timeline.get_timeline_interface()
180
+ self._kit_app = omni.kit.app.get_app()
181
+ LOGGER.info(
182
+ f"Serving {len(self._batches)} batches: {len(task_envs)} task(s) x {args.num_runs} run(s)"
183
+ )
184
+
185
+ def handle(self, message):
186
+ request_type = message.get("type")
187
+ if request_type == RequestType.RESET.value:
188
+ return self._reset()
189
+ if request_type == RequestType.GET_OBSERVATIONS.value:
190
+ return self._get_observations()
191
+ if request_type == RequestType.EXEC_ACTION.value:
192
+ return self._execute_actions(message["data"])
193
+ return {"status": "ok"} # CONNECT / EXIT
194
+
195
+ def _reset(self):
196
+ if self._batch_index >= len(self._batches):
197
+ return {"status": "finished"}
198
+ task, run_index = self._batches[self._batch_index]
199
+ self._batch_index += 1
200
+
201
+ if task != self._task:
202
+ if self._env is not None:
203
+ self._env.close()
204
+ self._env, self._env_cfg = create_env(
205
+ task,
206
+ device=self._args.device,
207
+ num_envs=self._args.num_envs,
208
+ instruction_type=self._args.instruction_type,
209
+ policy="ladder_runner",
210
+ renderer=self._args.renderer,
211
+ rendering_mode=self._args.rendering_type,
212
+ )
213
+ self._task = task
214
+ if self._args.no_render:
215
+ # Isaac Lab's own switch: skips the Kit app loop and the RTX camera render, not physics.
216
+ getattr(self._env, "unwrapped", self._env).render_enabled = False
217
+ # Env-owned oracle: the per-goal checks from the task's own subtask spec, paired below
218
+ # with the composition spec's plan (or, for RoboLab's own tasks, commands rendered from
219
+ # the goal predicates).
220
+ self._oracle = build_oracle(getattr(self._env.cfg, "subtasks", None), self._env_cfg.instruction)
221
+ # The achieved vector is per-task, so a lane moving to a task with a different goal
222
+ # count would die on the strict zip below. Start the new task with no history.
223
+ self._prev_achieved = None
224
+ # Trajectory-metric inputs, matching the native hdf5 recorder: dt = sim.dt x decimation,
225
+ # EE body resolved like PostStepEndEffectorPoseRecorder (exact "base_link", then substring).
226
+ unwrapped = getattr(self._env, "unwrapped", self._env)
227
+ self._metrics_dt = float(unwrapped.cfg.sim.dt * unwrapped.cfg.decimation)
228
+ body_names = unwrapped.scene["robot"].data.body_names
229
+ self._ee_body_index = (
230
+ body_names.index("base_link")
231
+ if "base_link" in body_names
232
+ else next((i for i, name in enumerate(body_names) if "base_link" in name), None)
233
+ )
234
+ if self._ee_body_index is None:
235
+ LOGGER.warn(f"no base_link EE body among {body_names}; trajectory metrics disabled")
236
+ else:
237
+ self._env.reset_eval_state()
238
+ obs, _ = self._env.reset()
239
+ obs, _ = self._env.reset() # native double reset (robolab.eval.episode.run_episode)
240
+ self._raw_obs = obs
241
+ self._step_count = 0
242
+ # Per batch: the next task's oracle has its own number of goals, and an episode starts with
243
+ # nothing achieved, so a vector carried over here would both mis-diff and mis-zip.
244
+ self._prev_achieved = None
245
+ self._converter = DroidJointposConverter(
246
+ num_envs=self._env.num_envs, image_size=tuple(args_cli.image_size)
247
+ )
248
+ self._traj = [
249
+ {
250
+ "ee_position": [],
251
+ "ee_linear_velocity": [],
252
+ "joint_position": [],
253
+ "joint_velocity": [],
254
+ "actions": [],
255
+ }
256
+ for _ in range(self._env.num_envs)
257
+ ]
258
+ # None = episode still running; {} = closed but too short for metrics; else the metric dict.
259
+ self._metrics = [None] * self._env.num_envs
260
+ self._diverged = set()
261
+ self._wedged = set()
262
+ LOGGER.info(
263
+ f"Batch {self._batch_index}/{len(self._batches)} task={task} run={run_index} "
264
+ f"instruction={self._env_cfg.instruction!r}"
265
+ )
266
+ return {"status": "ok", "n_envs": self._env.num_envs}
267
+
268
+ _MAIN_CAMERA = "over_shoulder_left_camera"
269
+ _base_logged = False
270
+
271
+ def _camera_payloads(self, image_obs):
272
+ """Per-env calibrated depth frames for the main camera, or None when depth is off.
273
+
274
+ ``"depth"`` aliases ``distance_to_image_plane``, so the buffer is already metres along the
275
+ optical axis, not ray length. Poses are relative to the articulation root, the frame
276
+ ``eef_pose`` is computed in.
277
+ """
278
+ if not self._args.publish_depth:
279
+ return None
280
+ key = next(
281
+ (k for k in image_obs if self._MAIN_CAMERA in k and "depth" in k.lower()),
282
+ None,
283
+ )
284
+ if key is None:
285
+ raise RuntimeError(
286
+ f"publish_depth is set but no depth observation was found; image_obs has "
287
+ f"{sorted(image_obs)}"
288
+ )
289
+ depth = image_obs[key].detach().cpu().numpy().astype(np.float32)
290
+ if depth.ndim == 4 and depth.shape[-1] == 1:
291
+ depth = depth[..., 0]
292
+ sensor = self._env.unwrapped.scene[self._MAIN_CAMERA]
293
+ intrinsics = sensor.data.intrinsic_matrices.detach().cpu().numpy()
294
+ cam_pos = sensor.data.pos_w.detach().cpu().numpy()
295
+ # quat_w_ros is a Warp quatf: ordered XYZW despite the name.
296
+ cam_quat_xyzw = sensor.data.quat_w_ros.detach().cpu().numpy()
297
+ cam_quat = np.concatenate([cam_quat_xyzw[:, 3:4], cam_quat_xyzw[:, :3]], axis=1)
298
+ # root_quat_w is XYZW too.
299
+ robot = self._env.unwrapped.scene["robot"]
300
+ base_pos = robot.data.root_pos_w.detach().cpu().numpy()
301
+ base_quat_xyzw = robot.data.root_quat_w.detach().cpu().numpy()
302
+ if not self._base_logged:
303
+ self._base_logged = True
304
+ # Logged once: a wrong base frame misses every reach while every number looks fine.
305
+ origin = self._env.unwrapped.scene.env_origins.detach().cpu().numpy()[0]
306
+ LOGGER.info(
307
+ f"camera base frame: root={np.round(base_pos[0] - origin, 4).tolist()} rel env_origin, "
308
+ f"quat_xyzw={np.round(base_quat_xyzw[0], 4).tolist()}, bodies={list(robot.data.body_names)[:6]}"
309
+ )
310
+ base_quat = np.concatenate([base_quat_xyzw[:, 3:4], base_quat_xyzw[:, :3]], axis=1)
311
+ payloads = []
312
+ for env_i in range(len(depth)):
313
+ k = intrinsics[env_i] if intrinsics.ndim == 3 else intrinsics
314
+ world_from_base = _transform(base_pos[env_i], base_quat[env_i])
315
+ world_from_camera = _transform(cam_pos[env_i], cam_quat[env_i])
316
+ payloads.append(
317
+ encode_camera(
318
+ depth_m=depth[env_i].astype(np.float32),
319
+ intrinsics=k,
320
+ base_from_camera=np.linalg.inv(world_from_base) @ world_from_camera,
321
+ )
322
+ )
323
+ return payloads
324
+
325
+ def _get_observations(self):
326
+ if self._env is None or self._raw_obs is None:
327
+ return {"status": "error", "message": "Environment not initialized"}
328
+ image_obs = self._raw_obs["image_obs"]
329
+ cameras = self._camera_payloads(image_obs)
330
+ proprio = self._raw_obs["proprio_obs"]
331
+ results = self._env.get_env_results()
332
+ active = set(self._env.active_env_ids)
333
+ # Belt against a never-freezing env; RoboLab's own time_out termination freezes first.
334
+ max_steps_reached = self._step_count >= int(self._env.max_episode_length)
335
+ commands, achieved_all, plan_subtasks = None, None, None
336
+ if self._oracle:
337
+ commands = [goal.command for goal in self._oracle]
338
+ plan_subtasks = _PLAN_SUBTASKS.get(self._task)
339
+ if plan_subtasks is not None and len(plan_subtasks) != len(commands):
340
+ LOGGER.warn(
341
+ f"{self._task}: spec plan has {len(plan_subtasks)} subtasks but the env oracle has "
342
+ f"{len(commands)} goals; publishing the env's own commands"
343
+ )
344
+ plan_subtasks = None
345
+ plan_subtasks = plan_subtasks or commands
346
+ try:
347
+ achieved_all = [
348
+ [bool(goal.check(self._env, env_id=env_i)) for goal in self._oracle]
349
+ for env_i in range(self._env.num_envs)
350
+ ]
351
+ except Exception as error:
352
+ LOGGER.exception( # noqa: PLE1205
353
+ f"Per-goal oracle checks failed for {self._task}; falling back to single-goal", error
354
+ )
355
+ achieved_all = None
356
+ # Log every change of the privileged achieved vector. This is the oracle progress trace the
357
+ # eval protocol reports per-goal progress from, and it is the only way to tell a goal that
358
+ # was never reached from one that was reached and then UN-achieved: a goal flipping
359
+ # True -> False means its predicate is instantaneous rather than a latched milestone, which
360
+ # sends the advancer backwards onto work it already finished.
361
+ if achieved_all is not None:
362
+ prev = self._prev_achieved
363
+ if prev != achieved_all:
364
+ LOGGER.info(f"ORACLE_ACHIEVED {achieved_all}")
365
+ if prev is not None:
366
+ for env_i, (was, now) in enumerate(zip(prev, achieved_all, strict=True)):
367
+ lost = [i for i, (a, b) in enumerate(zip(was, now, strict=True)) if a and not b]
368
+ if lost:
369
+ LOGGER.warn(f"ORACLE_UNACHIEVED env {env_i}: goals {lost} went True->False")
370
+ self._prev_achieved = [list(a) for a in achieved_all]
371
+
372
+ privileged = (
373
+ privileged_state(getattr(self._env, "unwrapped", self._env), self._oracle, achieved_all)
374
+ if self._args.expose_privileged and self._oracle and achieved_all is not None
375
+ else None
376
+ )
377
+
378
+ data = []
379
+ for env_i in range(self._env.num_envs):
380
+ success = bool(results[env_i]["success"])
381
+ truncated = max_steps_reached or env_i not in active
382
+ if (success or truncated) and self._metrics[env_i] is None:
383
+ # Episode just closed: native metric set over the trajectory up to this step.
384
+ traj = {key: np.asarray(values) for key, values in self._traj[env_i].items()}
385
+ self._metrics[env_i] = (
386
+ compute_episode_metrics(traj, dt=self._metrics_dt) if len(traj["ee_position"]) else None
387
+ ) or {}
388
+ metadata = {
389
+ "env_name": self._task,
390
+ "robot_name": "franka",
391
+ "instruction": self._env_cfg.instruction,
392
+ "done": success,
393
+ "truncated": truncated,
394
+ # Privileged ground truth for oracle HLCs (PrivilegedDecomposer/Advancer): the
395
+ # synthesized per-goal commands paired with each goal's task-spec condition
396
+ # (robolab/oracle.py). A task with no subtask spec publishes the
397
+ # single-goal form: the instruction with the env-side success predicate.
398
+ "oracle": {
399
+ "subtasks": plan_subtasks,
400
+ "achieved": achieved_all[env_i],
401
+ # A composition spec scored as a sequence (relay, revisit, ordered) publishes it,
402
+ # so the oracle arm walks the chain in the order its cached plan already gives
403
+ # the planner arms. RoboLab's own tasks carry no such spec and stay unordered.
404
+ "ordered": _ORDERED_TASKS.get(self._task, False),
405
+ "revisits": _REVISIT_TASKS.get(self._task, False),
406
+ }
407
+ if achieved_all is not None
408
+ else {"subtasks": [self._env_cfg.instruction], "achieved": [success]},
409
+ }
410
+ if self._metrics[env_i]:
411
+ metadata["metrics"] = self._metrics[env_i]
412
+ if privileged is not None:
413
+ metadata[METADATA_PRIVILEGED_KEY] = privileged[env_i]
414
+ if cameras is not None:
415
+ metadata[METADATA_CAMERAS_KEY] = {"scene": cameras[env_i]}
416
+ data.append(
417
+ self._converter.observation_dict(
418
+ env_i=env_i,
419
+ main_image=image_obs["over_shoulder_left_camera"][env_i].detach().cpu().numpy(),
420
+ wrist_image=image_obs["wrist_cam"][env_i].detach().cpu().numpy(),
421
+ scene_image=(_half(image_obs["over_shoulder_left_camera"][env_i]) if cameras else None),
422
+ right_image=(
423
+ None
424
+ if "over_shoulder_right_camera" not in image_obs
425
+ else image_obs["over_shoulder_right_camera"][env_i].detach().cpu().numpy()
426
+ ),
427
+ joints=proprio["arm_joint_pos"][env_i].detach().cpu().numpy(),
428
+ gripper_position=proprio["gripper_pos"][env_i].detach().cpu().numpy(),
429
+ metadata=metadata,
430
+ )
431
+ )
432
+ return {"status": "ok", "data": data[0] if self._env.num_envs == 1 else data}
433
+
434
+ def _execute_actions(self, payload):
435
+ if self._env is None or self._raw_obs is None:
436
+ return {"status": "error", "message": "Environment not initialized"}
437
+ if isinstance(payload, dict) and "actions" in payload:
438
+ actions = [RobotAction.from_dict(action_dict) for action_dict in payload["actions"]]
439
+ else:
440
+ actions = [RobotAction.from_dict(payload)]
441
+ if len(actions) != self._env.num_envs:
442
+ return {
443
+ "status": "error",
444
+ "message": f"expected {self._env.num_envs} actions, got {len(actions)}",
445
+ }
446
+
447
+ joints = self._raw_obs["proprio_obs"]["arm_joint_pos"].detach().cpu().numpy()
448
+ commands = self._converter.actions_to_jointpos(actions, joints)
449
+ while not self._timeline.is_playing():
450
+ self._kit_app.update()
451
+ obs, _, _, _, _ = self._env.step(torch.as_tensor(commands, device=self._env.device))
452
+ self._raw_obs = obs
453
+ self._step_count += 1
454
+ self._record_trajectory(commands)
455
+ self._log_divergence(obs, commands)
456
+ return {"success": True}
457
+
458
+ def _record_trajectory(self, commands: np.ndarray) -> None:
459
+ """One post-step sample per still-running env, from the same articulation state the native
460
+ hdf5 recorder writes (PostStepEndEffectorPoseRecorder: env-local EE position, world EE
461
+ linear velocity), the inputs of robolab's compute_episode_metrics."""
462
+ if self._ee_body_index is None:
463
+ return
464
+ unwrapped = getattr(self._env, "unwrapped", self._env)
465
+ robot = unwrapped.scene["robot"]
466
+ ee_pos = robot.data.body_pos_w[:, self._ee_body_index] - unwrapped.scene.env_origins
467
+ ee_pos = ee_pos.detach().cpu().numpy()
468
+ ee_vel = robot.data.body_lin_vel_w[:, self._ee_body_index].detach().cpu().numpy()
469
+ joint_pos = robot.data.joint_pos.detach().cpu().numpy()
470
+ joint_vel = robot.data.joint_vel.detach().cpu().numpy()
471
+ for env_i in range(self._env.num_envs):
472
+ if self._metrics[env_i] is not None:
473
+ continue # episode closed: trajectory stays at its terminal step, like a native demo
474
+ traj = self._traj[env_i]
475
+ traj["ee_position"].append(ee_pos[env_i])
476
+ traj["ee_linear_velocity"].append(ee_vel[env_i])
477
+ traj["joint_position"].append(joint_pos[env_i])
478
+ traj["joint_velocity"].append(joint_vel[env_i])
479
+ traj["actions"].append(commands[env_i])
480
+
481
+ def _log_divergence(self, obs, commands):
482
+ """Dump the physics state the first time an env's joints go non-finite.
483
+
484
+ The blow-up is silent, so this is the only place the cause is still visible: a joint-velocity
485
+ ramp over several steps means the position drive was driven unstable, a one-step jump means a
486
+ contact impulse, and objects going non-finite alongside the arm means the whole scene
487
+ diverged rather than the articulation alone.
488
+ """
489
+ joints = obs["proprio_obs"]["arm_joint_pos"]
490
+ scene = getattr(self._env, "unwrapped", self._env)
491
+ scene = getattr(scene, "scene", None)
492
+ robot = scene["robot"] if scene is not None else None
493
+ if robot is not None:
494
+ # Gripper wedge detector: the Robotiq joints are physically bounded at ~1.05 rad, so
495
+ # a linkage past 2.0 rad is bent/wrecked even though it is far below the 6.5-rad ARM
496
+ # sanity threshold. Phrased as "diverged joints" so report filters that exclude
497
+ # diverged episodes pick these up unchanged.
498
+ grip_q = robot.data.joint_pos[:, 7:]
499
+ wedged = torch.isfinite(grip_q).all(dim=-1) & (
500
+ torch.nan_to_num(grip_q).abs().max(dim=-1).values > _GRIP_WEDGE_RAD
501
+ )
502
+ for env_i in wedged.nonzero(as_tuple=False).flatten().tolist():
503
+ if env_i in self._wedged or env_i in self._diverged:
504
+ continue
505
+ self._wedged.add(env_i)
506
+ LOGGER.warn(
507
+ f"env {env_i}: diverged joints (gripper linkage wedged, max |q| = "
508
+ f"{float(grip_q[env_i].abs().max()):.3g} rad); flagging episode"
509
+ )
510
+ finite = torch.isfinite(joints).all(dim=-1)
511
+ for env_i in (~finite).nonzero().flatten().tolist():
512
+ if env_i in self._diverged:
513
+ continue
514
+ self._diverged.add(env_i)
515
+ objs = "n/a"
516
+ if scene is not None:
517
+ try:
518
+ objs = (
519
+ ",".join(
520
+ name
521
+ for name, obj in scene.rigid_objects.items()
522
+ if not torch.isfinite(obj.data.root_pos_w[env_i]).all()
523
+ )
524
+ or "none"
525
+ )
526
+ except Exception as error: # noqa: BLE001 -- diagnostic only; the message carries the cause
527
+ objs = f"unreadable ({error!r})"
528
+ LOGGER.warn(
529
+ f"DIVERGENCE env {env_i} step {self._step_count} task {self._task}: "
530
+ f"nonfinite_objects=[{objs}] "
531
+ f"commanded={commands[env_i].round(3).tolist()}"
532
+ )
533
+
534
+
535
+ # Gripper joint magnitude that means the linkage is bent/wrecked (its physical limits are
536
+ # ~1.05 rad) while staying far below the arm sanity threshold. Detects the wedge class that
537
+ # degrades episodes without an arm explosion.
538
+ _GRIP_WEDGE_RAD = 2.0
539
+
540
+
541
+ def main() -> None:
542
+ server = ZmqRequestReplyServer(ZmqRequestReplyServerConfig(port=args_cli.port, recv_timeout_ms=120000))
543
+ server.start(RobolabServer(args_cli).handle)
544
+ simulation_app.close()
545
+
546
+
547
+ if __name__ == "__main__":
548
+ try:
549
+ main()
550
+ except Exception as error:
551
+ LOGGER.exception("[env_server] Terminated with error", error) # noqa: PLE1205
552
+ simulation_app.close()
553
+ sys.exit(1)
ladder/components/inference/robots/robolab/export_robolab_results.py ADDED
@@ -0,0 +1,56 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import argparse
2
+ import json
3
+ import os
4
+
5
+ import yaml
6
+
7
+
8
+ def main() -> None:
9
+ parser = argparse.ArgumentParser(
10
+ description="Map a ladder-runner campaign (episode_log.yaml) to RoboLab's episode_results.jsonl."
11
+ )
12
+ parser.add_argument("--episode-log", required=True, help="episode_log.yaml from the ladder runner.")
13
+ parser.add_argument("--output-dir", required=True, help="Directory for episode_results.jsonl.")
14
+ parser.add_argument("--policy", default="ladder_vlam", help="Policy label stamped into records.")
15
+ args = parser.parse_args()
16
+
17
+ with open(args.episode_log) as f:
18
+ episode_log = yaml.safe_load(f) or []
19
+
20
+ # Batches arrive in order per task; number them 0.. like RoboLab's run index.
21
+ batch_to_run = {}
22
+ per_task_runs = {}
23
+ records = []
24
+ for entry in episode_log:
25
+ task = entry["env_name"]
26
+ batch_key = (task, entry.get("batch", entry.get("episode")))
27
+ if batch_key not in batch_to_run:
28
+ batch_to_run[batch_key] = per_task_runs.get(task, 0)
29
+ per_task_runs[task] = batch_to_run[batch_key] + 1
30
+ run_index = batch_to_run[batch_key]
31
+ records.append(
32
+ {
33
+ "task_name": task,
34
+ "run_name": f"{task}_{run_index}",
35
+ "run": run_index,
36
+ "env_id": entry.get("batch_env_index", 0),
37
+ "policy": args.policy,
38
+ "instruction": entry.get("instruction", ""),
39
+ "success": bool(entry["success"]),
40
+ "episode_step": entry["num_steps"],
41
+ "metrics": entry.get("metrics", {}),
42
+ "events": {},
43
+ "timing": {},
44
+ }
45
+ )
46
+
47
+ os.makedirs(args.output_dir, exist_ok=True)
48
+ output_path = os.path.join(args.output_dir, "episode_results.jsonl")
49
+ with open(output_path, "w") as f:
50
+ for record in records:
51
+ f.write(json.dumps(record) + "\n")
52
+ print(f"Wrote {len(records)} records to {output_path}")
53
+
54
+
55
+ if __name__ == "__main__":
56
+ main()
ladder/components/inference/robots/robolab/franka_kinematics.py ADDED
@@ -0,0 +1,72 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from pathlib import Path
2
+
3
+ import numpy as np
4
+ import pytorch_kinematics as pk
5
+ import torch
6
+ from pytorch_kinematics.ik import delta_pose
7
+ from pytorch_kinematics.transforms import rotation_conversions
8
+
9
+ from ladder.core.common.platform import REPO_ROOT
10
+
11
+ # panda_link8 (flange) is ladder's canonical DROID EE frame; pytorch_kinematics keeps this torch/numpy-2 native.
12
+ _PANDA_URDF = Path(REPO_ROOT) / "ladder/components/urdf/robots/panda/robot.urdf"
13
+ _EEF_LINK = "panda_link8"
14
+
15
+ # Franka Panda joint position limits (rad).
16
+ _JOINT_LIMITS_LOWER = [-2.7437, -1.7837, -2.9007, -3.0421, -2.8065, 0.5445, -3.0159]
17
+ _JOINT_LIMITS_UPPER = [2.7437, 1.7837, 2.9007, -0.1518, 2.8065, 4.5169, 3.0159]
18
+
19
+
20
+ class FrankaKinematics:
21
+ def __init__(self) -> None:
22
+ with open(_PANDA_URDF) as urdf_file:
23
+ self._chain = pk.build_serial_chain_from_urdf(urdf_file.read(), _EEF_LINK).to(dtype=torch.float32)
24
+ self._joint_limits = torch.tensor([_JOINT_LIMITS_LOWER, _JOINT_LIMITS_UPPER], dtype=torch.float32).T
25
+ self._solver = pk.PseudoInverseIK(
26
+ self._chain,
27
+ retry_configs=torch.zeros(1, 7),
28
+ joint_limits=self._joint_limits,
29
+ max_iterations=100,
30
+ pos_tolerance=1e-4,
31
+ rot_tolerance=1e-3,
32
+ early_stopping_any_converged=True,
33
+ )
34
+
35
+ def forward(self, joint_position: np.ndarray) -> np.ndarray:
36
+ joints = torch.as_tensor(np.array(joint_position, dtype=np.float32)).reshape(1, -1)
37
+ pose = self._chain.forward_kinematics(joints, end_only=True).get_matrix()[0].numpy()
38
+ # A diverged sim step can report non-finite joints; a neutral pose keeps the rotation orthonormal
39
+ # so one diverged env doesn't crash the whole batched collate.
40
+ return pose if np.isfinite(pose).all() else np.eye(4, dtype=np.float32)
41
+
42
+ def inverse(self, target_poses: np.ndarray, seed_joint_positions: np.ndarray) -> np.ndarray:
43
+ q = torch.as_tensor(np.array(seed_joint_positions, dtype=np.float32))
44
+ target = torch.as_tensor(np.array(target_poses, dtype=np.float32)).reshape(-1, 4, 4)
45
+ target_pos = target[:, :3, 3]
46
+ target_wxyz = rotation_conversions.matrix_to_quaternion(target[:, :3, :3])
47
+ remaining = torch.ones(len(q), dtype=torch.bool)
48
+ err_min, no_improve = None, None
49
+ with torch.no_grad():
50
+ for _ in range(self._solver.max_iterations):
51
+ if not remaining.any():
52
+ break
53
+ jacobian, pose = self._chain.jacobian(q, ret_eef_pose=True)
54
+ dx, pos_diff, rot_diff = delta_pose(pose.view(-1, 1, 4, 4), target_pos, target_wxyz)
55
+ dq = self._solver.compute_dq(jacobian, dx).squeeze(2)
56
+ q = torch.where(remaining.unsqueeze(1), q + self._solver.lr * dq, q)
57
+ converged = (pos_diff.squeeze(2).norm(dim=-1) < self._solver.pos_tolerance) & (
58
+ rot_diff.squeeze(2).norm(dim=-1) < self._solver.rot_tolerance
59
+ )
60
+ remaining &= ~converged
61
+ err = dx.squeeze(2).norm(dim=-1)
62
+ if no_improve is None:
63
+ no_improve = torch.zeros_like(err)
64
+ elif err_min is None:
65
+ err_min = err.clone()
66
+ else:
67
+ improved = err < err_min
68
+ err_min[improved] = err[improved]
69
+ no_improve[improved] = 0
70
+ no_improve[~improved] += 1
71
+ remaining &= no_improve <= self._solver.early_stopping_no_improvement_patience
72
+ return q.numpy()
ladder/components/inference/robots/robolab/oracle.py ADDED
@@ -0,0 +1,145 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import dataclasses
2
+ import re
3
+ from typing import Callable, Dict, List, Optional, Sequence, Tuple
4
+
5
+ from ladder.core.common.logger import get_logger
6
+
7
+ LOGGER = get_logger(__name__)
8
+
9
+ # Goal-terminating predicate name -> command template, filled from the predicate's bound
10
+ # noun kwargs. Only the placement/stack predicates that CARRY a goal's score need an entry;
11
+ # any other terminating predicate falls back to the whole-task instruction (logged once).
12
+ # Extend by adding one line when a new goal predicate is used.
13
+ _TEMPLATES: Dict[str, str] = {
14
+ "object_on_top": "put the {object} on the {reference_object}.",
15
+ "object_in_container": "put the {object} in the {container}.",
16
+ "object_inside": "put the {object} in the {container}.",
17
+ "object_on_bottom": "put the {object} in the {reference_object}.",
18
+ }
19
+
20
+
21
+ # Placement predicate -> (moved-object kwarg, destination kwarg, relation). These are the
22
+ # predicates that say WHERE something has to end up, which is what a privileged policy drives to.
23
+ _PLACEMENTS: Dict[str, Tuple[str, str, str]] = {
24
+ "object_on_top": ("object", "reference_object", "on"),
25
+ "object_in_container": ("object", "container", "in"),
26
+ "object_inside": ("object", "container", "in"),
27
+ "object_on_bottom": ("object", "reference_object", "in"),
28
+ }
29
+
30
+
31
+ @dataclasses.dataclass(frozen=True)
32
+ class OracleGoal:
33
+ """One score-carrying goal: its command string, the check that credits it, and its legs.
34
+
35
+ ``legs`` is the ordered chain the goal is scored through -- a relay's intermediate stops, then
36
+ the final placement. Each leg pairs its own predicate with the geometry it names, so a
37
+ privileged policy can drive the chain and a text planner can read the command, both off the
38
+ same enumeration.
39
+ """
40
+
41
+ command: str
42
+ check: Callable
43
+ legs: Sequence[Tuple[Callable, Optional[Tuple[str, str, str]]]]
44
+
45
+
46
+ def goal_geometry(predicate: Callable) -> Optional[Tuple[str, str, str]]:
47
+ """(moved object, destination, relation) for a placement predicate, else None.
48
+
49
+ Read off the predicate's own bound kwargs -- the same source ``_render`` draws its nouns from --
50
+ so the geometry a policy drives to and the condition the task scores agree by construction.
51
+ """
52
+ func = getattr(predicate, "func", predicate)
53
+ kwargs = getattr(predicate, "keywords", None) or {}
54
+ name = getattr(func, "__name__", "")
55
+ if name == "stacked":
56
+ objects = kwargs.get("objects") or []
57
+ return (objects[0], objects[1], "on") if len(objects) >= 2 else None
58
+ entry = _PLACEMENTS.get(name)
59
+ if entry is None:
60
+ return None
61
+ obj_key, dest_key, relation = entry
62
+ if isinstance(kwargs.get(obj_key), str) and isinstance(kwargs.get(dest_key), str):
63
+ return (kwargs[obj_key], kwargs[dest_key], relation)
64
+ return None
65
+
66
+
67
+ def _noun(asset_id: str, instruction: str) -> str:
68
+ """Asset id -> a readable noun, grounded in the task instruction's own words. The per-token
69
+ instance-index suffix is stripped first ("lime01" -> "lime", "orange_01" -> "orange") so that
70
+ duplicated objects ground to their base noun. Keep the id tokens that appear in the instruction
71
+ ("bin_a06" + "...into the bin" -> "bin"; "plate_large" + "...on the plate" -> "plate"); when the
72
+ instruction never names the object (an abstract task), fall back to the stripped id
73
+ ("spam_can" -> "spam can")."""
74
+ tokens = [re.sub(r"\d+$", "", token) for token in asset_id.lower().split("_")]
75
+ tokens = [token for token in tokens if token]
76
+ words = set(re.findall(r"[a-z]+", instruction.lower()))
77
+ grounded = [token for token in tokens if token in words]
78
+ if grounded:
79
+ return " ".join(grounded)
80
+ return " ".join(tokens) or asset_id
81
+
82
+
83
+ def _render(predicate: Callable, instruction: str) -> str:
84
+ """One command string for a goal-terminating predicate, from its name + bound nouns; each
85
+ noun is grounded in the task ``instruction`` (which is also the no-template fallback)."""
86
+ func = getattr(predicate, "func", predicate) # unwrap functools.partial
87
+ kwargs = getattr(predicate, "keywords", None) or {}
88
+ name = getattr(func, "__name__", "")
89
+ if name == "stacked":
90
+ objects = [_noun(obj, instruction) for obj in kwargs.get("objects", [])]
91
+ return "stack the " + " on the ".join(objects) + "." if objects else instruction
92
+ template = _TEMPLATES.get(name)
93
+ if template is None:
94
+ LOGGER.warn(f"robolab oracle: no command template for predicate {name!r}; using task instruction")
95
+ return instruction
96
+ nouns = {key: _noun(value, instruction) for key, value in kwargs.items() if isinstance(value, str)}
97
+ try:
98
+ return template.format(**nouns)
99
+ except KeyError:
100
+ LOGGER.warn(f"robolab oracle: template for {name!r} missing a noun; using task instruction")
101
+ return instruction
102
+
103
+
104
+ def build_oracle(subtasks, task_instruction: str) -> List[OracleGoal]:
105
+ """Synthesize the privileged oracle plan from the env's OWN subtask spec: one goal per
106
+ score-carrying condition, in goal order. The command is rendered from the goal's terminating
107
+ predicate (verb + bound object/target nouns) and the check IS that predicate, so a plan and the
108
+ credit it is scored against stay aligned by construction. This is the RoboLab-side analogue of
109
+ SimplerEnv's ``oracle_subtasks`` / ``oracle_goal_keys`` (derived from the env's goals, not a
110
+ hand-authored plan); the server just forwards the result.
111
+
112
+ The goal enumeration mirrors what RoboLab scores against: a ``logical="all"`` multi-object group
113
+ yields one goal per object (its final, score-carrying condition); ``"any"`` collapses to one
114
+ group-level goal; ``"choose"`` yields K goals (goal i-1 = "at least i of the group placed").
115
+ Returns ``[]`` when the task declares no subtask spec, so the caller publishes the single
116
+ whole-task goal instead."""
117
+ goals: List[OracleGoal] = []
118
+ for subtask in subtasks or []:
119
+ chains = list(subtask.conditions.values())
120
+ finals = [conditions[-1][0] for conditions in chains]
121
+ if subtask.logical == "all" and len(finals) > 1:
122
+ for chain in chains:
123
+ goals.append(_goal(chain[-1][0], task_instruction, chain))
124
+ elif subtask.logical == "any":
125
+ check = lambda env, env_id=None, fs=finals: any(f(env, env_id=env_id) for f in fs) # noqa: E731
126
+ goals.append(_goal(finals[0], task_instruction, chains[0], check=check))
127
+ elif subtask.logical == "choose":
128
+ for need in range(1, (subtask.K or 1) + 1):
129
+ index = min(need - 1, len(finals) - 1)
130
+ check = lambda env, env_id=None, fs=finals, need=need: ( # noqa: E731
131
+ sum(bool(f(env, env_id=env_id)) for f in fs) >= need
132
+ )
133
+ goals.append(_goal(finals[index], task_instruction, chains[index], check=check))
134
+ else:
135
+ goals.append(_goal(finals[0], task_instruction, chains[0]))
136
+ return goals
137
+
138
+
139
+ def _goal(predicate: Callable, instruction: str, chain, check: Optional[Callable] = None) -> OracleGoal:
140
+ """One goal from its terminating predicate and the ordered condition chain reaching it."""
141
+ return OracleGoal(
142
+ command=_render(predicate, instruction),
143
+ check=check if check is not None else predicate,
144
+ legs=[(leg[0], goal_geometry(leg[0])) for leg in chain],
145
+ )
ladder/components/inference/robots/robolab/privileged.py ADDED
@@ -0,0 +1,151 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from typing import Any, Dict, List, Sequence, Tuple
2
+
3
+ import numpy as np
4
+ import torch
5
+ from robolab.core.world.world_state import get_world
6
+
7
+ from ladder.components.inference.api.core.privileged_geometry import build_payloads, to_base
8
+ from ladder.components.inference.robots.robolab.oracle import OracleGoal
9
+
10
+ _ROBOT = "robot"
11
+ _BASE_LINK = "panda_link0"
12
+ _GRIPPER = "gripper"
13
+ _IGNORED = {"table"} # scenery registered as a rigid object, as upstream's EventTracker skips it
14
+
15
+ Leg = Tuple[str, str, str]
16
+
17
+
18
+ _LONG_ASPECT = 1.2 # a footprint this much longer than wide has a long axis to grip across
19
+
20
+
21
+ def _numpy(value) -> np.ndarray:
22
+ return value.detach().cpu().numpy() if isinstance(value, torch.Tensor) else np.asarray(value)
23
+
24
+
25
+ def _quat_to_matrix(quat: np.ndarray) -> np.ndarray:
26
+ """Rotation from an (x, y, z, w) quaternion -- the order this articulation state reports.
27
+
28
+ Verified against the sim: the arm's base sits square on the env origin, reporting [0, 0, 0, 1],
29
+ and the end effector resolves to the same x and y through forward kinematics as it does in
30
+ env-local coordinates. Reading that quaternion as (w, x, y, z) instead invents a 180 degree yaw,
31
+ which puts the whole scene behind the robot and sends the policy driving out of the workspace.
32
+ """
33
+ x, y, z, w = (float(v) for v in quat)
34
+ return np.array(
35
+ [
36
+ [1 - 2 * (y * y + z * z), 2 * (x * y - w * z), 2 * (x * z + w * y)],
37
+ [2 * (x * y + w * z), 1 - 2 * (x * x + z * z), 2 * (y * z - w * x)],
38
+ [2 * (x * z - w * y), 2 * (y * z + w * x), 1 - 2 * (x * x + y * y)],
39
+ ]
40
+ )
41
+
42
+
43
+ def _base_transforms(world, n_envs: int) -> np.ndarray:
44
+ """Env-local -> robot base, one 4x4 per env.
45
+
46
+ Object geometry comes out of WorldState relative to each env's scene origin, while the policy
47
+ reads an eef pose forward kinematics produced in the arm's own base frame. Publishing the two in
48
+ different frames fails silently: every number looks plausible and every reach misses by the mount
49
+ offset.
50
+ """
51
+ poses = _numpy(world.get_articulation_link_pose(_ROBOT, _BASE_LINK))
52
+ origins = _numpy(world.env.scene.env_origins)
53
+
54
+ transforms = np.zeros((n_envs, 4, 4))
55
+ for env_id in range(n_envs):
56
+ base_to_env = np.eye(4)
57
+ base_to_env[:3, :3] = _quat_to_matrix(poses[env_id, 3:7])
58
+ base_to_env[:3, 3] = poses[env_id, :3] - origins[env_id]
59
+ transforms[env_id] = np.linalg.inv(base_to_env)
60
+ return transforms
61
+
62
+
63
+ def _corners(world, name: str) -> np.ndarray:
64
+ """Per-env corners of one body's oriented bounding box, ``[n_envs, 8, 3]`` in env-local coordinates."""
65
+ corners, _ = world.get_bbox(name)
66
+ return _numpy(corners)
67
+
68
+
69
+ def _long_axis_yaw(corners: np.ndarray) -> float:
70
+ """Yaw of an oriented box's longer horizontal side, or NaN when its footprint is round.
71
+
72
+ The axis-aligned extents cannot tell which way a lemon at 45 degrees lies, and a grip closed on
73
+ its tapered ends squeezes it out of the jaws.
74
+ """
75
+ xy = corners[:, :2] - corners[:, :2].mean(axis=0)
76
+ _, spread, axes = np.linalg.svd(xy, full_matrices=False)
77
+ if spread[0] < _LONG_ASPECT * spread[1]:
78
+ return float("nan")
79
+ return float(np.arctan2(axes[0][1], axes[0][0]))
80
+
81
+
82
+ def privileged_state(
83
+ env, goals: Sequence[OracleGoal], achieved: Sequence[Sequence[bool]]
84
+ ) -> List[Dict[str, Any]]:
85
+ """Ground-truth geometry for the scripted completability policy, one payload per env.
86
+
87
+ Driven by the goals the task is SCORED on, so it covers every RoboLab task rather than the
88
+ composition suite alone, and emitted in the schema RobotArena and SimplerEnv emit, so one
89
+ ScriptedPolicy drives all three. A goal whose predicate names no placement is skipped: there is
90
+ no destination to drive to.
91
+ """
92
+ world = get_world(env)
93
+ n_envs = int(env.num_envs)
94
+
95
+ # A subtask's condition chain is the STAGES of one placement (the upstream builder emits
96
+ # object_grabbed before the placement predicate), not a sequence of destinations. A relay's legs
97
+ # arrive as separate goals already, each latched by the factory, so the geometry to drive to is
98
+ # the last condition that actually names a placement.
99
+ active = [
100
+ next((geom for _, geom in reversed(list(goal.legs)) if geom is not None), None) for goal in goals
101
+ ]
102
+
103
+ # Every movable body, so a grasped or knocked distractor shows in the trace.
104
+ named = {name for goal in goals for _, leg in goal.legs if leg for name in leg[:2]}
105
+ names = sorted(named | {name for name in world.objects if name not in _IGNORED})
106
+ if not names:
107
+ return [{"conditions": [], "objects": []} for _ in range(n_envs)]
108
+ index_of = {name: i for i, name in enumerate(names)}
109
+
110
+ transforms = _base_transforms(world, n_envs)
111
+ mins, maxs = (np.zeros((len(names), n_envs, 3)) for _ in range(2))
112
+ yaws = np.full((len(names), n_envs), np.nan)
113
+ for i, name in enumerate(names):
114
+ corners = _corners(world, name)
115
+ for env_id in range(n_envs):
116
+ # All eight corners go through the change of frame, so the extremes are those of the
117
+ # base-frame box rather than of two env-local corners that a rotation can swap.
118
+ base = to_base(transforms[env_id], corners[env_id])
119
+ mins[i, env_id], maxs[i, env_id] = base.min(axis=0), base.max(axis=0)
120
+ yaws[i, env_id] = _long_axis_yaw(base)
121
+ centers = 0.5 * (mins + maxs)
122
+
123
+ grasped = np.zeros((len(names), n_envs), dtype=bool)
124
+ for i, name in enumerate(names):
125
+ grasped[i] = _numpy(world.in_contact(name, _GRIPPER))
126
+
127
+ payload_goals: List[Dict[str, Any]] = []
128
+ for goal_index, leg in enumerate(active):
129
+ if leg is None:
130
+ continue
131
+ source, destination, relation = leg
132
+ payload_goals.append(
133
+ {
134
+ "source": index_of[source],
135
+ "destination": index_of[destination],
136
+ "relation": relation,
137
+ "satisfied": [bool(achieved[env_id][goal_index]) for env_id in range(n_envs)],
138
+ }
139
+ )
140
+
141
+ payloads = build_payloads(
142
+ names=names,
143
+ centers=centers,
144
+ mins=mins,
145
+ maxs=maxs,
146
+ grasped=grasped,
147
+ goals=payload_goals,
148
+ n_envs=n_envs,
149
+ long_axis_yaws=yaws,
150
+ )
151
+ return payloads
ladder/components/urdf/robots/panda/robot.urdf ADDED
@@ -0,0 +1,440 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ <?xml version="1.0" ?>
2
+ <!-- =================================================================================== -->
3
+ <!-- | This document was autogenerated by xacro from franka_description/robots/panda/panda.urdf.xacro | -->
4
+ <!-- | EDITING THIS FILE BY HAND IS NOT RECOMMENDED | -->
5
+ <!-- =================================================================================== -->
6
+ <robot name="panda">
7
+ <!-- hand="$(arg hand)"
8
+ tcp_xyz="$(arg tcp_xyz)"
9
+ tcp_rpy="$(arg tcp_rpy)"
10
+ gazebo="$(arg gazebo)"
11
+ parent="$(arg parent)"
12
+ xyz="$(arg xyz)"
13
+ rpy="$(arg rpy)" -->
14
+ <!-- sub-link defining detailed meshes for collision with environment -->
15
+ <link name="panda_link0">
16
+ <visual>
17
+ <geometry>
18
+ <mesh filename="meshes/visual/link0.dae"/>
19
+ </geometry>
20
+ </visual>
21
+ <collision>
22
+ <geometry>
23
+ <mesh filename="meshes/collision/link0.stl"/>
24
+ </geometry>
25
+ </collision>
26
+ </link>
27
+ <!-- sub-link defining coarse geometries of real robot's internal self-collision -->
28
+ <link name="panda_link0_sc">
29
+ <collision>
30
+ <origin rpy="0 1.5707963267948966 0" xyz="-0.075 0 0.06"/>
31
+ <geometry>
32
+ <cylinder length="0.03" radius="0.09"/>
33
+ </geometry>
34
+ </collision>
35
+ <collision>
36
+ <origin xyz="-0.06 0 0.06"/>
37
+ <geometry>
38
+ <sphere radius="0.09"/>
39
+ </geometry>
40
+ </collision>
41
+ <collision>
42
+ <origin xyz="-0.09 0 0.06"/>
43
+ <geometry>
44
+ <sphere radius="0.09"/>
45
+ </geometry>
46
+ </collision>
47
+ </link>
48
+ <!-- fixed joint between both sub-links -->
49
+ <joint name="panda_link0_sc_joint" type="fixed">
50
+ <origin rpy="0 0 0"/>
51
+ <parent link="panda_link0"/>
52
+ <child link="panda_link0_sc"/>
53
+ </joint>
54
+ <!-- sub-link defining detailed meshes for collision with environment -->
55
+ <link name="panda_link1">
56
+ <visual>
57
+ <geometry>
58
+ <mesh filename="meshes/visual/link1.dae"/>
59
+ </geometry>
60
+ </visual>
61
+ <collision>
62
+ <geometry>
63
+ <mesh filename="meshes/collision/link1.stl"/>
64
+ </geometry>
65
+ </collision>
66
+ </link>
67
+ <!-- sub-link defining coarse geometries of real robot's internal self-collision -->
68
+ <link name="panda_link1_sc">
69
+ <collision>
70
+ <origin rpy="0 0 0" xyz="0 0 -0.1915"/>
71
+ <geometry>
72
+ <cylinder length="0.283" radius="0.09"/>
73
+ </geometry>
74
+ </collision>
75
+ <collision>
76
+ <origin xyz="0 0 -0.05000000000000002"/>
77
+ <geometry>
78
+ <sphere radius="0.09"/>
79
+ </geometry>
80
+ </collision>
81
+ <collision>
82
+ <origin xyz="0 0 -0.33299999999999996"/>
83
+ <geometry>
84
+ <sphere radius="0.09"/>
85
+ </geometry>
86
+ </collision>
87
+ </link>
88
+ <!-- fixed joint between both sub-links -->
89
+ <joint name="panda_link1_sc_joint" type="fixed">
90
+ <origin rpy="0 0 0"/>
91
+ <parent link="panda_link1"/>
92
+ <child link="panda_link1_sc"/>
93
+ </joint>
94
+ <joint name="panda_joint1" type="revolute">
95
+ <origin rpy="0 0 0" xyz="0 0 0.333"/>
96
+ <parent link="panda_link0"/>
97
+ <child link="panda_link1"/>
98
+ <axis xyz="0 0 1"/>
99
+ <limit effort="87.0" lower="-2.8973" upper="2.8973" velocity="2.175"/>
100
+ <safety_controller k_position="100.0" k_velocity="40.0" soft_lower_limit="-2.8973" soft_upper_limit="2.8973"/>
101
+ <dynamics D="1" K="7000" damping="0.003" friction="0.0" mu_coulomb="0" mu_viscous="16"/>
102
+ </joint>
103
+ <!-- sub-link defining detailed meshes for collision with environment -->
104
+ <link name="panda_link2">
105
+ <visual>
106
+ <geometry>
107
+ <mesh filename="meshes/visual/link2.dae"/>
108
+ </geometry>
109
+ </visual>
110
+ <collision>
111
+ <geometry>
112
+ <mesh filename="meshes/collision/link2.stl"/>
113
+ </geometry>
114
+ </collision>
115
+ </link>
116
+ <!-- sub-link defining coarse geometries of real robot's internal self-collision -->
117
+ <link name="panda_link2_sc">
118
+ <collision>
119
+ <origin rpy="0 0 0" xyz="0 0 0"/>
120
+ <geometry>
121
+ <cylinder length="0.12" radius="0.09"/>
122
+ </geometry>
123
+ </collision>
124
+ <collision>
125
+ <origin xyz="0 0 0.06"/>
126
+ <geometry>
127
+ <sphere radius="0.09"/>
128
+ </geometry>
129
+ </collision>
130
+ <collision>
131
+ <origin xyz="0 0 -0.06"/>
132
+ <geometry>
133
+ <sphere radius="0.09"/>
134
+ </geometry>
135
+ </collision>
136
+ </link>
137
+ <!-- fixed joint between both sub-links -->
138
+ <joint name="panda_link2_sc_joint" type="fixed">
139
+ <origin rpy="0 0 0"/>
140
+ <parent link="panda_link2"/>
141
+ <child link="panda_link2_sc"/>
142
+ </joint>
143
+ <joint name="panda_joint2" type="revolute">
144
+ <origin rpy="-1.5707963267948966 0 0" xyz="0 0 0"/>
145
+ <parent link="panda_link1"/>
146
+ <child link="panda_link2"/>
147
+ <axis xyz="0 0 1"/>
148
+ <limit effort="87.0" lower="-1.7628" upper="1.7628" velocity="2.175"/>
149
+ <safety_controller k_position="100.0" k_velocity="40.0" soft_lower_limit="-1.7628" soft_upper_limit="1.7628"/>
150
+ <dynamics D="1" K="7000" damping="0.003" friction="0.0" mu_coulomb="0" mu_viscous="16"/>
151
+ </joint>
152
+ <!-- sub-link defining detailed meshes for collision with environment -->
153
+ <link name="panda_link3">
154
+ <visual>
155
+ <geometry>
156
+ <mesh filename="meshes/visual/link3.dae"/>
157
+ </geometry>
158
+ </visual>
159
+ <collision>
160
+ <geometry>
161
+ <mesh filename="meshes/collision/link3.stl"/>
162
+ </geometry>
163
+ </collision>
164
+ </link>
165
+ <!-- sub-link defining coarse geometries of real robot's internal self-collision -->
166
+ <link name="panda_link3_sc">
167
+ <collision>
168
+ <origin rpy="0 0 0" xyz="0 0 -0.145"/>
169
+ <geometry>
170
+ <cylinder length="0.15" radius="0.09"/>
171
+ </geometry>
172
+ </collision>
173
+ <collision>
174
+ <origin xyz="0 0 -0.06999999999999999"/>
175
+ <geometry>
176
+ <sphere radius="0.09"/>
177
+ </geometry>
178
+ </collision>
179
+ <collision>
180
+ <origin xyz="0 0 -0.21999999999999997"/>
181
+ <geometry>
182
+ <sphere radius="0.09"/>
183
+ </geometry>
184
+ </collision>
185
+ </link>
186
+ <!-- fixed joint between both sub-links -->
187
+ <joint name="panda_link3_sc_joint" type="fixed">
188
+ <origin rpy="0 0 0"/>
189
+ <parent link="panda_link3"/>
190
+ <child link="panda_link3_sc"/>
191
+ </joint>
192
+ <joint name="panda_joint3" type="revolute">
193
+ <origin rpy="1.5707963267948966 0 0" xyz="0 -0.316 0"/>
194
+ <parent link="panda_link2"/>
195
+ <child link="panda_link3"/>
196
+ <axis xyz="0 0 1"/>
197
+ <limit effort="87.0" lower="-2.8973" upper="2.8973" velocity="2.175"/>
198
+ <safety_controller k_position="100.0" k_velocity="40.0" soft_lower_limit="-2.8973" soft_upper_limit="2.8973"/>
199
+ <dynamics D="1" K="7000" damping="0.003" friction="0.0" mu_coulomb="0" mu_viscous="16"/>
200
+ </joint>
201
+ <!-- sub-link defining detailed meshes for collision with environment -->
202
+ <link name="panda_link4">
203
+ <visual>
204
+ <geometry>
205
+ <mesh filename="meshes/visual/link4.dae"/>
206
+ </geometry>
207
+ </visual>
208
+ <collision>
209
+ <geometry>
210
+ <mesh filename="meshes/collision/link4.stl"/>
211
+ </geometry>
212
+ </collision>
213
+ </link>
214
+ <!-- sub-link defining coarse geometries of real robot's internal self-collision -->
215
+ <link name="panda_link4_sc">
216
+ <collision>
217
+ <origin rpy="0 0 0" xyz="0 0 0"/>
218
+ <geometry>
219
+ <cylinder length="0.12" radius="0.09"/>
220
+ </geometry>
221
+ </collision>
222
+ <collision>
223
+ <origin xyz="0 0 0.06"/>
224
+ <geometry>
225
+ <sphere radius="0.09"/>
226
+ </geometry>
227
+ </collision>
228
+ <collision>
229
+ <origin xyz="0 0 -0.06"/>
230
+ <geometry>
231
+ <sphere radius="0.09"/>
232
+ </geometry>
233
+ </collision>
234
+ </link>
235
+ <!-- fixed joint between both sub-links -->
236
+ <joint name="panda_link4_sc_joint" type="fixed">
237
+ <origin rpy="0 0 0"/>
238
+ <parent link="panda_link4"/>
239
+ <child link="panda_link4_sc"/>
240
+ </joint>
241
+ <joint name="panda_joint4" type="revolute">
242
+ <origin rpy="1.5707963267948966 0 0" xyz="0.0825 0 0"/>
243
+ <parent link="panda_link3"/>
244
+ <child link="panda_link4"/>
245
+ <axis xyz="0 0 1"/>
246
+ <limit effort="87.0" lower="-3.0718" upper="-0.0698" velocity="2.175"/>
247
+ <safety_controller k_position="100.0" k_velocity="40.0" soft_lower_limit="-3.0718" soft_upper_limit="-0.0698"/>
248
+ <dynamics D="1" K="7000" damping="0.003" friction="0.0" mu_coulomb="0" mu_viscous="16"/>
249
+ </joint>
250
+ <!-- sub-link defining detailed meshes for collision with environment -->
251
+ <link name="panda_link5">
252
+ <visual>
253
+ <geometry>
254
+ <mesh filename="meshes/visual/link5.dae"/>
255
+ </geometry>
256
+ </visual>
257
+ <collision>
258
+ <geometry>
259
+ <mesh filename="meshes/collision/link5.stl"/>
260
+ </geometry>
261
+ </collision>
262
+ </link>
263
+ <!-- sub-link defining coarse geometries of real robot's internal self-collision -->
264
+ <link name="panda_link5_sc">
265
+ <collision>
266
+ <origin rpy="0 0 0" xyz="0 0 -0.26"/>
267
+ <geometry>
268
+ <cylinder length="0.1" radius="0.09"/>
269
+ </geometry>
270
+ </collision>
271
+ <collision>
272
+ <origin xyz="0 0 -0.21000000000000002"/>
273
+ <geometry>
274
+ <sphere radius="0.09"/>
275
+ </geometry>
276
+ </collision>
277
+ <collision>
278
+ <origin xyz="0 0 -0.31"/>
279
+ <geometry>
280
+ <sphere radius="0.09"/>
281
+ </geometry>
282
+ </collision>
283
+ <collision>
284
+ <origin rpy="0 0 0.08" xyz="0 0.08 -0.13"/>
285
+ <geometry>
286
+ <cylinder length="0.14" radius="0.055"/>
287
+ </geometry>
288
+ </collision>
289
+ <collision>
290
+ <origin xyz="0 0.08 -0.06"/>
291
+ <geometry>
292
+ <sphere radius="0.055"/>
293
+ </geometry>
294
+ </collision>
295
+ <collision>
296
+ <origin xyz="0 0.08 -0.2"/>
297
+ <geometry>
298
+ <sphere radius="0.055"/>
299
+ </geometry>
300
+ </collision>
301
+ </link>
302
+ <!-- fixed joint between both sub-links -->
303
+ <joint name="panda_link5_sc_joint" type="fixed">
304
+ <origin rpy="0 0 0"/>
305
+ <parent link="panda_link5"/>
306
+ <child link="panda_link5_sc"/>
307
+ </joint>
308
+ <joint name="panda_joint5" type="revolute">
309
+ <origin rpy="-1.5707963267948966 0 0" xyz="-0.0825 0.384 0"/>
310
+ <parent link="panda_link4"/>
311
+ <child link="panda_link5"/>
312
+ <axis xyz="0 0 1"/>
313
+ <limit effort="12.0" lower="-2.8973" upper="2.8973" velocity="2.61"/>
314
+ <safety_controller k_position="100.0" k_velocity="40.0" soft_lower_limit="-2.8973" soft_upper_limit="2.8973"/>
315
+ <dynamics D="1" K="7000" damping="0.003" friction="0.0" mu_coulomb="0" mu_viscous="16"/>
316
+ </joint>
317
+ <!-- sub-link defining detailed meshes for collision with environment -->
318
+ <link name="panda_link6">
319
+ <visual>
320
+ <geometry>
321
+ <mesh filename="meshes/visual/link6.dae"/>
322
+ </geometry>
323
+ </visual>
324
+ <collision>
325
+ <geometry>
326
+ <mesh filename="meshes/collision/link6.stl"/>
327
+ </geometry>
328
+ </collision>
329
+ </link>
330
+ <!-- sub-link defining coarse geometries of real robot's internal self-collision -->
331
+ <link name="panda_link6_sc">
332
+ <collision>
333
+ <origin rpy="0 0 0" xyz="0 0 -0.03"/>
334
+ <geometry>
335
+ <cylinder length="0.08" radius="0.08"/>
336
+ </geometry>
337
+ </collision>
338
+ <collision>
339
+ <origin xyz="0 0 0.010000000000000002"/>
340
+ <geometry>
341
+ <sphere radius="0.08"/>
342
+ </geometry>
343
+ </collision>
344
+ <collision>
345
+ <origin xyz="0 0 -0.07"/>
346
+ <geometry>
347
+ <sphere radius="0.08"/>
348
+ </geometry>
349
+ </collision>
350
+ </link>
351
+ <!-- fixed joint between both sub-links -->
352
+ <joint name="panda_link6_sc_joint" type="fixed">
353
+ <origin rpy="0 0 0"/>
354
+ <parent link="panda_link6"/>
355
+ <child link="panda_link6_sc"/>
356
+ </joint>
357
+ <joint name="panda_joint6" type="revolute">
358
+ <origin rpy="1.5707963267948966 0 0" xyz="0 0 0"/>
359
+ <parent link="panda_link5"/>
360
+ <child link="panda_link6"/>
361
+ <axis xyz="0 0 1"/>
362
+ <limit effort="12.0" lower="-0.0175" upper="3.7525" velocity="2.61"/>
363
+ <safety_controller k_position="100.0" k_velocity="40.0" soft_lower_limit="-0.0175" soft_upper_limit="3.7525"/>
364
+ <dynamics D="1" K="7000" damping="0.003" friction="0.0" mu_coulomb="0" mu_viscous="16"/>
365
+ </joint>
366
+ <!-- sub-link defining detailed meshes for collision with environment -->
367
+ <link name="panda_link7">
368
+ <visual>
369
+ <geometry>
370
+ <mesh filename="meshes/visual/link7.dae"/>
371
+ </geometry>
372
+ </visual>
373
+ <collision>
374
+ <geometry>
375
+ <mesh filename="meshes/collision/link7.stl"/>
376
+ </geometry>
377
+ </collision>
378
+ </link>
379
+ <!-- sub-link defining coarse geometries of real robot's internal self-collision -->
380
+ <link name="panda_link7_sc">
381
+ <collision>
382
+ <origin rpy="0 0 0" xyz="0 0 0.01"/>
383
+ <geometry>
384
+ <cylinder length="0.14" radius="0.07"/>
385
+ </geometry>
386
+ </collision>
387
+ <collision>
388
+ <origin xyz="0 0 0.08"/>
389
+ <geometry>
390
+ <sphere radius="0.07"/>
391
+ </geometry>
392
+ </collision>
393
+ <collision>
394
+ <origin xyz="0 0 -0.060000000000000005"/>
395
+ <geometry>
396
+ <sphere radius="0.07"/>
397
+ </geometry>
398
+ </collision>
399
+ <collision>
400
+ <origin rpy="0 1.5707963267948966 0" xyz="0.06 0 0.082"/>
401
+ <geometry>
402
+ <cylinder length="0.01" radius="0.06"/>
403
+ </geometry>
404
+ </collision>
405
+ <collision>
406
+ <origin xyz="0.065 0 0.082"/>
407
+ <geometry>
408
+ <sphere radius="0.06"/>
409
+ </geometry>
410
+ </collision>
411
+ <collision>
412
+ <origin xyz="0.055 0 0.082"/>
413
+ <geometry>
414
+ <sphere radius="0.06"/>
415
+ </geometry>
416
+ </collision>
417
+ </link>
418
+ <!-- fixed joint between both sub-links -->
419
+ <joint name="panda_link7_sc_joint" type="fixed">
420
+ <origin rpy="0 0 0.7853981633974483"/>
421
+ <parent link="panda_link7"/>
422
+ <child link="panda_link7_sc"/>
423
+ </joint>
424
+ <joint name="panda_joint7" type="revolute">
425
+ <origin rpy="1.5707963267948966 0 0" xyz="0.088 0 0"/>
426
+ <parent link="panda_link6"/>
427
+ <child link="panda_link7"/>
428
+ <axis xyz="0 0 1"/>
429
+ <limit effort="12.0" lower="-2.8973" upper="2.8973" velocity="2.61"/>
430
+ <safety_controller k_position="100.0" k_velocity="40.0" soft_lower_limit="-2.8973" soft_upper_limit="2.8973"/>
431
+ <dynamics D="1" K="7000" damping="0.003" friction="0.0" mu_coulomb="0" mu_viscous="16"/>
432
+ </joint>
433
+ <link name="panda_link8"/>
434
+ <joint name="panda_joint8" type="fixed">
435
+ <origin rpy="0 0 0" xyz="0 0 0.107"/>
436
+ <parent link="panda_link7"/>
437
+ <child link="panda_link8"/>
438
+ </joint>
439
+ </robot>
440
+
ladder/core/common/logger/__init__.py ADDED
@@ -0,0 +1,13 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from .colorize import colorize
2
+ from .logger import LadderLogger, enter_ipdb_breakpoint_on_signal, get_logger, get_root_logger, is_interactive
3
+ from .stdout import no_stdout_within_functions
4
+
5
+ __all__ = [
6
+ 'get_logger',
7
+ 'get_root_logger',
8
+ 'enter_ipdb_breakpoint_on_signal',
9
+ 'is_interactive',
10
+ 'LadderLogger',
11
+ 'no_stdout_within_functions',
12
+ 'colorize',
13
+ ]
ladder/core/common/logger/colorize.py ADDED
@@ -0,0 +1,27 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ COLORS = {
2
+ 'gray': 37,
3
+ 'red': 31,
4
+ 'green': 32,
5
+ 'yellow': 93,
6
+ 'blue': 94,
7
+ 'magenta': 35,
8
+ 'cyan': 36,
9
+ 'white': 97,
10
+ }
11
+
12
+
13
+ def colorize(string: str, color: str, bold: bool = False, highlight: bool = False) -> str:
14
+ """
15
+ Modify string so it appears in color on the console
16
+ """
17
+ attr = []
18
+ code = COLORS[color]
19
+
20
+ if highlight:
21
+ code += 10
22
+ attr.append(str(code))
23
+
24
+ if bold:
25
+ attr.append('1')
26
+
27
+ return '\x1b[%sm%s\x1b[0m' % (';'.join(attr), string)
ladder/core/common/logger/logger.py ADDED
@@ -0,0 +1,223 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import inspect
2
+ import logging
3
+ import os
4
+ import signal
5
+ import sys
6
+ import threading
7
+ from typing import Any, Dict, Set, Union
8
+
9
+ from .colorize import colorize
10
+
11
+ DEBUG_PATTERNS = [patt for patt in os.environ.get('DEBUG', '').split(',') if patt]
12
+
13
+ # Default overrides for modules with spammy logs. Patterns should be comma-separated
14
+ DEFAULT_LOG_MODULE_OVERRIDES = 'filelock=ERROR'
15
+
16
+
17
+ def _parse_log_overrides(log_override_pattern: str) -> Dict[str, str]:
18
+ """
19
+ Parses log override settings:
20
+ Args:
21
+ log_override_pattern: str with comma-separated values. Each value should be of the format
22
+ `path.to.module=LOG_LEVEL`, e.g. `ladder.core.common.logger.logger=INFO`
23
+ Returns:
24
+ Dict of module names and corresponding log level
25
+ """
26
+ overrides = {}
27
+ for setting in log_override_pattern.split(','):
28
+ parts = setting.strip().split('=')
29
+ if len(parts) < 2:
30
+ continue
31
+ overrides[parts[0]] = parts[1]
32
+ return overrides
33
+
34
+
35
+ LOG_MODULE_OVERRIDES = _parse_log_overrides(
36
+ ','.join([DEFAULT_LOG_MODULE_OVERRIDES, os.environ.get('LOG_MODULE_OVERRIDES', '')])
37
+ )
38
+
39
+ ROOT_LOGGER_LEVEL: str = os.environ.get('ROOT_LOGGER_LEVEL', 'INFO')
40
+
41
+ _root_logger_set = False
42
+ _root_logger_lock = threading.Lock()
43
+
44
+ # Loggers whose records must not reach the console. Enforced by a single filter on the console handler
45
+ # created in `get_root_logger`, so a logger can be excluded at any point without any caller having to
46
+ # find handlers itself - and without risk of catching a FileHandler, which subclasses StreamHandler.
47
+ _CONSOLE_EXCLUDED_LOGGERS: Set[str] = set()
48
+
49
+
50
+ def _disable_console_logging(logger_name: str) -> None:
51
+ """
52
+ Stop `logger_name`'s records reaching the console. Every other handler still receives them.
53
+
54
+ For processes that share one terminal but log to separate files - e.g. every rank of a distributed
55
+ job streaming to the same stdout - where the duplicate copies add nothing because each process
56
+ already writes its own log file.
57
+ """
58
+ _CONSOLE_EXCLUDED_LOGGERS.add(logger_name)
59
+
60
+
61
+ class LadderLogger:
62
+ def __init__(self, logger: logging.Logger) -> None:
63
+ self._logger = logger
64
+ self._once_call_sites: Set[tuple] = set()
65
+
66
+ @property
67
+ def name(self):
68
+ return self._logger.name
69
+
70
+ def is_enabled_for_level(self, level: int):
71
+ return self._logger.isEnabledFor(level)
72
+
73
+ def add_handler(self, handler: logging.Handler) -> None:
74
+ self._logger.addHandler(handler)
75
+
76
+ def debug(self, event_type: str, **info) -> None:
77
+ self._log(logging.DEBUG, event_type, info)
78
+
79
+ def info(self, event_type: str, color: str | None = None, **info) -> None:
80
+ self._log(logging.INFO, event_type, info, color=color)
81
+
82
+ def info_once(self, event_type: str, **info) -> None:
83
+ """Like info, but will only print for the first time and drop the log statement afterwards."""
84
+
85
+ assert type(self) is LadderLogger, "info_once will not work when subclassing the logger"
86
+ # It will also not work when delegating the logger etc.
87
+
88
+ call_site = inspect.stack()[1]
89
+ if (call_site.filename, call_site.lineno) not in self._once_call_sites:
90
+ self._once_call_sites.add((call_site.filename, call_site.lineno))
91
+ self._log(logging.INFO, event_type, info)
92
+
93
+ def warn(self, event_type: str, **info) -> None:
94
+ self._log(logging.WARN, event_type, info, color='yellow')
95
+
96
+ def error(self, event_type: str, **info) -> None:
97
+ self._log(logging.ERROR, event_type, info, color='red')
98
+
99
+ def critical(self, event_type: str, **info) -> None:
100
+ self._log(logging.CRITICAL, event_type, info, color='red')
101
+
102
+ def exception(self, event_type: str, _: Exception, **info) -> None:
103
+ self._log(logging.ERROR, event_type, info, log=self._log_exception)
104
+
105
+ def log(self, level: int, event_type: str, **info) -> None:
106
+ self._log(level, event_type, info)
107
+
108
+ def _log(
109
+ self, level: int, event_type: str, info: Dict[str, Any], log=None, color: str | None = None
110
+ ) -> None:
111
+ if log is None:
112
+ log = self._logger.log
113
+
114
+ if not self._logger.isEnabledFor(level):
115
+ return
116
+
117
+ extra = {'event_type': event_type}
118
+
119
+ if info:
120
+ extra.update(info)
121
+ if 'message' in extra:
122
+ extra.pop('message') # message is set by logger.
123
+ message = '%s %s' % (event_type, ", ".join(f"{k}={v}" for k, v in info.items()))
124
+ else:
125
+ message = event_type
126
+
127
+ if color:
128
+ message = colorize(message, color)
129
+
130
+ log(level, message, extra=extra)
131
+
132
+ def _log_exception(self, _, msg, *args, **kwargs) -> None:
133
+ self._logger.exception(msg, *args, **kwargs)
134
+
135
+ def close(self) -> None:
136
+ self._logger.handlers.clear()
137
+
138
+ def set_level(self, level: Union[int, str]) -> None:
139
+ self._logger.setLevel(level)
140
+
141
+ def disable_console(self) -> None:
142
+ """
143
+ Stop this logger's records reaching the console; every other handler still receives them.
144
+
145
+ Use when the decision depends on runtime state that isn't known at import time - e.g. the
146
+ distributed rank. Otherwise prefer `get_logger(..., console=False)`.
147
+ """
148
+ _disable_console_logging(self.name)
149
+
150
+
151
+ def is_interactive() -> bool:
152
+ """Determines whether the python application has been invoked from an interactive shell or not"""
153
+ return sys.stdin.isatty()
154
+
155
+
156
+ def get_root_logger() -> logging.Logger:
157
+ global _root_logger_set # noqa: PLW0603 (global-statement)
158
+ with _root_logger_lock:
159
+ root_logger = logging.getLogger()
160
+ if not _root_logger_set:
161
+ root_logger.handlers.clear() # There could be some default handlers we don't care about. Remove them.
162
+ root_logger.setLevel(ROOT_LOGGER_LEVEL)
163
+ stream_handler = logging.StreamHandler()
164
+ stream_handler.setLevel(ROOT_LOGGER_LEVEL)
165
+
166
+ formatter = logging.Formatter(
167
+ '%(levelname)-8s %(asctime)-15s \033[1;96m%(name)-12s\033[0m %(message)s'
168
+ )
169
+
170
+ stream_handler.setFormatter(formatter)
171
+ stream_handler.addFilter(lambda record: record.name not in _CONSOLE_EXCLUDED_LOGGERS)
172
+ root_logger.addHandler(stream_handler)
173
+ _root_logger_set = True
174
+ return root_logger
175
+
176
+
177
+ def get_logger(module_name: str, level=logging.INFO, console: bool = True) -> LadderLogger:
178
+ """
179
+ Args:
180
+ module_name: Logger name, normally `__name__`
181
+ level: Level for this logger
182
+ console: If False, this logger's records go to every handler except the console - useful when
183
+ many processes share one terminal but each also writes its own log file. Evaluated here, so
184
+ only use it for a decision known at import time; otherwise call
185
+ `LadderLogger.disable_console()` once the decision is made.
186
+ """
187
+ logger = logging.getLogger(module_name)
188
+ logger.setLevel(level)
189
+ get_root_logger() # Ensure root logger exists.
190
+
191
+ if not console:
192
+ _disable_console_logging(module_name)
193
+
194
+ if any(module_name.startswith(patt) for patt in DEBUG_PATTERNS):
195
+ logger.setLevel(logging.DEBUG)
196
+
197
+ handlers = [h for h in logging.root.handlers if isinstance(h, logging.StreamHandler)]
198
+ for handler in handlers:
199
+ handler.setLevel(logging.DEBUG)
200
+
201
+ # Override manually configured loggers
202
+ _set_log_level_overrides()
203
+
204
+ return LadderLogger(logger)
205
+
206
+
207
+ def enter_ipdb_breakpoint_on_signal(signal_type=signal.SIGUSR1):
208
+ def handle_signal(_, frame):
209
+ import ipdb # noqa: T100
210
+
211
+ ipdb.set_trace(frame) # noqa: T100
212
+
213
+ signal.signal(signal_type, handle_signal)
214
+ print(f'Run `kill -{signal_type} {os.getpid()}` to enter ipdb`')
215
+
216
+
217
+ def _set_log_level_overrides() -> None:
218
+ """
219
+ Override certain loggers in `LOG_MODULE_OVERRIDES` to their corresponding levels.
220
+ Used to set logger levels from command line (via env variable) or to silence modules with spam logs.
221
+ """
222
+ for module, level in LOG_MODULE_OVERRIDES.items():
223
+ logging.getLogger(module).setLevel(level)
ladder/core/common/logger/stdout.py ADDED
@@ -0,0 +1,39 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import contextlib
2
+ import os
3
+ import sys
4
+
5
+
6
+ class DummyFile:
7
+ def write(self, x):
8
+ pass
9
+
10
+
11
+ @contextlib.contextmanager
12
+ def no_stdout_within_functions():
13
+ """
14
+ Silences std output (but not error) within this context manager,
15
+ even when calling external functions and processes
16
+ """
17
+ # open fds
18
+ null_fds = os.open(os.devnull, os.O_RDWR)
19
+ # save the current file descriptors to a tuple
20
+ save = os.dup(1)
21
+ # put /dev/null fds on 1 (stout) but not 2 (stderr)
22
+ os.dup2(null_fds, 1)
23
+
24
+ # *** run the function ***
25
+ yield
26
+
27
+ # restore file descriptors so I can print the results
28
+ os.dup2(save, 1)
29
+ # close the temporary fds
30
+ os.close(null_fds)
31
+
32
+
33
+ @contextlib.contextmanager
34
+ def no_stdout():
35
+ """silences output within this context manager"""
36
+ save_stdout = sys.stdout
37
+ sys.stdout = DummyFile()
38
+ yield
39
+ sys.stdout = save_stdout
ladder/core/common/platform.py ADDED
@@ -0,0 +1,121 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import os
2
+ import socket
3
+ from typing import List
4
+
5
+ import psutil
6
+
7
+
8
+ def is_test_env() -> bool:
9
+ return 'TEST_UNDECLARED_OUTPUTS_DIR' in os.environ
10
+
11
+
12
+ def is_running_in_docker() -> bool:
13
+ def docker_in_cgroup():
14
+ with open('/proc/self/cgroup') as f:
15
+ return any('docker' in line for line in f)
16
+
17
+ return os.path.exists('/.dockerenv') or (os.path.isfile('/proc/self/cgroup') and docker_in_cgroup())
18
+
19
+
20
+ def _get_ladder_repo_root() -> str:
21
+ """Absolute path to the root of this repository (ladder)"""
22
+ # NOTE: Use os.path.realpath - this also resolves bazel symlinks and directs to the real root path
23
+ return os.path.realpath(os.path.dirname(os.path.realpath(__file__)) + "/../../..")
24
+
25
+
26
+ # -----------------
27
+ # Job metadata
28
+ # -----------------
29
+
30
+ EXPERIMENT_NAME = os.getenv('EXPERIMENT_NAME', None)
31
+
32
+ # -----------------
33
+ # SYSTEM
34
+ # -----------------
35
+
36
+ USERNAME = os.getenv('LADDER_USERNAME', '') or os.getenv('USER', '')
37
+ HOSTNAME: str = socket.gethostname().split('.')[0]
38
+
39
+ NODE_VISIBLE_CPUS_COUNT: int = len(os.sched_getaffinity(os.getpid())) # CPUs visible to this process
40
+ NODE_TOTAL_CPUS_COUNT: int = psutil.cpu_count() # Total number of CPUs on this node
41
+
42
+ # -----------------
43
+ # Repo
44
+ # -----------------
45
+
46
+ # Absolute path to the root of this repository (ladder)
47
+ LADDER_ROOT = REPO_ROOT = _get_ladder_repo_root()
48
+
49
+ # Set environment variable for the repo root
50
+ os.environ['LADDER_ROOT'] = LADDER_ROOT
51
+
52
+ # TODO: Can also try /var/lock or ~/. Can make a function that tests permissions
53
+ LADDER_LOCKFILES_DIR = os.getenv('LADDER_LOCKFILES_DIR', '/tmp')
54
+
55
+ # -----------------
56
+ # CUDA
57
+ # -----------------
58
+
59
+
60
+ def cuda_visible_devices_ids() -> List[str]:
61
+ """
62
+ Return a list of strings of the values in CUDA_VISIBLE_DEVICES. Note these aren't guaranteed
63
+ to be numbers, e.g. GPU UUIDs such as 'GPU-00000000-0000-0000-0000-000000000000'
64
+ """
65
+ return [gpu_id for gpu_id in os.getenv("CUDA_VISIBLE_DEVICES", "").split(',') if gpu_id != '']
66
+
67
+
68
+ def cuda_visible_devices_indices() -> List[int]:
69
+ """
70
+ Return a list of ints corresponding to the values in CUDA_VISIBLE_DEVICES.
71
+ - If CUDA_VISIBLE_DEVICES holds GPU UUIDs, it returns consecutive numbers, one per visible device
72
+ - Otherwise, the values in CUDA_VISIBLE_DEVICES, which are a subset of the numbers in `nvidia-smi`,
73
+ not guaranteed to be ordered or consecutive
74
+ """
75
+ gpu_ids = cuda_visible_devices_ids()
76
+
77
+ if any(not gpu_id.isdigit() for gpu_id in gpu_ids):
78
+ return [i for i in range(len(gpu_ids))]
79
+ return [int(gpu_id) for gpu_id in gpu_ids]
80
+
81
+
82
+ # -----------------
83
+ # HUGGING FACE
84
+ # -----------------
85
+ HF_TOKEN = os.getenv('HF_TOKEN', '')
86
+
87
+ # -----------------
88
+ # Torch
89
+ # -----------------
90
+ # `torchrun` would define these env variables before launching the script
91
+ # https://pytorch.org/docs/stable/elastic/run.html#environment-variables
92
+ IS_RUNNING_IN_TORCHRUN = 'TORCHELASTIC_RUN_ID' in os.environ
93
+
94
+ # -----------------
95
+ # Docker
96
+ # -----------------
97
+ DOCKER_TRAIN_IMAGE = os.getenv('DOCKER_TRAIN_IMAGE', 'no-docker-image-detected')
98
+
99
+ # -----------------
100
+ # Cloud
101
+ # -----------------
102
+ # TODO: These are just examples. Proper detection needs to be done
103
+ IS_RUNNING_IN_CLOUD = os.getenv('IS_RUNNING_IN_CLOUD', '') == 'true'
104
+ IS_RUNNING_IN_AWS = os.getenv('IS_RUNNING_IN_AWS', '') == 'true'
105
+ IS_RUNNING_IN_AZURE = os.getenv('IS_RUNNING_IN_AZURE', '') == 'true'
106
+ IS_RUNNING_IN_GCP = os.getenv('IS_RUNNING_IN_GCP', '') == 'true'
107
+
108
+ if IS_RUNNING_IN_AWS:
109
+ TRAINING_PLATFORM = "SageMaker"
110
+ NODE_COUNT = int(os.getenv('NODE_COUNT', '-1'))
111
+ elif IS_RUNNING_IN_AZURE:
112
+ TRAINING_PLATFORM = "AzureML"
113
+ NODE_COUNT = int(os.getenv('NODE_COUNT', '-1'))
114
+ elif IS_RUNNING_IN_GCP:
115
+ TRAINING_PLATFORM = "VertexAI"
116
+ NODE_COUNT = int(os.getenv('NODE_COUNT', '-1'))
117
+ else:
118
+ TRAINING_PLATFORM = "Local Machine"
119
+ NODE_COUNT = 1
120
+
121
+ IS_MULTINODE = NODE_COUNT > 1
ladder/core/databib/__init__.py ADDED
File without changes
ladder/core/databib/config/__init__.py ADDED
@@ -0,0 +1,16 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from .auto_config import AutoConfig, AutoConfigurable
2
+ from .config import Config, ConfigT, Configurable
3
+ from .config_parser import ConfigParser, assign_dict_value_by_recursive_access
4
+ from .yaml_util import load_config, update_config_dict
5
+
6
+ __all__ = [
7
+ 'Config',
8
+ 'Configurable',
9
+ 'AutoConfig',
10
+ 'AutoConfigurable',
11
+ 'ConfigT',
12
+ 'ConfigParser',
13
+ 'assign_dict_value_by_recursive_access',
14
+ 'load_config',
15
+ 'update_config_dict',
16
+ ]
ladder/core/databib/config/auto_config.py ADDED
@@ -0,0 +1,142 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import functools
2
+ import inspect
3
+ import pprint
4
+ from typing import Any, Type, TypeVar
5
+
6
+ from ladder.core.databib.dataclasses.dataclass_utils import parametrize
7
+
8
+ from .config import (
9
+ AutoRecordsManager,
10
+ Config,
11
+ ConfigAttributeContext,
12
+ ConfigMeta,
13
+ ConfigT,
14
+ MissingConfigAttributeError,
15
+ )
16
+
17
+
18
+ class AutoConfigMeta(ConfigMeta):
19
+ @functools.lru_cache(maxsize=None, typed=True) # noqa: B019
20
+ def __getitem__(cls, config_type) -> type: # noqa: N805
21
+ """AutoConfig[ModelConfig]: an AutoConfig that only creates subclasses of ModelConfig."""
22
+ if cls is not AutoConfig:
23
+ raise TypeError(f"Only AutoConfig can be subscripted, not {cls.__name__}")
24
+ # Prevent things like AutoConfig[TypeVar] or AutoConfig[Any]
25
+ if not inspect.isclass(config_type):
26
+ raise TypeError(f"{cls.__name__} expects a config class, but got {config_type}")
27
+ return parametrize(cls, (config_type,), ConfigT=config_type)
28
+
29
+ def __instancecheck__(cls, maybe_config): # noqa: N805
30
+ """
31
+ Override instance checks so that AutoConfig type annotations in classes work properly
32
+ isinstance(ConfigA(), AutoConfig[ConfigA]) -> True
33
+ isinstance(ConfigB(), AutoConfig[ConfigA]) -> False
34
+ isinstance(ConfigA(), AutoConfig) -> True
35
+ """
36
+ if not isinstance(cls.ConfigT, TypeVar):
37
+ return isinstance(maybe_config, cls.ConfigT)
38
+ if isinstance(maybe_config, Config):
39
+ return True
40
+ return super().__instancecheck__(maybe_config)
41
+
42
+
43
+ class AutoConfig(Config, metaclass=AutoConfigMeta):
44
+ """
45
+ A generic config class that will be instantiated as a specific config class returned by __new__.
46
+ Selecting the correct config class requires setting the correct class path to a corresponding
47
+ Configurable class in the autoclass attribute, e.g. databib.config.config.Configurable. The returned
48
+ config class is the one to which `ConfigT` attribute points to. Note that only Configurable classes
49
+ whose config class is concrete (not a TypeVar) can be specified.
50
+
51
+ Example:
52
+ class ModelConfig(Config):
53
+ ...
54
+
55
+ class Model(Configurable[ModelConfig]):
56
+ ...
57
+
58
+ model_config = AutoConfig(autoclass="full.path.to.module.Model")
59
+ assert isinstance(model_config, ModelConfig) # True
60
+ assert model_config.autoclass == "full.path.to.module.Model" # True
61
+ model = AutoConfiguralbe(model_config)
62
+ assert isinstance(model, Model) # True
63
+ """
64
+
65
+ ConfigT = ConfigT # a TypeVar until the class is subscripted, e.g. AutoConfig[ModelConfig]
66
+
67
+ def __new__(cls, *args, **kwargs):
68
+ ConfigType = cls._get_actual_config_class(kwargs)
69
+ # Make sure the AutoConfig[...] argument is respected
70
+ if not isinstance(cls.ConfigT, TypeVar):
71
+ if not issubclass(ConfigType, cls.ConfigT):
72
+ raise TypeError(
73
+ f"Class {cls.__name__} can only create config instances, which are "
74
+ f"subclasses of {cls.ConfigT}, but instance of {ConfigType} requested"
75
+ )
76
+ return ConfigType(*args, **kwargs)
77
+
78
+ @classmethod
79
+ def _get_actual_config_class(cls, data: dict) -> Type[Config]:
80
+ key = "autoclass"
81
+
82
+ with ConfigAttributeContext(cls, key):
83
+ if key not in data:
84
+ raise MissingConfigAttributeError(f"Field '{key}' of {cls.__name__} was not provided")
85
+
86
+ class_path = data[key]
87
+ if class_path == "":
88
+ raise ValueError(
89
+ f"Attribute {key} missing for {cls.__name__}. Availble data:\n{pprint.pformat(data, indent=2)}"
90
+ )
91
+
92
+ ConfigType = AutoRecordsManager.config_cls_from_configurable_path(class_path)
93
+
94
+ return ConfigType # type: ignore[return-value]
95
+
96
+ @classmethod
97
+ def _ignore_redundant_keys(cls, data: dict) -> dict:
98
+ # Make sure from_json works with AutoConfig
99
+ ConfigType = cls._get_actual_config_class(data)
100
+ return ConfigType._ignore_redundant_keys(data) # pylint: disable=protected-access # noqa: SLF001
101
+
102
+
103
+ class AutoConfigurable:
104
+ """
105
+ A generic configurable class that will be instantiated as a specific instance of Configurable returned by __new__.
106
+ Selecting the correct config class requires passing a config instance with autoclass attribute set to
107
+ a full class path, e.g. databib.config.config.Configurable. Note that only Configurable classes whose config
108
+ class is concrete (not a TypeVar) can be specified. Note that only Configurable classes will be created
109
+
110
+ Example:
111
+ class ModelConfig(Config):
112
+ ...
113
+
114
+ class Model(Configurable[ModelConfig]):
115
+ ...
116
+
117
+ model_config = AutoConfig(autoclass="full.path.to.module.Model")
118
+ assert isinstance(model_config, ModelConfig) # True
119
+ assert model_config.autoclass == "full.path.to.module.Model" # True
120
+ model = AutoConfiguralbe(model_config)
121
+ assert isinstance(model, Model) # True
122
+ """
123
+
124
+ def __new__(cls, config, **kwargs):
125
+ ConfigurableT = AutoConfigurable.target_class_from_config(config)
126
+ return ConfigurableT(config=config, **kwargs)
127
+
128
+ @staticmethod
129
+ def target_class_from_config(config: Config) -> Type:
130
+ if not isinstance(config, Config):
131
+ raise TypeError(
132
+ f"{AutoConfigurable.__name__} expects an instance of Config, but got {type(config)}"
133
+ )
134
+
135
+ return AutoRecordsManager.configurable_cls_from_config(config) # type: ignore[arg-type]
136
+
137
+ def __getattr__(self, _name: str) -> Any:
138
+ """Define to help pyright"""
139
+
140
+ def __call__(self, *_args, **_kwargs) -> Any:
141
+ """Define to help pyright"""
142
+ return None
ladder/core/databib/config/config.py ADDED
@@ -0,0 +1,780 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import collections
2
+ import dataclasses
3
+ import enum
4
+ import functools
5
+ import importlib
6
+ import inspect
7
+ import os
8
+ import pprint
9
+ import sys
10
+ from abc import ABCMeta
11
+ from typing import Any, ClassVar, Dict, Generic, List, Sequence, TextIO, Tuple, Type, TypeVar
12
+
13
+ from deepdiff import DeepDiff
14
+ from frozendict import FrozenOrderedDict, frozendict
15
+
16
+ from ladder.core.databib.config.yaml_util import load_config
17
+ from ladder.core.databib.dataclasses import (
18
+ Dataclass,
19
+ DataclassDict,
20
+ DataclassInterface,
21
+ DataclassList,
22
+ DataclassMeta,
23
+ )
24
+ from ladder.core.databib.dataclasses.dataclass_utils import parametrize
25
+ from ladder.core.databib.utils.classproperty import cached_classproperty
26
+ from ladder.core.databib.utils.typing_utils import (
27
+ annotation_is_dict,
28
+ annotation_is_enum,
29
+ annotation_is_list,
30
+ annotation_is_optional,
31
+ annotation_is_tuple,
32
+ annotation_is_union,
33
+ get_annotation_type_args,
34
+ get_dict_annotation_type_args,
35
+ get_list_annotation_type_args,
36
+ get_maybe_optional_type,
37
+ maybe_autocast_native_types,
38
+ value_type_is_annotation_type,
39
+ )
40
+
41
+ _FROZEN_DEFAULTS_TYPE_MAPPING: Dict[str, type] = {
42
+ 'dict': frozendict,
43
+ 'list': tuple,
44
+ 'OrderedDict': FrozenOrderedDict,
45
+ 'set': frozenset,
46
+ }
47
+
48
+ _FROZEN_TYPE_MAPPING: Dict[str, type] = {
49
+ 'set': frozenset,
50
+ }
51
+
52
+
53
+ class ConfigMeta(DataclassMeta):
54
+ def __new__(mcs, name, bases, attrs, **kwargs): # noqa: N804
55
+ mcs._assert_config_is_non_generic(name, bases)
56
+ mcs._assert_post_init_calls_super(name, attrs)
57
+ mcs._assert_class_does_not_overwrite_autoclass_key(name, attrs)
58
+
59
+ attrs = mcs._replace_default_values_with_frozen_types(attrs)
60
+
61
+ new_cls = super().__new__(mcs, name, bases, attrs, **kwargs)
62
+ new_dataclass = dataclasses.dataclass(new_cls, init=False, frozen=True, repr=False)
63
+ new_dataclass._prevent_forbidden_type_annotations() # noqa: SLF001
64
+
65
+ # frozen=True causes __setattr__ to get generated (and doesn't allow it to be defined on the class)
66
+ # Override the one generated by the dataclass to get around that restriction.
67
+ new_dataclass.__setattr__ = new_dataclass.__config_setattr__
68
+
69
+ return new_dataclass
70
+
71
+ @staticmethod
72
+ def _assert_post_init_calls_super(name, attrs):
73
+ """Check the __post_init__ definition of the subclass and make sure it calls super().__post_init__()"""
74
+ if name == "Config" or "__post_init__" not in attrs:
75
+ return
76
+ if "super().__post_init__()" not in inspect.getsource(attrs["__post_init__"]):
77
+ raise RuntimeError(f"{name}.__post_init__ method is missing a call to super().__post_init__()")
78
+
79
+ @staticmethod
80
+ def _assert_config_is_non_generic(name, bases):
81
+ """
82
+ Make sure that the Config subclass doesn't inherit from Generic.
83
+ This functionality is not supported and causes multiple problems
84
+ """
85
+ # AutoConfig[X] is the one parametrized config class
86
+ if name == "AutoConfig" or name.startswith("AutoConfig["):
87
+ return
88
+ for base in bases:
89
+ if base is Generic or getattr(base, "__parameters__", False):
90
+ raise TypeError(f"Generic config classes are not allowed. Please make {name} non-generic.")
91
+
92
+ @staticmethod
93
+ def _assert_class_does_not_overwrite_autoclass_key(name, attrs):
94
+ """
95
+ Make sure that the special `autoclass` key of AutoConfig is not accidentally overwritten by a Config subclass
96
+ """
97
+ if name == "Config":
98
+ return
99
+ annotations = attrs.get("__annotations__", {})
100
+ autoclass_key = "autoclass"
101
+ if autoclass_key in annotations:
102
+ raise ValueError(
103
+ f"Class {name} defines attribute {autoclass_key}, which is a reserved attribute. Please rename."
104
+ )
105
+
106
+ @staticmethod
107
+ def _replace_default_values_with_frozen_types(attrs) -> Dict[str, Type]:
108
+ """
109
+ Replace the mutable default values in a subclass of Config with their immutable counterparts.
110
+ Note that we are replacing only the default values, not the type annotations themselves.
111
+ """
112
+ annotations = attrs.get("__annotations__", {})
113
+ return {
114
+ key: _FROZEN_DEFAULTS_TYPE_MAPPING[type(value).__name__](value)
115
+ if key in annotations and type(value).__name__ in _FROZEN_DEFAULTS_TYPE_MAPPING
116
+ else value
117
+ for key, value in attrs.items()
118
+ }
119
+
120
+ def _define_dict_and_list_attribute_classes(cls): # noqa: N805
121
+ """
122
+ Overloading DataclassMeta._define_dict_and_list_attribute_classes
123
+
124
+ [IMPORTANT]: Suppose we have a Config
125
+ ```
126
+ @dataclass
127
+ class MyConfig(Config):
128
+ my_field: Dict[str, int]
129
+ ```
130
+ The values for my_field will always be cast to `ConfigDict[int]` inside `Config.__init__()`
131
+ However, the type `ConfigDict[int]` doesn't exist before we try to create an instance of
132
+ `MyConfig`. This is problematic because:
133
+ 1. We cannot properly unpickle such classes when using multiprocessing. In particular, the
134
+ class `MyConfig` will be known to the subprocess since the class will be imported.
135
+ However, `ConfigDict[int]` will be undefined, since the subprocess hasn't created
136
+ an instance of `MyConfig` before it tries to unpickle it
137
+ 2. If the types inside `Dict` are not allowed in `ConfigDict`, error will be raised only
138
+ when we try to create an instance, instead of at class definition time
139
+ To resolve these problems, here we define all the equivalent `ConfigDict` and `ConfigList`
140
+ classes needed for the new dataclass attributes
141
+ """
142
+ import ladder.core.databib.config.config_iterables as config_iterables # pylint: disable=cyclic-import
143
+
144
+ # NOTE: At this point, @dataclass has been applied so `__dataclass_fields__` is not the
145
+ # absolute source of truth for dataclass attributes. `__annotations__` gives us the fields added in
146
+ # this class definition, while `__dataclass_fields__` gives us the fields defined by the parents.
147
+ # We check both to also cover any transitive updates on parent class attributes, e.g. if
148
+ # called by `__getitem__`
149
+ annotations = getattr(cls, '__annotations__', {})
150
+ dataclass_fields = getattr(cls, '__dataclass_fields__', {})
151
+ fields = {**annotations, **{field.name: field.type for field in dataclass_fields.values()}}
152
+
153
+ for field_name, field_type in fields.items():
154
+ if annotation_is_dict(field_type):
155
+ _, DValueT = get_dict_annotation_type_args(field_type)
156
+ try:
157
+ config_iterables.ConfigDict[DValueT]
158
+ except TypeError as exc:
159
+ # Provide more informative error message when DValueT not allowed
160
+ message = f"Cannot cast {cls.__name__}.{field_name} to ConfigDict[{DValueT}].\n{exc}"
161
+ raise TypeError(message) from exc
162
+ if annotation_is_list(field_type):
163
+ LValueT: Type = get_list_annotation_type_args(field_type)[0]
164
+ try:
165
+ config_iterables.ConfigList[LValueT]
166
+ except TypeError as exc:
167
+ # Provide more informative error message when DValueT not allowed
168
+ message = f"Cannot cast {cls.__name__}.{field_name} to ConfigList[{LValueT}].\n{exc}"
169
+ raise TypeError(message) from exc
170
+
171
+ def _prevent_forbidden_type_annotations(cls): # noqa: N805
172
+ """
173
+ Prevent forbidden type annotations for Config attributes
174
+ """
175
+
176
+ for field in getattr(cls, "__dataclass_fields__", {}).values():
177
+ field_type = get_maybe_optional_type(field.type)
178
+
179
+ # Forbid Union[Config, ...] and Tuple[Config, ...]
180
+ if annotation_is_union(field_type) or annotation_is_tuple(field_type):
181
+ type_args: Tuple[Type, ...] = get_annotation_type_args(field_type)
182
+
183
+ is_config: List[bool] = [
184
+ inspect.isclass(arg) and isinstance(arg, ConfigMeta) for arg in type_args
185
+ ]
186
+ if any(is_config):
187
+ etype = 'Union' if annotation_is_union(field_type) else 'Tuple'
188
+ raise TypeError(
189
+ f"Class {cls} has field {field.name}: {field.type}, but {etype} with members "
190
+ f"of type Config are not allowed. Find a better abstraction."
191
+ )
192
+
193
+ is_enum: List[bool] = [annotation_is_enum(arg) for arg in type_args]
194
+
195
+ if sum(is_enum) > 1 and annotation_is_union(field_type):
196
+ raise TypeError(
197
+ f"Class {cls} has field {field.name}: {field.type}, "
198
+ f"but Union with multiple enums is not supported"
199
+ )
200
+
201
+ if sum(is_enum) > 0 and annotation_is_tuple(field_type):
202
+ raise TypeError(
203
+ f"Class {cls} has field {field.name}: {field.type}, "
204
+ f"but Tuple with enums is not supported"
205
+ )
206
+ continue
207
+
208
+ if annotation_is_dict(field_type) or annotation_is_list(field_type):
209
+ # Annotation type checks will be run by cls.types below
210
+ continue
211
+ # Forbid non-class type annotations
212
+ if (
213
+ not inspect.isclass(field_type)
214
+ and not isinstance(field_type, dataclasses.InitVar)
215
+ and field_type is not dataclasses.InitVar
216
+ and getattr(field_type, "__origin__", None) is not ClassVar
217
+ ):
218
+ raise TypeError(
219
+ f"Forbidden type annotation in {cls} for field '{field.name}: {field.type}'. "
220
+ f"Expected a class, Optional[class], Dict, List, Tuple or Union"
221
+ )
222
+
223
+
224
+ class Config(Dataclass, metaclass=ConfigMeta):
225
+ autoclass: str = "" # Special attribute for AutoConfig and AutoConfigurable
226
+
227
+ def __init__(self, **kwargs):
228
+ object.__setattr__(self, "_Config__frozen", False)
229
+
230
+ self._set_attributes(**kwargs)
231
+ self._init_remaining_subconfigs()
232
+ self._cast_dict_and_list_attrs()
233
+ self._assert_no_missing_attributes()
234
+ self.__post_init__()
235
+ self._freeze_mutable_attributes()
236
+ self._assert_post_init_is_idempotent()
237
+ # Cast dict and list attrs again to ConfigDict and ConfigList in case __post_init__ modified them
238
+ self._cast_dict_and_list_attrs()
239
+ self._make_type_checks()
240
+
241
+ object.__setattr__(self, "_Config__frozen", True)
242
+
243
+ def __post_init__(self):
244
+ pass
245
+
246
+ def _set_attributes(self, **kwargs):
247
+ for key, value in kwargs.items():
248
+ with ConfigAttributeContext(self.__class__, key):
249
+ # 1. Make sure key is a valid attribute of Config
250
+ if key not in self.__dataclass_fields__:
251
+ raise UnexpectedConfigAttributeError(
252
+ f"{self.__class__.__name__}.__init__() got unexpected keyword argument: "
253
+ f"{key}, expects one of: {list(self.__dataclass_fields__.keys())}"
254
+ )
255
+
256
+ annotation_type: Type = self.__dataclass_fields__[key].type
257
+ default_value: Any = self.__dataclass_fields__[key].default
258
+
259
+ # 2. If annotated type is Config, recursively initialize its attributes
260
+ if isinstance(annotation_type, ConfigMeta):
261
+ # 2.1 `value` is neither a Config, nor a dict -> INVALID
262
+ if not isinstance(value, (Config, collections.abc.Mapping)):
263
+ raise InvalidConfigAttributeTypeError(
264
+ f"{self.__class__.__name__}.{key} expects dict-like object "
265
+ f"(nested config), but got string/value: {value}"
266
+ )
267
+
268
+ # 2.2. `value` is already a complete Config instance -> default values don't make
269
+ # a difference and we can confidently set the attribute to `value`
270
+ if isinstance(value, Config):
271
+ pass
272
+
273
+ # 2.3. A default value is provided as a Config -> then apply `value` on top of the default
274
+ elif default_value != dataclasses.MISSING:
275
+ assert isinstance(value, collections.abc.Mapping), value
276
+ assert isinstance(default_value, Config), default_value
277
+
278
+ value = replace_with_auto_config(default_value, value)
279
+ assert isinstance(value, annotation_type), value
280
+
281
+ # 2.3 If `value` is not a Config, we make it one
282
+ if not isinstance(value, Config):
283
+ value = annotation_type(**value)
284
+
285
+ # 3. Annotated type is Optional[Config]
286
+ elif annotation_is_optional(annotation_type) and isinstance(
287
+ get_maybe_optional_type(annotation_type), ConfigMeta
288
+ ):
289
+ # This is not supported yet
290
+ if default_value != dataclasses.MISSING and default_value is not None:
291
+ raise NotImplementedError(
292
+ f"Default values different from None are not supported for Optional[Config], "
293
+ f"but got {self.__class__.__name__}.{key}: {annotation_type} = {default_value}"
294
+ )
295
+ if (value is not None) and not isinstance(value, Config):
296
+ value = get_maybe_optional_type(annotation_type)(**value)
297
+
298
+ # 4. Annotated type is Dict[str, Any]
299
+ elif annotation_is_dict(annotation_type):
300
+ # 4.1 Make sure `value` is dict-like
301
+ if not isinstance(value, collections.abc.Mapping):
302
+ raise InvalidConfigAttributeTypeError(
303
+ f"{self.__class__.__name__}.{key} expects dict-like object "
304
+ f", but got value: {value}"
305
+ )
306
+ # 4.2. SPECIAL CASE: If `value` is empty dict, then directly overwrite the default.
307
+ # Otherwise there is no way to overwrite defaults
308
+ if value != {}:
309
+ # Merge the current value of the attribute with the new value.
310
+ # Note that Dict[str, Config] or nested versions must support
311
+ # initialization with dict args for `Config` so that we have proper YAML support
312
+ value = _update_dict_of_maybe_configs(getattr(self, key, {}), value)
313
+
314
+ # 5. Annotated type is enum.Enum
315
+ elif annotation_is_enum(annotation_type) and not isinstance(value, enum.Enum):
316
+ assert isinstance(value, str), value
317
+ value = annotation_type(value)
318
+
319
+ # 6. Annotated type is Union[enum.Enum, ...]
320
+ elif isinstance(value, str) and annotation_is_union(annotation_type):
321
+ union_types: Tuple[Type, ...] = get_annotation_type_args(annotation_type)
322
+ is_enum: List[bool] = [
323
+ annotation_is_enum(union_type)
324
+ for union_type in get_annotation_type_args(annotation_type)
325
+ ]
326
+ if any(is_enum):
327
+ enum_type = union_types[is_enum.index(True)]
328
+ value = enum_type(value)
329
+
330
+ # 7. Autocast native types (e.g. int -> float, or list -> tuple for Tuple fields)
331
+ else:
332
+ value = maybe_autocast_native_types(value, get_maybe_optional_type(annotation_type))
333
+
334
+ setattr(self, key, value)
335
+
336
+ @cached_classproperty
337
+ def _cast_fields(cls) -> Dict[str, Any]: # noqa: N805
338
+ """
339
+ Returns a frozendict containing only the fields annotated as Dict and List in this `Config`
340
+ and their equivalent `ConfigDict` and `ConfigList` types that values should be cast to.
341
+ Note that ConfigMeta already ensures that all Dict and List annotations can be cast.
342
+
343
+ Note: we iterate over cls.fields instead of super()._cast_fields(), as the latter will materialize
344
+ a config class with DataclassDict / DataclassList children first, which we will throw away anyway.
345
+
346
+ Returns: Dict[str, Union[Type[ConfigDict], Type[ConfigList]]]
347
+ """
348
+ # pylint: disable=no-self-argument
349
+ import ladder.core.databib.config.config_iterables as config_iterables # pylint: disable=cyclic-import
350
+
351
+ cast_fields: Dict[str, Type[DataclassInterface]] = {}
352
+ for field in cls.fields.values():
353
+ if annotation_is_dict(field.type):
354
+ _, value_type = get_dict_annotation_type_args(field.type)
355
+ cast_fields[field.name] = config_iterables.ConfigDict[value_type] # type: ignore[name-defined]
356
+ elif annotation_is_list(field.type):
357
+ (value_type,) = get_list_annotation_type_args(field.type)
358
+ cast_fields[field.name] = config_iterables.ConfigList[value_type] # type: ignore[name-defined]
359
+ return frozendict(cast_fields)
360
+
361
+ def _init_remaining_subconfigs(self):
362
+ """Initialize any attributes which were not passed to __init__ (maybe they have default values)"""
363
+ for key in self.__dataclass_fields__:
364
+ if not hasattr(self, key) and isinstance(self.__dataclass_fields__[key].type, ConfigMeta):
365
+ with ConfigAttributeContext(self.__class__, key):
366
+ setattr(self, key, self.__dataclass_fields__[key].type())
367
+
368
+ def _cast_dict_and_list_attrs(self):
369
+ """
370
+ Cast attributes of sel annotated as Dict or List to their corresponding immutable
371
+ config equivalents, i.e. ConfigDict and ConfigList
372
+ """
373
+ for field_name, field_type in self._cast_fields.items():
374
+ field_value = getattr(self, field_name)
375
+ if type(field_value) is field_type:
376
+ # If field_value is already of type DataclassDict or DataclassList,
377
+ # then we don't need to worry about ValueT being a dataclass
378
+ continue
379
+ if inspect.isclass(field_type.ValueT) and issubclass(field_type.ValueT, Config):
380
+ # Cast the values inside the Dict or the List to Config (expected Config.__init__ behavior)
381
+ if issubclass(field_type, DataclassDict):
382
+ if not isinstance(field_value, collections.abc.Mapping):
383
+ raise TypeError(
384
+ f"Expected dict for field {field_name}, "
385
+ f"but got {field_value} of type {type(field_value)}"
386
+ )
387
+ field_value = {
388
+ key: field_type.ValueT(**value) if not isinstance(value, Config) else value
389
+ for key, value in field_value.items()
390
+ }
391
+ elif issubclass(field_type, DataclassList):
392
+ if not isinstance(field_value, Sequence):
393
+ raise TypeError(
394
+ f"Expected dict for field {field_name}, "
395
+ f"but got {field_value} of type {type(field_value)}"
396
+ )
397
+ field_value = [
398
+ field_type.ValueT(**value) if not isinstance(value, Config) else value
399
+ for value in field_value
400
+ ]
401
+ setattr(self, field_name, field_type(field_value))
402
+
403
+ def _freeze_mutable_attributes(self):
404
+ for key in self.__dataclass_fields__:
405
+ value = getattr(self, key)
406
+ if type(value).__name__ in _FROZEN_TYPE_MAPPING:
407
+ setattr(self, key, _FROZEN_TYPE_MAPPING[type(value).__name__](value))
408
+
409
+ def _assert_no_missing_attributes(self):
410
+ all_missing_attributes = []
411
+ for key in self.__dataclass_fields__.keys():
412
+ if not hasattr(self, key):
413
+ all_missing_attributes.append(key)
414
+
415
+ if all_missing_attributes:
416
+ with ConfigAttributeContext(self.__class__, all_missing_attributes[0]):
417
+ raise MissingConfigAttributeError(
418
+ f"Fields {all_missing_attributes} of {self.__class__.__name__} were not provided"
419
+ )
420
+
421
+ def _assert_post_init_is_idempotent(self):
422
+ """
423
+ Make sure that when called twice, `self.__post_init__()` keeps references to all basic values
424
+ instead of generating new objects. Example:
425
+ ```
426
+ config = Config();
427
+ new_config = config.replace(**{})
428
+ ```
429
+ If __post_init__() generates any values dynamically, we want to make sure that config and new_config
430
+ have the same dynamically generated values, i.e. config == new_config
431
+ """
432
+ post_init_dict = self.as_dict()
433
+ self.__post_init__()
434
+ self._freeze_mutable_attributes()
435
+ twice_post_init_dict = self.as_dict()
436
+ if post_init_dict != twice_post_init_dict:
437
+ dict_diff = DeepDiff(post_init_dict, twice_post_init_dict)
438
+ raise RuntimeError(
439
+ f"{self.__class__.__name__}.__post_init__() is not idempotent: "
440
+ f"got difference\n{pprint.pformat(dict_diff, indent=2)}"
441
+ )
442
+
443
+ def _make_type_checks(self):
444
+ """
445
+ Overload Dataclass._make_type_checks to use exact type matching, with the exception of
446
+ AutoConfig fields, where we check that the value is an instance of the exact annotation bound
447
+ (the resolved Config subclass). This is the same policy ConfigDict / ConfigList apply to their
448
+ values via `_auto_config_isinstance`.
449
+ """
450
+ import ladder.core.databib.config.config_iterables as config_iterables # pylint: disable=cyclic-import
451
+
452
+ for field_name, field_type in self.types.items():
453
+ value = getattr(self, field_name)
454
+ with ConfigAttributeContext(self.__class__, field_name):
455
+ if not value_type_is_annotation_type(
456
+ value, field_type, config_iterables._auto_config_isinstance # noqa: SLF001
457
+ ):
458
+ raise InvalidConfigAttributeTypeError(
459
+ f"Incorrect type provided for {self.__class__.__name__}.{field_name}: "
460
+ f"expected {field_type}, but got value {value} with type {type(value)}"
461
+ )
462
+
463
+ @classmethod
464
+ def make_empty(cls):
465
+ raise NotImplementedError(f"make_empty() is disabled for Config classes ({cls.__name__})")
466
+
467
+ @classmethod
468
+ def from_yaml(cls, yml_path: str, save_path: bool = True):
469
+ if not os.path.exists(yml_path):
470
+ raise FileNotFoundError(f'File not found: "{yml_path}"')
471
+
472
+ config_dict = load_config(yml_path)
473
+ if config_dict is None:
474
+ raise ValueError("Config loaded from yaml file cannot be empty.")
475
+
476
+ if save_path and 'config_path' in cls.keys():
477
+ return cls(**config_dict, config_path=yml_path)
478
+ return cls(**config_dict)
479
+
480
+ @classmethod
481
+ def from_yaml_file_object(cls, yml_file: TextIO):
482
+ config = load_config(yml_file)
483
+ if config is None:
484
+ raise ValueError("Config loaded from yaml file cannot be empty.")
485
+ return cls(**config)
486
+
487
+ def __config_setattr__(self, key, value):
488
+ with ConfigAttributeContext(self.__class__, key):
489
+ if self.__frozen:
490
+ raise RuntimeError(
491
+ "Cannot set attribute '{}' to '{}' on a frozen object: {}".format(key, value, self)
492
+ )
493
+ if key not in self.__dataclass_fields__:
494
+ raise UnexpectedConfigAttributeError(
495
+ "Cannot set attribute {} on {} as it is not one of its fields".format(
496
+ key, self.__class__.__name__
497
+ )
498
+ )
499
+ object.__setattr__(self, key, value)
500
+
501
+ def as_json(self, recursive: bool = True) -> dict:
502
+ data = super().as_json(recursive=recursive)
503
+ # Remove autoclass_key if it's empty to avoid clutter where the field is useless
504
+ if self.autoclass == "":
505
+ data.pop("autoclass", None)
506
+
507
+ # Convert enum.Enum to str
508
+ for key, value in data.items():
509
+ if isinstance(value, enum.Enum):
510
+ data[key] = str(value.value)
511
+
512
+ return data
513
+
514
+
515
+ def replace_with_auto_config(default: Config, replacements: Dict[str, Any]) -> Config:
516
+ """
517
+ Recursively replace `default` with `replacements`
518
+
519
+ NOTE: This is NOT equivalent to `default.replace(**replacements)`. Consider these caveats:
520
+ 1. Let default has a field of type AutoConfig and replacements requests a different type via 'autoclass'.
521
+ Then `default.replace` will be incorrect as it will return the same type as the current value
522
+ of its field instead of the type specified by 'autoclass' in replacements
523
+ 2. The above cannot be always resolved by type(default)(**{**default.as_json(), **replacements}) either.
524
+ If default has a field of type AutoConfig, but its default value is a specific Config instance,
525
+ 'autoclass' will be empty when `default.as_json()` is called and cannot be reconstructed either
526
+ since we don't know the target Configurable type.
527
+ """
528
+ for key, value in replacements.items():
529
+ if isinstance(value, collections.abc.Mapping):
530
+ replacements[key] = replace_with_auto_config(getattr(default, key), value) # type: ignore[arg-type]
531
+
532
+ if replacements.get('autoclass', '') != '':
533
+ # replacements changes the output type - we cannot call simple default.replace
534
+ # NOTE: If the annotation is not AutoConfig, the calling function will complain
535
+ import ladder.core.databib.config.auto_config as auto_config # pylint: disable=cyclic-import
536
+
537
+ output: Config = auto_config.AutoConfig(**{**default.as_json(recursive=False), **replacements})
538
+ else:
539
+ # Calling replace is safe since all nested dicts in replacements have been recursively
540
+ # converted to Config instances already and replace will overwrite them directly in `default`
541
+ output = default.replace(**replacements)
542
+
543
+ return output
544
+
545
+
546
+ class ConfigAttributeContext:
547
+ attr_tree: List[Tuple[ConfigMeta, str]] = []
548
+
549
+ def __init__(self, config_class: Type[Config], attr_name: str):
550
+ self._config_class = config_class
551
+ self._attr_name = attr_name
552
+
553
+ def __enter__(self):
554
+ self.attr_tree.append((self._config_class, self._attr_name))
555
+
556
+ def __exit__(self, exc_type, exc_val, exc_tb):
557
+ if exc_type is None:
558
+ self.attr_tree.pop()
559
+
560
+ @classmethod
561
+ def reset(cls):
562
+ cls.attr_tree.clear()
563
+
564
+
565
+ class ConfigAttributeError(Exception):
566
+ def __init__(self, *args, **kwargs):
567
+ super().__init__(*args, **kwargs)
568
+ self._attr_tree = self._get_attr_tree()
569
+ ConfigAttributeContext.reset()
570
+
571
+ def _get_attr_tree(self):
572
+ attr_tree = ""
573
+ for i, (config_class, attr_name) in enumerate(ConfigAttributeContext.attr_tree):
574
+ attr_tree += config_class.__name__ + "\n" + (i + 1) * "\t" + attr_name + ": "
575
+ attr_tree += self.__class__.__name__
576
+ return attr_tree
577
+
578
+ def __str__(self):
579
+ return super().__str__() + "\n\n" + self._attr_tree
580
+
581
+
582
+ class UnexpectedConfigAttributeError(ConfigAttributeError):
583
+ pass
584
+
585
+
586
+ class MissingConfigAttributeError(ConfigAttributeError):
587
+ pass
588
+
589
+
590
+ class InvalidConfigAttributeTypeError(ConfigAttributeError):
591
+ pass
592
+
593
+
594
+ class ConfigAttributeInvalidValueError(ConfigAttributeError):
595
+ pass
596
+
597
+
598
+ ConfigT = TypeVar("ConfigT", bound=Config)
599
+
600
+
601
+ class ConfigurableMeta(ABCMeta):
602
+ @functools.lru_cache(maxsize=None, typed=True) # noqa: B019
603
+ def __getitem__(cls, config_type): # noqa: N805
604
+ """Configurable[ModelConfig] (or Model[ModelConfig]): the class with its config class set."""
605
+ if not isinstance(cls.ConfigT, TypeVar):
606
+ raise TypeError(f"{cls.__name__} already has a config class: {cls.ConfigT}")
607
+ new_cls = parametrize(cls, (config_type,))
608
+ # Set after creation, so only named subclasses (class Model(Configurable[ModelConfig])) register
609
+ new_cls.ConfigT = config_type
610
+ return new_cls
611
+
612
+
613
+ class Configurable(metaclass=ConfigurableMeta):
614
+ """A class built from a config, e.g. `class Model(Configurable[ModelConfig])`, which has
615
+ `Model.ConfigT is ModelConfig`. A class whose ConfigT is still a TypeVar can be subscripted again."""
616
+
617
+ ConfigT = ConfigT
618
+
619
+ def __init__(self, config: ConfigT):
620
+ if not config.__class__ == self.ConfigT:
621
+ raise TypeError(
622
+ f"{self.__class__}.__init__() expects an instance of "
623
+ f"{self.ConfigT}, but got {config.__class__}"
624
+ )
625
+ self._config = config
626
+
627
+ @property
628
+ def config(self) -> ConfigT:
629
+ return self._config
630
+
631
+ @classmethod
632
+ def from_kwargs(cls, **kwargs) -> "Configurable":
633
+ config = cls.ConfigT(**kwargs)
634
+ return cls(config)
635
+
636
+ def __init_subclass__(cls, **kwargs) -> None:
637
+ super().__init_subclass__(**kwargs)
638
+ # Don't add any classes whose config class is still a TypeVar to the registry
639
+ if not isinstance(cls.ConfigT, TypeVar) and issubclass(cls.ConfigT, Config):
640
+ AutoRecordsManager.add_to_records(cls)
641
+
642
+
643
+ class AutoRecordsManager:
644
+ CONFIGURABLE_CLS_PATH_TO_CONFIG_CLS: Dict[str, Type[Config]] = {}
645
+ CONFIGURABLE_CLS_PATH_TO_CONFIGURABLE_CLS: Dict[str, Type[Configurable]] = {}
646
+
647
+ @classmethod
648
+ def add_to_records(cls, ConfigurableT: Type[Configurable]): # noqa: N803
649
+ assert issubclass(ConfigurableT, Configurable), ConfigurableT
650
+
651
+ ConfigType: Type[Config] = ConfigurableT.ConfigT
652
+
653
+ configurable_class_path = f"{ConfigurableT.__module__}.{ConfigurableT.__qualname__}"
654
+
655
+ if configurable_class_path in cls.CONFIGURABLE_CLS_PATH_TO_CONFIG_CLS:
656
+ # Only print warning if running in interactive shell or notebook, to allow for re-executing cells
657
+ if is_interactive_py():
658
+ print(
659
+ f"WARNING: Duplicate registration of class {configurable_class_path}. Deleting old records"
660
+ )
661
+ else:
662
+ raise ValueError(f"Class {configurable_class_path} already registered. System Error.")
663
+
664
+ cls.CONFIGURABLE_CLS_PATH_TO_CONFIG_CLS[configurable_class_path] = ConfigType
665
+ cls.CONFIGURABLE_CLS_PATH_TO_CONFIGURABLE_CLS[configurable_class_path] = ConfigurableT
666
+
667
+ @classmethod
668
+ def config_cls_from_configurable_path(cls, configurable_class_path: str) -> Type[Config]:
669
+ if configurable_class_path == "" or "." not in configurable_class_path:
670
+ raise ValueError(
671
+ f"You need to provide the complete path to the target Configurable class, "
672
+ f"got '{configurable_class_path}'"
673
+ )
674
+
675
+ cls._maybe_import_class_from_module(configurable_class_path)
676
+
677
+ klass = cls.CONFIGURABLE_CLS_PATH_TO_CONFIG_CLS.get(configurable_class_path, None)
678
+
679
+ if klass is None:
680
+ expected_keys = list(cls.CONFIGURABLE_CLS_PATH_TO_CONFIG_CLS.keys())
681
+ raise ValueError(
682
+ f"AutoConfig does not recognize the class path: '{configurable_class_path}'. Expected one of the following:"
683
+ f"\n{pprint.pformat(expected_keys, indent=2)}\nTo enable AutoConfig initialization, make sure the "
684
+ f"target class path points to a class that inherits from Configurable or to a Config class that "
685
+ f"is provided as type argument to a Configurable. Also make sure the python module where "
686
+ f"the Configurable class is defined is actually imported in your program."
687
+ )
688
+ assert klass is not None # Help mypy
689
+ return klass
690
+
691
+ @classmethod
692
+ def configurable_cls_from_configurable_path(cls, configurable_class_path: str) -> Type[Configurable]:
693
+ if configurable_class_path == "" or "." not in configurable_class_path:
694
+ raise ValueError(
695
+ f"You need to provide the complete path to the target Configurable class, "
696
+ f"got '{configurable_class_path}'"
697
+ )
698
+
699
+ cls._maybe_import_class_from_module(configurable_class_path)
700
+
701
+ klass = cls.CONFIGURABLE_CLS_PATH_TO_CONFIGURABLE_CLS.get(configurable_class_path, None)
702
+
703
+ if klass is None:
704
+ expected_keys = list(cls.CONFIGURABLE_CLS_PATH_TO_CONFIGURABLE_CLS.keys())
705
+ raise ValueError(
706
+ f"AutoConfig does not recognize the class path: '{configurable_class_path}'. Expected one of the following:"
707
+ f"\n{pprint.pformat(expected_keys, indent=2)}\nTo enable AutoConfig initialization, make sure the "
708
+ f"target class path points to a class that inherits from Configurable or to a Config class that "
709
+ f"is provided as type argument to a Configurable. Also make sure the python module where "
710
+ f"the Configurable class is defined is actually imported in your program."
711
+ )
712
+ assert klass is not None # Help mypy
713
+ return klass
714
+
715
+ @classmethod
716
+ def configurable_cls_from_config(cls, config: Config) -> Type[Configurable]:
717
+ return cls.configurable_cls_from_configurable_path(config.autoclass)
718
+
719
+ @classmethod
720
+ def _maybe_import_class_from_module(cls, class_path: str) -> None:
721
+ """
722
+ Import a class using its full path. Useful when using YAML configs - allows for automatically
723
+ selecting Config / Configurable classes without explicitly importing them in the executable
724
+ script. If the Configurable class hasn't been imported, it won't be registered and Auto won't work
725
+ """
726
+ if class_path in cls.CONFIGURABLE_CLS_PATH_TO_CONFIGURABLE_CLS:
727
+ # Class already known and registered - no need to import
728
+ return
729
+
730
+ assert "." in class_path, class_path
731
+ module_path, class_name = class_path.rsplit(".", maxsplit=1)
732
+ try:
733
+ module = importlib.import_module(module_path)
734
+ except (ImportError, ModuleNotFoundError) as exc:
735
+ message = f"Can't import module {module_path}. Error: {exc}"
736
+ raise type(exc)(message) from exc
737
+
738
+ klass = getattr(module, class_name)
739
+
740
+ if not issubclass(klass, Configurable):
741
+ raise TypeError(f'Target class {class_path} must point to a subclass of Configurable')
742
+
743
+
744
+ def is_interactive_py() -> bool:
745
+ return hasattr(sys, 'ps1')
746
+
747
+
748
+ def _update_dict_of_maybe_configs(dict_1: Dict[str, Any], dict_2: Dict[str, Any]) -> Dict[str, Any]:
749
+ """
750
+ Updates dict_1 with dict_2. Supports Config as value
751
+ Wherever there are matching keys, if both values are convertible to dict, then conversion is
752
+ done and the dicts are merged. Otherwise, value_2 overwrites value_1
753
+
754
+ Example 1:
755
+ dict_1: {'a': 5, 'b': {'c': 6, 'd': 7}}
756
+ dict_2: {'b': {'e': 3}}
757
+ result: {'a': 5, 'b': {'c': 6, 'd': 7, 'e': 3}}
758
+ Example 2:
759
+ dict_1: {'a': 5, 'b': {'c': 6, 'd': 7}}
760
+ dict_2: {'b': {'d': {'e': 3}}}
761
+ result: {'a': 5, 'b': {'c': 6, 'd': {'e': 3}}}
762
+ """
763
+ dict_1 = dict(dict_1)
764
+ for key, value_2 in dict_2.items():
765
+ value_1: Any = dict_1.get(key, {})
766
+
767
+ # Convert Config -> Dict[str, Any]
768
+ if isinstance(value_1, Config):
769
+ value_1 = value_1.as_json()
770
+
771
+ # Convert Config -> Dict[str, Any]
772
+ if isinstance(value_2, Config):
773
+ value_2 = value_2.as_json()
774
+
775
+ if isinstance(value_1, dict) and isinstance(value_2, dict):
776
+ dict_1[key] = _update_dict_of_maybe_configs(value_1, value_2)
777
+ # If either of the values isn't a Dict, overwrite value_1 directly
778
+ else:
779
+ dict_1[key] = value_2
780
+ return dict_1
ladder/core/databib/config/config_iterables.py ADDED
@@ -0,0 +1,60 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from typing import Dict, List, Tuple, Type
2
+
3
+ # Import as modules to avoid potential circular import problems
4
+ import ladder.core.databib.config.auto_config as auto_config
5
+ from ladder.core.databib.dataclasses import DataclassDict, DataclassList
6
+ from ladder.core.databib.utils.typing_utils import value_type_is_annotation_type
7
+
8
+ def _auto_config_isinstance(value, field_type) -> bool:
9
+ """
10
+ Run type checks by also accounting for AutoConfig
11
+ """
12
+ # Check AutoConfig type
13
+ if issubclass(field_type, auto_config.AutoConfig):
14
+ return isinstance(value, field_type)
15
+ return type(value) is field_type
16
+
17
+
18
+ class ConfigDict(DataclassDict):
19
+ @classmethod
20
+ def _container_classes(cls) -> Tuple[Type, Type]:
21
+ return ConfigList, ConfigDict
22
+
23
+ def _check_value_types_at_runtime(self):
24
+ """Override to allow for AutoConfig checks"""
25
+ if value_type_is_annotation_type(self, Dict[str, self.ValueT], _auto_config_isinstance):
26
+ return
27
+ # Provide more informative error
28
+ for key, value in self.items():
29
+ if not value_type_is_annotation_type(
30
+ {key: value}, Dict[str, self.ValueT], _auto_config_isinstance
31
+ ):
32
+ raise TypeError(
33
+ f"Incorrect type provided for {self.__class__.__name__}: expected "
34
+ f"{self.ValueT}, but got {value} of type {type(value)} at key {key}"
35
+ )
36
+
37
+ def replace(self, strict: bool = False, **kwargs):
38
+ """
39
+ Overload to change the default value of strict.
40
+ In ConfigDict, adding new attributes is common behavior
41
+ """
42
+ return super().replace(strict=strict, **kwargs)
43
+
44
+
45
+ class ConfigList(DataclassList):
46
+ @classmethod
47
+ def _container_classes(cls) -> Tuple[Type, Type]:
48
+ return ConfigList, ConfigDict
49
+
50
+ def _check_value_types_at_runtime(self):
51
+ """Override to allow for AutoConfig checks"""
52
+ if value_type_is_annotation_type(self, List[self.ValueT], _auto_config_isinstance):
53
+ return
54
+ # Provide more informative error
55
+ for index, value in enumerate(self):
56
+ if not value_type_is_annotation_type([value], List[self.ValueT], _auto_config_isinstance):
57
+ raise TypeError(
58
+ f"Incorrect type provided for {self.__class__.__name__}: expected "
59
+ f"{self.ValueT}, but got {value} of type {type(value)} at index {index}"
60
+ )
ladder/core/databib/config/config_parser.py ADDED
@@ -0,0 +1,148 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import argparse
2
+ import ast
3
+ from typing import Any, Dict, Iterator, List, Optional, Tuple, Type
4
+
5
+ import yaml
6
+
7
+ from .config import Config
8
+ from .yaml_util import load_config, update_config_dict
9
+
10
+
11
+ class ConfigParser(argparse.ArgumentParser):
12
+ def __init__(self, config_class: Type[Config], config_path_key: Optional[str] = None):
13
+ super().__init__()
14
+ self.config_class = config_class
15
+ self.config_path_key = config_path_key
16
+ self.add_argument("--config", type=str, default=None)
17
+
18
+ def _process_known_args(self, known_args: Dict[str, Any]) -> Optional[str]:
19
+ config_path = known_args.pop('config', None)
20
+ return config_path
21
+
22
+ def _load_config(self, config_path: str) -> Dict[str, Any]:
23
+ config = load_config(config_path)
24
+
25
+ if self.config_path_key is not None:
26
+ config = assign_dict_value_by_recursive_access(config, self.config_path_key, config_path)
27
+
28
+ return config
29
+
30
+ @staticmethod
31
+ def _set_recursive_arg_value(args_dict: Dict[str, Any], arg_path: str, arg_value: Any) -> Dict[str, Any]:
32
+ """
33
+ Update a nested dictionary with a key and value in place
34
+ arg_path: Can be a nested path separated with `.`
35
+ """
36
+ # Cast value to the correct type
37
+ try:
38
+ value: Any = ast.literal_eval(arg_value)
39
+ except (ValueError, SyntaxError):
40
+ value = arg_value
41
+
42
+ name_path: List[str] = arg_path.split('.')
43
+ parents_path, base_name = name_path[:-1], name_path[-1]
44
+
45
+ base_dict = args_dict
46
+ for key in parents_path:
47
+ if key not in base_dict:
48
+ base_dict[key] = {}
49
+ base_dict = base_dict[key]
50
+ base_dict[base_name] = value
51
+
52
+ return args_dict
53
+
54
+ @staticmethod
55
+ def _extra_args_name_value_iter(extra_args: List[str]) -> Iterator[Tuple[str, Any]]:
56
+ names = set()
57
+ i = 0
58
+ while i < len(extra_args):
59
+ arg = extra_args[i]
60
+ if not arg.startswith('--'):
61
+ raise ValueError(
62
+ f"Expected argument starting with --, but got only {arg}. "
63
+ f"Argument specification should follow the syntax '--name value' or '--name=value'."
64
+ )
65
+
66
+ # Arg provided with syntax '--arg_name=value'
67
+ if '=' in arg:
68
+ data: List[str] = arg[2:].split('=')
69
+ if len(data) != 2:
70
+ raise ValueError(f"Argument name or value cannot contain '=', but got {arg}")
71
+
72
+ name, value = data[0], data[1]
73
+ i += 1
74
+
75
+ # Arg provided with syntax '--arg_name value'
76
+ else:
77
+ if i == len(extra_args) - 1 or extra_args[i + 1].startswith('--'):
78
+ raise ValueError(
79
+ f"No value provided for argument {arg[2:]}. Expected {arg} <value> or {arg}=<value>."
80
+ )
81
+
82
+ name, value = arg[2:], extra_args[i + 1]
83
+ i += 2
84
+
85
+ if name in names:
86
+ raise ValueError(f"Duplicate arguments provided for {name}")
87
+
88
+ names.add(name)
89
+
90
+ yield name, yaml.safe_load(value)
91
+
92
+ def _parse_cmdline_config_args(self, extra_args: List[str]) -> Dict[str, Any]:
93
+ cmdline_args: Dict[str, Any] = {}
94
+
95
+ for name, value in self._extra_args_name_value_iter(extra_args):
96
+ cmdline_args = self._set_recursive_arg_value(cmdline_args, name, value)
97
+
98
+ return cmdline_args
99
+
100
+ def _parse_args_to_dict(self, args=None, namespace=None) -> Dict[str, Any]:
101
+ parsed_args: Tuple[argparse.Namespace, List[str]] = super().parse_known_args(args, namespace)
102
+ known_args: dict = vars(parsed_args[0])
103
+ extra_args: List[str] = parsed_args[1]
104
+
105
+ config_path: Optional[str] = self._process_known_args(known_args)
106
+ if config_path is not None:
107
+ yml_args: Dict[str, Any] = self._load_config(config_path)
108
+ else:
109
+ yml_args = {}
110
+ cmdline_args: Dict[str, Any] = self._parse_cmdline_config_args(extra_args)
111
+ config_args: Dict[str, Any] = update_config_dict(yml_args, cmdline_args)
112
+
113
+ return config_args
114
+
115
+ def _parse_config(self, config_args: Dict[str, Any], config: Optional[Config] = None) -> Config:
116
+ if config is None:
117
+ return self.config_class(**config_args)
118
+ return config.replace(**config_args)
119
+
120
+ def _parse_args_to_config(self, args=None, namespace=None, config=None) -> Config:
121
+ config_args: Dict[str, Any] = self._parse_args_to_dict(args=args, namespace=namespace)
122
+ return self._parse_config(config_args, config)
123
+
124
+ def parse_args(self, args=None, namespace=None, config=None):
125
+ config = self._parse_args_to_config(args=args, namespace=namespace, config=config)
126
+ return config
127
+
128
+ def parse_args_to_dict(self, args=None, namespace=None) -> Dict[str, Any]:
129
+ """Parse config to a dict instead of a Config object"""
130
+ return self._parse_args_to_dict(args=args, namespace=namespace)
131
+
132
+ def parse_from_path(self, config_path: str) -> Config:
133
+ config_dict = self._load_config(config_path)
134
+ return self._parse_config(config_dict)
135
+
136
+
137
+ def assign_dict_value_by_recursive_access(data: Dict[str, Any], full_key: str, value: Any) -> Dict[str, Any]:
138
+ keys: List[str] = full_key.split('.')
139
+
140
+ inner_dict = data
141
+ for key in keys[:-1]:
142
+ if key not in inner_dict:
143
+ inner_dict[key] = {}
144
+ inner_dict = inner_dict[key]
145
+
146
+ inner_dict[keys[-1]] = value
147
+
148
+ return data
ladder/core/databib/config/yaml_util.py ADDED
@@ -0,0 +1,253 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import os
2
+ import pathlib
3
+ import re
4
+ from typing import Any, Dict, List, Optional, TextIO, Tuple, Union, cast
5
+
6
+ import yaml
7
+
8
+ # Type alias representing a config "dependency" tree (to trace which configs are imported)
9
+ ConfigImportTree = Dict[str, Any]
10
+
11
+
12
+ class _OverwriteDict(dict):
13
+ """A custom dict class that marks nodes that overwrite existing nodes."""
14
+
15
+ def __repr__(self):
16
+ return f"{self.__class__.__name__}({super().__repr__()})"
17
+
18
+
19
+ class _OverwriteList(list):
20
+ """A custom dict class that marks nodes that overwrite existing nodes."""
21
+
22
+ def __repr__(self):
23
+ return f"{self.__class__.__name__}({super().__repr__()})"
24
+
25
+
26
+ def load_config(config_path: Union[str, TextIO, pathlib.Path]) -> Dict[str, Any]:
27
+ config, _ = _load_raw_yaml_with_import_tree(config_path)
28
+ config = _expand_env_vars_recursive(config) # type: ignore[assignment]
29
+ config = _strip_overwrite_types(config) # type: ignore[assignment]
30
+ return config
31
+
32
+
33
+ def _strip_overwrite_types(config: Dict[str, Any] | List[Any] | Any) -> Dict[str, Any] | List[Any] | Any:
34
+ if isinstance(config, dict):
35
+ return {key: _strip_overwrite_types(value) for key, value in config.items()}
36
+ if isinstance(config, list):
37
+ return [_strip_overwrite_types(item) for item in config]
38
+ return config
39
+
40
+
41
+ def _expand_env_vars_recursive(node: Dict[str, Any] | List[Any] | Any) -> Dict[str, Any] | List[Any] | Any:
42
+ if isinstance(node, dict):
43
+ return type(node)({key: _expand_env_vars_recursive(value) for key, value in node.items()})
44
+ if isinstance(node, list):
45
+ return [_expand_env_vars_recursive(item) for item in node]
46
+ if isinstance(node, str):
47
+ return os.path.expandvars(node)
48
+ return node
49
+
50
+
51
+ def _merge_or_overwrite_value(
52
+ base_value: Dict[str, Any] | List[Any], merge_value: Dict[str, Any] | List[Any]
53
+ ) -> Dict[str, Any] | List[Any]:
54
+ """
55
+ Merge `base_value` and `merge_value` respecing the !overwrite tag, encoded as `_OverwriteDict` or
56
+ `_OverwriteList`. If merge_value is of type `_OverwriteDict` or `_OverwriteList`, completely overwrites
57
+ `base_value`. Otherwise merges `base_value` and `merge_value`
58
+ """
59
+ if isinstance(merge_value, (_OverwriteDict, _OverwriteList)):
60
+ return merge_value
61
+
62
+ # fmt: off
63
+ if (
64
+ isinstance(base_value, dict) != isinstance(merge_value, dict) or
65
+ isinstance(base_value, list) != isinstance(merge_value, list)
66
+ ):
67
+ raise TypeError(f"Can't merge entry {base_value} with entry {merge_value}")
68
+ # fmt: on
69
+
70
+ if isinstance(base_value, dict):
71
+ result = type(base_value)({key: value for key, value in base_value.items()})
72
+
73
+ for key, value in merge_value.items(): # type: ignore[union-attr]
74
+ # Overwrite local keys pointing to dict
75
+ if isinstance(value, _OverwriteDict):
76
+ result[key] = dict(value) # Convert _OverwriteDict to regular dict
77
+ # Overwrite local keys pointing to list
78
+ elif isinstance(value, _OverwriteList):
79
+ result[key] = list(value) # Convert _OverwriteList to regular list
80
+ # Merge nested dicts
81
+ elif isinstance(value, dict) and key in result:
82
+ if not isinstance(result[key], dict):
83
+ raise ValueError(
84
+ f"Cannot merge values for key {key} of types dict and {type(result[key])}"
85
+ )
86
+ result[key] = _merge_or_overwrite_value(result[key], value)
87
+ elif isinstance(value, list) and key in result:
88
+ if not isinstance(result[key], list):
89
+ raise ValueError(
90
+ f"Cannot merge values for key {key} of types list and {type(result[key])}"
91
+ )
92
+ # NOTE: We merge lists by direct appends
93
+ result[key] = [*result[key], *value]
94
+ else:
95
+ result[key] = value
96
+ elif isinstance(base_value, list):
97
+ result = type(base_value)([*base_value, *merge_value]) # type: ignore[assignment]
98
+ else:
99
+ result = merge_value
100
+
101
+ return result
102
+
103
+
104
+ def _load_raw_yaml_with_import_tree(
105
+ config_path: Union[str, TextIO, pathlib.Path]
106
+ ) -> Tuple[Dict[str, Any], ConfigImportTree]:
107
+ if isinstance(config_path, pathlib.Path):
108
+ config_path = str(config_path)
109
+
110
+ loader = _Loader(config_path)
111
+ try:
112
+ # Note: get_single_data() returns None for an empty config, we want an empty dict
113
+ config = loader.get_single_data() or {}
114
+ import_tree = loader.import_tree
115
+ return config, import_tree
116
+ finally:
117
+ loader.dispose()
118
+
119
+
120
+ def _ordered_dict_representer(dumper, data):
121
+ return yaml.nodes.MappingNode(
122
+ yaml.SafeDumper.DEFAULT_MAPPING_TAG,
123
+ [(dumper.represent_data(k), dumper.represent_data(v)) for k, v in data.items()],
124
+ )
125
+
126
+
127
+ class _Loader(yaml.SafeLoader):
128
+ config_path: Optional[str]
129
+
130
+ def __init__(self, config_path_or_file: Union[str, TextIO]):
131
+ if type(config_path_or_file) is str:
132
+ self.config_path = cast(str, config_path_or_file)
133
+ config_file = open(self.config_path, 'r')
134
+ else:
135
+ self.config_path = None
136
+ config_file = cast(TextIO, config_path_or_file) # type: ignore
137
+
138
+ super().__init__(config_file)
139
+
140
+ self.add_implicit_resolver(
141
+ 'tag:yaml.org,2002:float',
142
+ re.compile(
143
+ '''^(?:
144
+ [-+]?(?:[0-9][0-9_]*)\\.[0-9_]*(?:[eE][-+]?[0-9]+)?
145
+ |[-+]?(?:[0-9][0-9_]*)(?:[eE][-+]?[0-9]+)
146
+ |\\.[0-9_]+(?:[eE][-+][0-9]+)?
147
+ |[-+]?[0-9][0-9_]*(?::[0-5]?[0-9])+\\.[0-9_]*
148
+ |[-+]?\\.(?:inf|Inf|INF)
149
+ |\\.(?:nan|NaN|NAN))$''',
150
+ re.X,
151
+ ),
152
+ list('-+0123456789.'),
153
+ )
154
+
155
+ self.add_constructor(self.DEFAULT_MAPPING_TAG, self.mapping_constructor)
156
+ self.add_constructor('!overwrite', self.overwrite_constructor)
157
+
158
+ # Keep track of the !import dependency tree. Note that we only support importing when reading
159
+ # from a path on disk. !import doesn't work with file descripors or buffers
160
+ self._dep_tree: ConfigImportTree = {}
161
+
162
+ def overwrite_constructor(self, loader, node):
163
+ if isinstance(node, yaml.MappingNode):
164
+ return _OverwriteDict(loader.construct_mapping(node))
165
+ if isinstance(node, yaml.SequenceNode):
166
+ return _OverwriteList(loader.construct_sequence(node))
167
+ raise ValueError("Can only use `!overwrite` tag for dicts or lists")
168
+
169
+ @property
170
+ def import_tree(self) -> ConfigImportTree:
171
+ return self._dep_tree
172
+
173
+ @staticmethod
174
+ def mapping_constructor(loader, node):
175
+ # Everything here must go through ``loader``, never through the instance that registered this
176
+ # constructor: ``add_constructor`` registers on the Loader CLASS, so that instance is whichever
177
+ # loader was built LAST -- for a nested import, the imported file rather than the one being
178
+ # parsed. Resolving against it made a relative import land in the wrong directory whenever a
179
+ # file's first import pulled in a config from somewhere else, so a path that looked correct
180
+ # from its own location failed, and a wrong one could work by accident.
181
+ if not isinstance(node, yaml.nodes.MappingNode):
182
+ raise yaml.constructor.ConstructorError(
183
+ None, None, "expected a mapping node, but found %s" % node.id, node.start_mark
184
+ )
185
+
186
+ result = {}
187
+
188
+ for key_node, value_node in node.value:
189
+ key = loader.construct_object(key_node, deep=True)
190
+ value = loader.construct_object(value_node, deep=True)
191
+
192
+ if key == "import":
193
+ if loader.config_path is None:
194
+ raise ValueError('Can only use `!import` tag when loading from a path on disk')
195
+ import_path = os.path.join(os.path.dirname(loader.config_path), os.path.expandvars(value))
196
+ if not os.path.isfile(import_path):
197
+ raise FileNotFoundError(f'Cannot load referenced yaml at: {import_path}')
198
+
199
+ imported_config, imported_dep_tree = _load_raw_yaml_with_import_tree(import_path)
200
+ loader.merge_import_tree(import_path, imported_dep_tree)
201
+ # Merge the imported config immediately. Order of import and !overwrite matters:
202
+ # - `import` after `!overwrite` merges into `!overwrite`
203
+ # - `!overwrite` after `import` overwrites whatever is inside the `import`
204
+ result = _merge_or_overwrite_value(result, imported_config)
205
+ else:
206
+ if key not in result:
207
+ result[key] = value
208
+ else:
209
+ result[key] = _merge_or_overwrite_value(result[key], value)
210
+
211
+ return result
212
+
213
+ def merge_import_tree(self, import_path: str, imported_dep_tree: ConfigImportTree):
214
+ # Merge the imported dep tree with the existing one if that config was already imported.
215
+ self._dep_tree[import_path] = {
216
+ **self._dep_tree.get(import_path, {}),
217
+ **imported_dep_tree,
218
+ }
219
+
220
+ def dispose(self):
221
+ self.stream.close()
222
+ super().dispose()
223
+
224
+
225
+ def update_config_dict(dict_1: Dict[str, Any], dict_2: Dict[str, Any]) -> Dict[str, Any]:
226
+ """
227
+ Updates dict_1 with dict_2. Works for nested dictionaries.
228
+ If any value in dict_1 is not a dict, it cannot be replaced with a dict and vice-versa.
229
+ Example 1:
230
+ dict_1: {'a': 5, 'b': {'c': 6, 'd': 7}}
231
+ dict_2: {'b': {'e': 3}}
232
+ result: {'a': 5, 'b': {'c': 6, 'd': 7, 'e': 3}}
233
+ Example 2:
234
+ dict_1: {'a': 5, 'b': {'c': 6, 'd': 7}}
235
+ dict_2: {'b': {'d': {'e': 3}}}
236
+ result: Error: int cannot be replaced by a dict
237
+ """
238
+ dict_1 = dict(dict_1)
239
+ for key, value in dict_2.items():
240
+ if isinstance(value, dict):
241
+ source_value = dict_1.get(key, {})
242
+ if not isinstance(source_value, dict):
243
+ raise TypeError(
244
+ f'Updating {source_value} of type {type(source_value)} with a dict {value} is not allowed.'
245
+ )
246
+ dict_1[key] = update_config_dict(source_value, value)
247
+ else:
248
+ if isinstance(dict_1.get(key, None), dict):
249
+ raise TypeError(
250
+ f'Updating {dict_1.get(key)} of type dict with {value} of type {type(value)} is not allowed.'
251
+ )
252
+ dict_1[key] = value
253
+ return dict_1
ladder/core/databib/dataclasses/__init__.py ADDED
@@ -0,0 +1,16 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from .dataclass import Dataclass, DataclassMeta, DataclassT, dataclass
2
+ from .dataclass_dict import DataclassDict
3
+ from .dataclass_interface import DataclassInterface
4
+ from .dataclass_list import DataclassList
5
+ from .dataclass_utils import zip_dataclass_items
6
+
7
+ __all__ = [
8
+ 'dataclass',
9
+ 'Dataclass',
10
+ 'DataclassT',
11
+ 'DataclassDict',
12
+ 'DataclassInterface',
13
+ 'DataclassList',
14
+ 'DataclassMeta',
15
+ 'zip_dataclass_items',
16
+ ]
ladder/core/databib/dataclasses/dataclass.py ADDED
@@ -0,0 +1,391 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import collections
2
+ import dataclasses
3
+ import enum
4
+ import inspect
5
+ from abc import ABCMeta
6
+ from typing import Any, Callable, ClassVar, Dict, List, Type, TypeVar, Union
7
+
8
+ import numpy as np
9
+ from frozendict import frozendict
10
+
11
+ try:
12
+ import torch
13
+ except ImportError:
14
+ # Don't explicitly depend on torch, it's optional
15
+ torch = type('', (), {"Tensor": np.ndarray})()
16
+
17
+ from ladder.core.databib.dataclasses.dataclass_dict import DataclassDict
18
+ from ladder.core.databib.dataclasses.dataclass_interface import DataclassInterface
19
+ from ladder.core.databib.dataclasses.dataclass_list import DataclassList
20
+ from ladder.core.databib.dataclasses.dataclass_utils import maybe_chained_keys_to_nested_dict
21
+ from ladder.core.databib.utils.classproperty import cached_classproperty
22
+ from ladder.core.databib.utils.typing_utils import (
23
+ ITERABLE_TYPES,
24
+ annotation_is_dict,
25
+ annotation_is_list,
26
+ annotation_is_tuple,
27
+ annotation_is_union,
28
+ get_annotation_type_args,
29
+ get_dict_annotation_type_args,
30
+ get_list_annotation_type_args,
31
+ get_maybe_optional_type,
32
+ get_origin_type,
33
+ value_type_is_annotation_type,
34
+ )
35
+
36
+ DataclassT = TypeVar("DataclassT", bound="Dataclass")
37
+
38
+
39
+ def dataclass(cls: Type[DataclassT], **kwargs) -> Type[DataclassT]:
40
+ cls = dataclasses.dataclass(cls, frozen=True, repr=False, kw_only=True, **kwargs) # type: ignore[call-overload]
41
+ _prevent_forbidden_type_annotations(cls)
42
+ return cls
43
+
44
+
45
+ def _prevent_forbidden_type_annotations(cls):
46
+ """This cannot be added in a metaclass since __dataclass_fields__ does not exist when the metaclass is called"""
47
+ for field in getattr(cls, "__dataclass_fields__", {}).values():
48
+ field_type = get_maybe_optional_type(field.type)
49
+
50
+ # Forbid Union or Tuple with any member of type
51
+ # [DataclassInterface, Dict, List, Set, Tuple, TypeVar, Union, Optional]
52
+ if annotation_is_union(field_type) or annotation_is_tuple(field_type):
53
+ type_args = get_annotation_type_args(field_type)
54
+ for arg in type_args:
55
+ if (
56
+ (inspect.isclass(arg) and issubclass(arg, DataclassInterface))
57
+ or get_origin_type(arg) in ITERABLE_TYPES + (Union,)
58
+ or isinstance(arg, TypeVar)
59
+ ):
60
+ etype = 'Union' if annotation_is_union(field_type) else 'Tuple'
61
+ raise TypeError(
62
+ f"Class {cls} has field {field.name}: {field.type}, but {etype} with members of type "
63
+ f"DataclassInterface, Dict, List, Set, Tuple, Sequence, Union, Optional, TypeVar "
64
+ f"are unsafe and not allowed. Remove the Union instead."
65
+ )
66
+ continue
67
+ if annotation_is_dict(field_type) or annotation_is_list(field_type):
68
+ # Annotation type checks will be run by cls.types below
69
+ continue
70
+ # Forbid non-class type annotations
71
+ if (
72
+ not inspect.isclass(field_type)
73
+ and not isinstance(field_type, dataclasses.InitVar)
74
+ and field_type is not dataclasses.InitVar
75
+ and getattr(field_type, "__origin__", None) is not ClassVar
76
+ ):
77
+ raise TypeError(
78
+ f"Forbidden type annotation in {cls} for field '{field.name}: {field.type}'. "
79
+ f"Expected a class, Optional[class], Dict, List, Tuple or Union"
80
+ )
81
+
82
+
83
+ class DataclassMeta(ABCMeta):
84
+ def __new__(mcs, name, bases, attributes, *args, **kwargs): # noqa: N804
85
+ new_cls = super().__new__(mcs, name, bases, attributes, *args, **kwargs)
86
+ new_cls._define_dict_and_list_attribute_classes() # noqa: SLF001
87
+ return new_cls
88
+
89
+ def _define_dict_and_list_attribute_classes(cls): # noqa: N805
90
+ """
91
+ [IMPORTANT]: Suppose we have a dataclass
92
+ ```
93
+ @dataclass
94
+ class MyDataclass(Dataclass):
95
+ my_field: Dict[str, int]
96
+ ```
97
+ The values for my_field will always be cast to `DataclassDict[int]` inside `Dataclass.__init__()`
98
+ However, the type `DataclassDict[int]` doesn't exist before we try to create an instance of
99
+ `MyDataclass`. This is problematic because:
100
+ 1. We cannot properly unpickle such classes when using multiprocessing. In particular, the
101
+ class `MyDataclass` will be known to the subprocess since the class will be imported.
102
+ However, `DataclassDict[int]` will be undefined, since the subprocess hasn't created
103
+ an instance of `MyDataclass` before it tries to unpickle it
104
+ 2. If the types inside `Dict` are not allowed in `DataclassDict`, error will be raised only
105
+ when we try to create an instance, instead of at class definition time
106
+ To resolve these problems, here we define all the equivalent `DataclassDict` and `DataclassList`
107
+ classes needed for the new dataclass attributes
108
+ """
109
+
110
+ # NOTE: At this point, @dataclass hasn't been applied yet, so `__dataclass_fields__` is not the
111
+ # absolute source of truth for dataclass attributes. `__annotations__` gives us the fields added in
112
+ # this class definition, while `__dataclass_fields__` gives us the fields defined by the parents.
113
+ # We check both to also cover any transitive updates on parent class attributes, e.g. if
114
+ # called by `__getitem__`
115
+ annotations = getattr(cls, '__annotations__', {})
116
+ dataclass_fields = getattr(cls, '__dataclass_fields__', {})
117
+ fields = {**annotations, **{field.name: field.type for field in dataclass_fields.values()}}
118
+
119
+ # Note that we check only direct attribute types and don't recurse, e.g. into something like
120
+ # `Dict[str, List[str]]`. For now, we care only about the dataclass field type and cast only that
121
+ for field_name, field_type in fields.items():
122
+ if annotation_is_dict(field_type):
123
+ _, DValueT = get_dict_annotation_type_args(field_type)
124
+ try:
125
+ DataclassDict[DValueT]
126
+ except TypeError as exc:
127
+ # Provide more informative error message when DValueT not allowed
128
+ message = f"Cannot cast {cls.__name__}.{field_name} to DataclassDict[{DValueT}].\n{exc}"
129
+ raise TypeError(message) from exc
130
+ if annotation_is_list(field_type):
131
+ LValueT: Type = get_list_annotation_type_args(field_type)[0]
132
+ try:
133
+ DataclassList[LValueT]
134
+ except TypeError as exc:
135
+ # Provide more informative error message when DValueT not allowed
136
+ message = f"Cannot cast {cls.__name__}.{field_name} to DataclassList[{LValueT}].\n{exc}"
137
+ raise TypeError(message) from exc
138
+
139
+
140
+ @dataclass
141
+ class Dataclass(DataclassInterface, metaclass=DataclassMeta):
142
+ def __post_init__(self):
143
+ self._cast_dict_and_list_attrs()
144
+ self._make_type_checks()
145
+
146
+ def _cast_dict_and_list_attrs(self):
147
+ """
148
+ Cast attributes of type Dict or List to their corresponding DataclassDict and DataclassList types
149
+ """
150
+ for field_name, field_type in self._cast_fields.items():
151
+ value = getattr(self, field_name)
152
+ if type(value) is field_type:
153
+ continue
154
+ try:
155
+ object.__setattr__(self, field_name, field_type(value))
156
+ except TypeError:
157
+ # Let self._make_type_checks() raise a more informative error
158
+ pass
159
+
160
+ def _make_type_checks(self):
161
+ for field_name, field_type in self.types.items():
162
+ value = getattr(self, field_name)
163
+
164
+ if (
165
+ value is None
166
+ and inspect.isclass(field_type)
167
+ and not issubclass(field_type, DataclassInterface)
168
+ ):
169
+ # Here we allow None for any field which is not a subclass of DataclassInterface.
170
+ # Technically, proper type checks should forbid any None value for non-Optional fields,
171
+ # but this is required for Dataclass.make_empty() to work in general.
172
+ # TODO: Figure out how to resolve this predicament in general
173
+ continue
174
+
175
+ if not value_type_is_annotation_type(value, field_type):
176
+ raise TypeError(
177
+ f"Incorrect type provided for {self.__class__.__name__}.{field_name}: "
178
+ f"expected {self.types[field_name]}, but got value {value} with type {type(value)}"
179
+ )
180
+
181
+ @cached_classproperty
182
+ def fields(cls) -> Dict[str, dataclasses.Field]: # noqa: N805
183
+ # pylint: disable=no-self-argument
184
+ """Returns a frozendict of the Field objects, keyed and sorted by field name"""
185
+ return frozendict({f.name: f for f in sorted(dataclasses.fields(cls), key=lambda x: x.name)})
186
+
187
+ @cached_classproperty
188
+ def annotated_types(cls) -> Dict[str, type]: # noqa: N805
189
+ # pylint: disable=no-self-argument
190
+ return frozendict({name: f.type for name, f in cls.fields.items()})
191
+
192
+ @cached_classproperty
193
+ def types(cls) -> Dict[str, type]: # noqa: N805
194
+ # pylint: disable=no-self-argument
195
+ return frozendict({name: cls._cast_fields.get(name, f.type) for name, f in cls.fields.items()})
196
+
197
+ @cached_classproperty
198
+ def _cast_fields(cls) -> Dict[str, Type[DataclassInterface]]: # noqa: N805
199
+ """
200
+ Returns a frozendict containing only the fields annotated as Dict and List in this `Dataclass`
201
+ and their equivalent `DataclassDict` and `DataclassList` types that values should be cast to.
202
+ Note that DataclassMeta already ensures that all Dict and List annotations can be cast.
203
+ """
204
+ # pylint: disable=no-self-argument
205
+ cast_fields: Dict[str, Type[DataclassInterface]] = {}
206
+ for field in cls.fields.values():
207
+ if annotation_is_dict(field.type):
208
+ _, DValueT = get_dict_annotation_type_args(field.type)
209
+ cast_fields[field.name] = DataclassDict[DValueT] # type: ignore[valid-type]
210
+ if annotation_is_list(field.type):
211
+ LValueT: Type = get_list_annotation_type_args(field.type)[0]
212
+ cast_fields[field.name] = DataclassList[LValueT] # type: ignore[valid-type]
213
+ return frozendict(cast_fields)
214
+
215
+ @classmethod
216
+ def keys(cls) -> List[str]:
217
+ return list(cls.fields)
218
+
219
+ @classmethod
220
+ def from_subclass(cls: Type[DataclassT], subclass_instance: DataclassT) -> DataclassT:
221
+ """Returns an instance of DataclassT, with all subclass properties removed"""
222
+ if not isinstance(subclass_instance, cls):
223
+ raise TypeError(
224
+ f"from_subclass expected an instance of (a subclass of) {cls.__name__}, "
225
+ f"but got {subclass_instance.__class__.__name__}"
226
+ )
227
+ return cls.from_json(
228
+ subclass_instance.as_json(recursive=False), recursive=False, ignore_redundant=True
229
+ )
230
+
231
+ @classmethod
232
+ def from_json(cls, data: Dict[str, Any], recursive: bool = True, ignore_redundant: bool = False):
233
+ """Parses a dict to dataclass object"""
234
+ if not isinstance(data, collections.abc.Mapping):
235
+ raise TypeError(
236
+ f"{cls}.from_json() expects input of type dict, but got input of type {type(data)}"
237
+ )
238
+ data = dict(data)
239
+
240
+ if ignore_redundant:
241
+ data = cls._ignore_redundant_keys(data)
242
+
243
+ if recursive:
244
+ for key, value in data.items():
245
+ field_type = cls.types.get(key, None)
246
+ if field_type is None:
247
+ # This key is not part of the dataclass fields. Leave it as is.
248
+ # Dataclass.__init__() will raise error
249
+ continue
250
+ field_type = get_maybe_optional_type(field_type)
251
+ # If the field annotation is not a class, let the __new__ method deal with it
252
+ if not inspect.isclass(field_type):
253
+ continue
254
+ # If field is an Enum, convert it to the right type
255
+ if issubclass(field_type, enum.Enum):
256
+ data[key] = field_type(value)
257
+ if issubclass(field_type, DataclassInterface) and value is not None:
258
+ data[key] = field_type.from_json(
259
+ value, recursive=recursive, ignore_redundant=ignore_redundant
260
+ )
261
+
262
+ return cls(**data)
263
+
264
+ @classmethod
265
+ def _ignore_redundant_keys(cls, data: dict) -> dict:
266
+ return {key: value for key, value in data.items() if key in cls.types}
267
+
268
+ @classmethod
269
+ def from_dict(cls, d: dict, recursive: bool = True, ignore_redundant: bool = False):
270
+ return cls.from_json(d, recursive, ignore_redundant)
271
+
272
+ @classmethod
273
+ def make_empty(cls: Type[DataclassT]) -> DataclassT:
274
+ return cls(
275
+ **{
276
+ k: v.make_empty() if inspect.isclass(v) and issubclass(v, DataclassInterface) else None
277
+ for k, v in cls.types.items()
278
+ }
279
+ )
280
+
281
+ @property
282
+ def is_empty(self) -> bool:
283
+ for value in self.values():
284
+ if isinstance(value, DataclassInterface):
285
+ if not value.is_empty:
286
+ return False
287
+ elif value is not None:
288
+ return False
289
+ return True
290
+
291
+ def as_json(self, recursive: bool = True) -> dict:
292
+ return {
293
+ k: v.as_json() if isinstance(v, DataclassInterface) and recursive else v for k, v in self.items()
294
+ }
295
+
296
+ def as_dict(self, recursive: bool = True) -> dict:
297
+ # cannot use the inbuilt asdict methods as they do a deepcopy of tensors
298
+ return self.as_json(recursive=recursive)
299
+
300
+ def values(self):
301
+ return [getattr(self, name) for name in self.fields]
302
+
303
+ def items(self, recursive: bool = False):
304
+ for key, value in zip(self.keys(), self.values(), strict=True):
305
+ if recursive and isinstance(value, DataclassInterface):
306
+ for subkey, subvalue in value.items(recursive=True):
307
+ yield f"{key}.{subkey}", subvalue
308
+ else:
309
+ yield key, value
310
+
311
+ def getattr(self, name: str) -> Any:
312
+ """
313
+ Recursive counterpart of the builtin getattr(): `name` can address an attribute of a nested
314
+ dataclass via dot-separation, e.g. 'nested_field.attr'
315
+ """
316
+ value = self
317
+ for attr in name.split("."):
318
+ # Method names are not in scope inside the method body, so this is the builtin getattr()
319
+ value = getattr(value, attr)
320
+ return value
321
+
322
+ def replace(self, **kwargs):
323
+ """
324
+ Return a new instance of Dataclass with the kwargs overwritten.
325
+ """
326
+ kwargs = maybe_chained_keys_to_nested_dict(kwargs)
327
+
328
+ data = self.as_dict(recursive=False)
329
+
330
+ for key, value in kwargs.items():
331
+ if key not in self.types:
332
+ raise KeyError(f"Dataclass {self.__class__} does not have a field {key}")
333
+
334
+ value_type = self.types[key]
335
+ value_type = get_maybe_optional_type(value_type)
336
+
337
+ # Recurse if a DataclassInterface field
338
+ if inspect.isclass(value_type) and issubclass(value_type, DataclassInterface):
339
+ if isinstance(value, dict):
340
+ data[key] = data[key].replace(**value)
341
+ else:
342
+ # If the type is incorrect, delegate to __init__ to handle it
343
+ data[key] = value
344
+ else:
345
+ data[key] = value
346
+
347
+ return self.__class__(**data)
348
+
349
+ def apply(self, fcn: Callable, recursive: bool = True, skip_nones: bool = False):
350
+ def fcn_wrapper(value: Any) -> Any:
351
+ if value is None and skip_nones:
352
+ return None
353
+ if isinstance(value, DataclassInterface) and recursive:
354
+ return value.apply(fcn, recursive=True, skip_nones=skip_nones)
355
+ return fcn(value)
356
+
357
+ return self.__class__(**{key: fcn_wrapper(value) for key, value in self.items()})
358
+
359
+ def __iter__(self):
360
+ for name in self.fields:
361
+ field_value = getattr(self, name)
362
+ if isinstance(field_value, DataclassDict):
363
+ for value in field_value.values():
364
+ yield value
365
+ elif isinstance(field_value, DataclassInterface):
366
+ for value in field_value:
367
+ yield value
368
+ else:
369
+ yield field_value
370
+
371
+ def shape_repr(self, indent: int = 0, skip_empty=True) -> str:
372
+ DEFAULT_INDENT = 2
373
+ indent_str = " " * indent
374
+ field_indent_str = " " * (indent + DEFAULT_INDENT)
375
+ shape_strings = []
376
+
377
+ if self.is_empty and skip_empty:
378
+ return f"{indent_str}{self.__class__.__name__}.empty()"
379
+
380
+ for key, value in self.items():
381
+ if value is None:
382
+ shape_strings.append(f"{field_indent_str}{key}: None")
383
+ elif isinstance(value, Dataclass):
384
+ dataclass_repr = value.shape_repr(indent + DEFAULT_INDENT, skip_empty).strip()
385
+ shape_strings.append(f"{field_indent_str}{key}: {dataclass_repr}")
386
+ elif isinstance(value, (np.ndarray, torch.Tensor)):
387
+ shape_strings.append(f"{field_indent_str}{key}: {list(value.shape)}")
388
+ else:
389
+ shape_strings.append(f"{field_indent_str}{key}: -X-")
390
+
391
+ return f"{indent_str}{self.__class__.__name__}(\n" + ",\n".join(shape_strings) + f",\n{indent_str})"
ladder/core/databib/dataclasses/dataclass_dict.py ADDED
@@ -0,0 +1,192 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import functools
2
+ import inspect
3
+ import sys
4
+ from abc import ABCMeta
5
+ from typing import Any, Callable, Dict, Tuple, Type, TypeVar
6
+
7
+ from frozendict import frozendict
8
+
9
+ from ladder.core.databib.dataclasses.dataclass_interface import DataclassInterface
10
+ from ladder.core.databib.dataclasses.dataclass_utils import parametrize
11
+ from ladder.core.databib.utils.typing_utils import (
12
+ cast_container_types,
13
+ get_maybe_optional_type,
14
+ substitute_annotation_container_types,
15
+ type_annotation_contains_type_var,
16
+ value_type_is_annotation_type,
17
+ )
18
+
19
+ ValueT = TypeVar("ValueT")
20
+ DataclassDictT = TypeVar("DataclassDictT", bound="DataclassDict")
21
+
22
+
23
+ class DataclassDictMeta(ABCMeta):
24
+ @functools.lru_cache(maxsize=None, typed=True) # noqa: B019
25
+ def __getitem__(cls, value_type): # noqa: N805
26
+ if not isinstance(cls.ValueT, TypeVar):
27
+ raise TypeError(f"{cls.__name__} already has a value type")
28
+ # Substitute nested List / Dict in the value type with their DataclassList / DataclassDict
29
+ # equivalents (ConfigList / ConfigDict for the Config variants)
30
+ ListType, DictType = cls._container_classes()
31
+ value_type = substitute_annotation_container_types(value_type, ListType, DictType)
32
+ new_cls = parametrize(cls, (value_type,), ValueT=value_type)
33
+ new_cls._raise_on_forbidden_value_type() # noqa: SLF001
34
+ return new_cls
35
+
36
+ def _raise_on_forbidden_value_type(cls): # noqa: N805
37
+ assert cls.ValueT is not Ellipsis
38
+
39
+ if isinstance(get_maybe_optional_type(cls.ValueT), TypeVar):
40
+ return
41
+
42
+ if type_annotation_contains_type_var(cls.ValueT):
43
+ raise TypeError(f"TypeVar annotation allowed only directly or Optional[TypeVar], but got {cls}")
44
+
45
+
46
+ class DataclassDict(DataclassInterface, frozendict, metaclass=DataclassDictMeta):
47
+ """
48
+ Immutable Dict container compatible with DataclassInterface API.
49
+ Assumes key type is always a str. Value type provided at runtime.
50
+
51
+ Allowed value type annotations (including nested versions of these):
52
+ Any, Dict, List, Optional, Tuple, Union
53
+ TypeVar annotation is also allowed, but it can't be nested under any of the above containers
54
+ """
55
+
56
+ ValueT = ValueT # a TypeVar until the class is subscripted, e.g. DataclassDict[int]
57
+
58
+
59
+ @classmethod
60
+ def _container_classes(cls) -> Tuple[Type, Type]:
61
+ """The (ListType, DictType) pair nested containers are cast to. Overridden by ConfigDict."""
62
+ from ladder.core.databib.dataclasses.dataclass_list import DataclassList
63
+
64
+ return DataclassList, DataclassDict
65
+
66
+ def __new__(cls, *args, **kwargs):
67
+ values = frozendict(*args, **kwargs)
68
+ # Cast value to Dict[cls.ValueT] (note that ValueT already has plain Dict/Dict container types
69
+ # substituted with their DataclassList / DataclassDict equivalents).
70
+ # NOTE: We cast the outer container to a python list instead of DataclassDict to avoid infinite
71
+ # recursion since we are in DataclassDict.__new__. super().__new__() will cast the outer container
72
+ values = cast_container_types(values, Dict[str, cls.ValueT])
73
+ return super().__new__(cls, values)
74
+
75
+ def __init__(self, *args, **kwargs):
76
+ del args, kwargs
77
+ # NOTE: frozendict gets auto initialized in __new__. No need to call here
78
+ DataclassInterface.__init__(self)
79
+ self._check_value_types_at_runtime()
80
+
81
+ def _check_value_types_at_runtime(self):
82
+ if value_type_is_annotation_type(self, Dict[str, self.ValueT]):
83
+ return
84
+ # Provide more informative error
85
+ for key, value in self.items():
86
+ if not value_type_is_annotation_type({key: value}, Dict[str, self.ValueT]):
87
+ raise TypeError(
88
+ f"Incorrect type provided for {self.__class__.__name__}: expected "
89
+ f"{self.ValueT}, but got {value} of type {type(value)} at key {key}"
90
+ )
91
+
92
+ @classmethod
93
+ def from_json(
94
+ cls, data: Dict[str, Any], recursive: bool = True, ignore_redundant: bool = False
95
+ ) -> "DataclassDict[ValueT]":
96
+ if not isinstance(data, dict):
97
+ raise TypeError(
98
+ f"{cls}.from_json() expects input of type dict, but got input of type {type(data)}"
99
+ )
100
+ data = dict(data)
101
+
102
+ if recursive and inspect.isclass(cls.ValueT) and issubclass(cls.ValueT, DataclassInterface):
103
+ data = {
104
+ key: cls.ValueT.from_json(value, recursive=recursive, ignore_redundant=ignore_redundant)
105
+ for key, value in data.items()
106
+ }
107
+
108
+ return cls(**data)
109
+
110
+ def as_json(self, recursive: bool = True) -> Dict[str, Any]:
111
+ return {
112
+ key: value.as_json() if isinstance(value, DataclassInterface) and recursive else value
113
+ for key, value in self.items()
114
+ }
115
+
116
+ @classmethod
117
+ def make_empty(cls: Type[DataclassDictT]) -> DataclassDictT:
118
+ return cls()
119
+
120
+ @property
121
+ def is_empty(self) -> bool:
122
+ return len(self) == 0
123
+
124
+ def items(self, recursive: bool = False):
125
+ for key in self.keys():
126
+ value = self[key]
127
+ if recursive and isinstance(value, DataclassInterface):
128
+ for subkey, subvalue in value.items(recursive=True):
129
+ yield f"{key}.{subkey}", subvalue
130
+ else:
131
+ yield key, value
132
+
133
+ def replace(self, strict=False, **kwargs) -> "DataclassDict[ValueT]":
134
+ """If strict, no new keys allowed, only existing values can be replaced"""
135
+ extra_keys = kwargs.keys() - self.keys()
136
+ if strict and len(extra_keys) > 0:
137
+ raise KeyError(f"Unexpected extra keys: {extra_keys}")
138
+
139
+ data = {**self}
140
+
141
+ for key, value in kwargs.items():
142
+ # Recurse if ValueT is a DataclassInterface field
143
+ if inspect.isclass(self.ValueT) and issubclass(self.ValueT, DataclassInterface):
144
+ # Case 1: value is already the correct type, just assign it
145
+ if isinstance(value, self.ValueT):
146
+ data[key] = value
147
+ # Case 2: value is a plain dict representing the dataclass
148
+ elif isinstance(value, dict):
149
+ # Case 2.1: new key being added to the dataclass -> cast to ValueT
150
+ if key in extra_keys:
151
+ data[key] = self.ValueT(**value)
152
+ # Case 2.2: existing key being updated -> call replace() on the current instance
153
+ else:
154
+ data[key] = data[key].replace(**value)
155
+ # Case 3: value is some other type - delegate to __init__ to cast or raise error
156
+ else:
157
+ data[key] = value
158
+ else:
159
+ data[key] = value
160
+
161
+ return self.__class__(**data)
162
+
163
+ def apply(
164
+ self, fcn: Callable, recursive: bool = True, skip_nones: bool = False
165
+ ) -> "DataclassDict[ValueT]":
166
+ def fcn_wrapper(v: Any) -> Any:
167
+ if v is None and skip_nones:
168
+ return None
169
+ if isinstance(v, DataclassInterface) and recursive:
170
+ return v.apply(fcn, recursive=True, skip_nones=skip_nones)
171
+ return fcn(v)
172
+
173
+ return self.__class__(**{k: fcn_wrapper(v) for k, v in self.items()})
174
+
175
+ def __reduce__(self) -> Tuple[Callable, Tuple[Any, ...], Dict[str, Any]]:
176
+ """
177
+ Needed so we properly support pickling for classes with square brackets in their names.
178
+
179
+ A subscripted class such as `DataclassDict[typing.Any]` is created at runtime and registered on
180
+ its module under that name (`dataclass_utils.parametrize`). pickle cannot look such a name up
181
+ itself, so this returns (callable, args, state): `get_dynamic_class` finds the class by name and
182
+ rebuilds the object from its JSON form, and `state` is passed to __setstate__ afterwards.
183
+ """
184
+ return (
185
+ get_dynamic_class,
186
+ (self.__class__.__module__, self.__class__.__name__, self.as_json()),
187
+ self.__dict__,
188
+ )
189
+
190
+
191
+ def get_dynamic_class(module_name: str, classname: str, data: Dict[str, Any]):
192
+ return getattr(sys.modules[module_name], classname).from_json(data)
ladder/core/databib/dataclasses/dataclass_interface.py ADDED
@@ -0,0 +1,46 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import abc
2
+ from typing import Any, Callable, Iterator, Tuple, Union
3
+
4
+
5
+ class DataclassInterface(abc.ABC):
6
+ """
7
+ Interface for dataclasses and the supported methods.
8
+ All dataclasses are immutable and all methods return new instances.
9
+ """
10
+
11
+ @classmethod
12
+ @abc.abstractmethod
13
+ def from_json(cls, data, recursive: bool = True, ignore_redundant: bool = False):
14
+ pass
15
+
16
+ @classmethod
17
+ @abc.abstractmethod
18
+ def make_empty(cls):
19
+ pass
20
+
21
+ @abc.abstractmethod
22
+ def as_json(self, recursive: bool = True) -> Union[dict, list]:
23
+ pass
24
+
25
+ @abc.abstractmethod
26
+ def replace(self, **kwargs):
27
+ """Returns a new instance of the dataclass with the given fields replaced by the given values"""
28
+
29
+ @abc.abstractmethod
30
+ def apply(self, fcn: Callable, recursive: bool = True, skip_nones: bool = False):
31
+ pass
32
+
33
+ @abc.abstractmethod
34
+ def items(self, recursive: bool = False) -> Iterator[Tuple[str, Any]]:
35
+ pass
36
+
37
+ def __repr__(self) -> str:
38
+ indent = " " * 2
39
+
40
+ fields_reprs = [
41
+ f"{indent}{key}={repr(value)}".replace('\n', f'\n{indent}')
42
+ for key, value in self.items(recursive=False)
43
+ ]
44
+ fields_repr = ("\n" + ",\n".join(fields_reprs) + f",\n") if len(fields_reprs) > 0 else ""
45
+
46
+ return f"{self.__class__.__name__}({fields_repr})"
ladder/core/databib/dataclasses/dataclass_list.py ADDED
@@ -0,0 +1,171 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import functools
2
+ import inspect
3
+ import sys
4
+ from abc import ABCMeta
5
+ from typing import Any, Callable, Dict, List, Sequence, Tuple, Type, TypeVar
6
+
7
+ from ladder.core.databib.dataclasses.dataclass_interface import DataclassInterface
8
+ from ladder.core.databib.dataclasses.dataclass_utils import parametrize
9
+ from ladder.core.databib.utils.typing_utils import (
10
+ cast_container_types,
11
+ get_maybe_optional_type,
12
+ substitute_annotation_container_types,
13
+ type_annotation_contains_type_var,
14
+ value_type_is_annotation_type,
15
+ )
16
+
17
+ ValueT = TypeVar("ValueT")
18
+ DataclassListT = TypeVar("DataclassListT", bound="DataclassList")
19
+
20
+
21
+ class DataclassListMeta(ABCMeta):
22
+ @functools.lru_cache(maxsize=None, typed=True) # noqa: B019
23
+ def __getitem__(cls, value_type): # noqa: N805
24
+ if not isinstance(cls.ValueT, TypeVar):
25
+ raise TypeError(f"{cls.__name__} already has a value type")
26
+ # Substitute nested List / Dict in the value type with their DataclassList / DataclassDict
27
+ # equivalents (ConfigList / ConfigDict for the Config variants)
28
+ ListType, DictType = cls._container_classes()
29
+ value_type = substitute_annotation_container_types(value_type, ListType, DictType)
30
+ new_cls = parametrize(cls, (value_type,), ValueT=value_type)
31
+ new_cls._raise_on_forbidden_value_type() # noqa: SLF001
32
+ return new_cls
33
+
34
+ def _raise_on_forbidden_value_type(cls): # noqa: N805
35
+ assert cls.ValueT is not Ellipsis
36
+
37
+ if isinstance(get_maybe_optional_type(cls.ValueT), TypeVar):
38
+ return
39
+
40
+ if type_annotation_contains_type_var(cls.ValueT):
41
+ raise TypeError(f"TypeVar annotation allowed only directly or Optional[TypeVar], but got {cls}")
42
+
43
+
44
+ class DataclassList(DataclassInterface, tuple, metaclass=DataclassListMeta):
45
+ """
46
+ Immutable List container compatible with DataclassInterface API. Value type provided at runtime.
47
+
48
+ Allowed value type annotations (including nested versions of these):
49
+ Any, Dict, List, Optional, Tuple, Union
50
+ TypeVar annotation is also allowed, but it can't be nested under any of the above containers
51
+ """
52
+
53
+ ValueT = ValueT # a TypeVar until the class is subscripted, e.g. DataclassList[int]
54
+
55
+
56
+ @classmethod
57
+ def _container_classes(cls) -> Tuple[Type, Type]:
58
+ """The (ListType, DictType) pair nested containers are cast to. Overridden by ConfigList."""
59
+ from ladder.core.databib.dataclasses.dataclass_dict import DataclassDict
60
+
61
+ return DataclassList, DataclassDict
62
+
63
+ def __new__(cls, *args, **kwargs):
64
+ value = tuple(*args, **kwargs)
65
+ # Cast value to List[cls.ValueT] (note that ValueT already has plain List/Dict container types
66
+ # substituted with their DataclassList / DataclassDict equivalents).
67
+ # NOTE: We cast the outer container to a python list instead of DataclassList to avoid infinite
68
+ # recursion since we are in DataclassList.__new__. super().__new__() will cast the outer container
69
+ value = cast_container_types(value, List[cls.ValueT])
70
+ return super().__new__(cls, value)
71
+
72
+ def __init__(self, *args, **kwargs):
73
+ del args, kwargs
74
+ # NOTE: tuple gets auto initialized in __new__. No need to call here
75
+ DataclassInterface.__init__(self)
76
+ self._check_value_types_at_runtime()
77
+
78
+ def _check_value_types_at_runtime(self):
79
+ if value_type_is_annotation_type(self, List[self.ValueT]):
80
+ return
81
+ # Provide more informative error
82
+ for index, value in enumerate(self):
83
+ if not value_type_is_annotation_type([value], List[self.ValueT]):
84
+ raise TypeError(
85
+ f"Incorrect type provided for {self.__class__.__name__}: expected "
86
+ f"{self.ValueT}, but got {value} of type {type(value)} at index {index}"
87
+ )
88
+
89
+ @classmethod
90
+ def from_json(
91
+ cls, data: Sequence[Any], recursive: bool = True, ignore_redundant: bool = False
92
+ ) -> "DataclassList[ValueT]":
93
+ if not isinstance(data, (list, tuple)):
94
+ raise TypeError(
95
+ f"{cls}.from_json() expects input of type list or tuple, but got input of type {type(data)}"
96
+ )
97
+ data = list(data)
98
+
99
+ if recursive and inspect.isclass(cls.ValueT) and issubclass(cls.ValueT, DataclassInterface):
100
+ data = [
101
+ cls.ValueT.from_json(value, recursive=recursive, ignore_redundant=ignore_redundant)
102
+ for value in data
103
+ ]
104
+
105
+ return cls(data)
106
+
107
+ def as_json(self, recursive: bool = True) -> List:
108
+ return [
109
+ value.as_json() if isinstance(value, DataclassInterface) and recursive else value
110
+ for value in self
111
+ ]
112
+
113
+ @classmethod
114
+ def make_empty(cls: Type[DataclassListT]) -> DataclassListT:
115
+ return cls([])
116
+
117
+ @property
118
+ def is_empty(self) -> bool:
119
+ return len(self) == 0
120
+
121
+ def items(self, recursive: bool = False):
122
+ for i, value in enumerate(self):
123
+ if recursive and isinstance(value, DataclassInterface):
124
+ for subkey, subvalue in value.items(recursive=True):
125
+ yield f"{i}.{subkey}", subvalue
126
+ else:
127
+ yield f"{i}", value
128
+
129
+ def replace(self, **kwargs) -> "DataclassList[ValueT]": # noqa: ARG002
130
+ raise RuntimeError(f"{self.__class__.__name__}.replace() is not supported")
131
+
132
+ def apply(
133
+ self, fcn: Callable, recursive: bool = True, skip_nones: bool = False
134
+ ) -> "DataclassList[ValueT]":
135
+ def fcn_wrapper(v: Any) -> Any:
136
+ if v is None and skip_nones:
137
+ return None
138
+ if isinstance(v, DataclassInterface) and recursive:
139
+ return v.apply(fcn, recursive=True, skip_nones=skip_nones)
140
+ return fcn(v)
141
+
142
+ return self.__class__([fcn_wrapper(value) for value in self])
143
+
144
+ def __repr__(self) -> str:
145
+ indent = " " * 2
146
+
147
+ fields_reprs = [
148
+ f"{indent}{repr(value)}".replace('\n', f'\n{indent}') for _, value in self.items(recursive=False)
149
+ ]
150
+ fields_repr = ("\n" + ",\n".join(fields_reprs) + f",\n") if len(fields_reprs) > 0 else ""
151
+
152
+ return f"{self.__class__.__name__}({fields_repr})"
153
+
154
+ def __reduce__(self) -> Tuple[Callable, Tuple[Any, ...], Dict[str, Any]]:
155
+ """
156
+ Needed so we properly support pickling for classes with square brackets in their names.
157
+
158
+ A subscripted class such as `DataclassDict[typing.Any]` is created at runtime and registered on
159
+ its module under that name (`dataclass_utils.parametrize`). pickle cannot look such a name up
160
+ itself, so this returns (callable, args, state): `get_dynamic_class` finds the class by name and
161
+ rebuilds the object from its JSON form, and `state` is passed to __setstate__ afterwards.
162
+ """
163
+ return (
164
+ get_dynamic_class,
165
+ (self.__class__.__module__, self.__class__.__name__, self.as_json()),
166
+ self.__dict__,
167
+ )
168
+
169
+
170
+ def get_dynamic_class(module_name: str, classname: str, data: Dict[str, Any]):
171
+ return getattr(sys.modules[module_name], classname).from_json(data)
ladder/core/databib/dataclasses/dataclass_utils.py ADDED
@@ -0,0 +1,63 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import sys
2
+ from typing import Any, Dict, Iterator, Tuple
3
+
4
+
5
+ def parametrize(cls: type, args: Tuple[Any, ...], **class_attrs: Any) -> type:
6
+ """The subclass `cls[args]`, with `class_attrs` set on it (e.g. DataclassDict[int] with ValueT = int).
7
+ It is registered on the module of `cls` under its name, which is how pickling finds it again."""
8
+ names = ", ".join(a.__name__ if isinstance(a, type) else repr(a) for a in args)
9
+ name = f"{cls.__name__}[{names}]"
10
+ new_cls = type(cls)(name, (cls,), {"__module__": cls.__module__, "__qualname__": name, **class_attrs})
11
+ setattr(sys.modules[cls.__module__], name, new_cls)
12
+ return new_cls
13
+
14
+
15
+ def zip_dataclass_items(*dataclasses, recursive: bool) -> Iterator[Tuple[str, Tuple[Any, ...]]]:
16
+ if len(set(type(dataclass) for dataclass in dataclasses)) > 1:
17
+ raise TypeError(
18
+ f"Cannot zip dataclasses with non-matching types: {[type(dataclass) for dataclass in dataclasses]}"
19
+ )
20
+
21
+ zip_iterator = zip(*[dataclass.items(recursive=recursive) for dataclass in dataclasses], strict=True)
22
+ tuples_of_items: Tuple[Tuple[str, Any], ...]
23
+ for tuples_of_items in zip_iterator:
24
+ items: Tuple[Any, ...] = sum(tuples_of_items, ())
25
+ keys: Tuple[str, ...] = items[0::2]
26
+ if len(set(keys)) > 1:
27
+ raise ValueError(f"Dataclass keys do NOT match: {keys}")
28
+ key: str = keys[0]
29
+ values: Tuple[Any, ...] = items[1::2]
30
+ yield key, values
31
+
32
+
33
+ def maybe_chained_keys_to_nested_dict(data: Dict[str, Any]) -> Dict[str, Any]:
34
+ """Converts a dict with keys of the form "key1.key2.key3" to a nested dict"""
35
+ unpacked_data: Dict[str, Any] = {}
36
+ for key, value in data.items():
37
+ if "." not in key:
38
+ unpacked_data = merge_dicts_recursive(unpacked_data, {key: value})
39
+ else:
40
+ mainkey, subkey = key.split(".", maxsplit=1)
41
+ nested_value = maybe_chained_keys_to_nested_dict({subkey: value})
42
+ unpacked_data = merge_dicts_recursive(unpacked_data, {mainkey: nested_value})
43
+ return unpacked_data
44
+
45
+
46
+ def merge_dicts_recursive(dict_1: Dict[str, Any], dict_2: Dict[str, Any]) -> Dict[str, Any]:
47
+ """
48
+ Merges dict_1 with dict_2 recursively.
49
+ Handles clashing keys:
50
+ 1. If both values are dicts, merges them recursively
51
+ 2. If any value is not a dict, raises ValueError
52
+ """
53
+ merged = dict(dict_1)
54
+
55
+ for key, value in dict_2.items():
56
+ if key in merged:
57
+ if not type(merged[key]) is type(value) is dict:
58
+ raise ValueError(f"Multiple values provided for key {key}: {merged[key]} and {value}")
59
+ merged[key] = merge_dicts_recursive(merged[key], value)
60
+ else:
61
+ merged[key] = value
62
+
63
+ return merged
ladder/core/databib/utils/classproperty.py ADDED
@@ -0,0 +1,47 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ class ClassPropertyDescriptor:
2
+ def __init__(self, fget, fset=None):
3
+ self.fget = fget
4
+ self.fset = fset
5
+
6
+ def __get__(self, obj, klass=None):
7
+ if klass is None:
8
+ klass = type(obj)
9
+ return self.fget.__get__(obj, klass)()
10
+
11
+ def __set__(self, obj, value):
12
+ if not self.fset:
13
+ raise AttributeError("can't set attribute")
14
+ type_ = type(obj)
15
+ return self.fset.__get__(obj, type_)(value)
16
+
17
+ def setter(self, func):
18
+ if not isinstance(func, (classmethod, staticmethod)):
19
+ func = classmethod(func)
20
+ self.fset = func
21
+ return self
22
+
23
+
24
+ def classproperty(func):
25
+ if not isinstance(func, (classmethod, staticmethod)):
26
+ func = classmethod(func)
27
+
28
+ return ClassPropertyDescriptor(func)
29
+
30
+
31
+ class CachedClassPropertyDescriptor:
32
+ def __init__(self, func):
33
+ self.func = func
34
+ self._values = {}
35
+
36
+ def __get__(self, obj, klass):
37
+ if klass not in self._values.keys():
38
+ self._values[klass] = self.func.__get__(obj, klass)()
39
+
40
+ return self._values[klass]
41
+
42
+
43
+ def cached_classproperty(func):
44
+ if not isinstance(func, (classmethod, staticmethod)):
45
+ func = classmethod(func)
46
+
47
+ return CachedClassPropertyDescriptor(func)