react-manip 0.1.0__tar.gz → 0.3.0__tar.gz

react_manip-0.3.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include README.md
+include README.zh-CN.md
+include requirements.txt
+recursive-include react_manip *.json
+recursive-include tasks *
+recursive-include integrations *.json
+recursive-include configs *.json
+recursive-include assets *.json *.png
+recursive-include scripts *.json
+prune assets/robots
+global-exclude __pycache__ *.py[cod] .DS_Store
+

react_manip-0.1.0/README.md → react_manip-0.3.0/PKG-INFO

@@ -1,4 +1,60 @@
-# ReAct-Manip 0.3
+Metadata-Version: 2.4
+Name: react-manip
+Version: 0.3.0
+Summary: Robotics manipulation evaluation runtime with reproducible MuJoCo task instances
+Project-URL: Homepage, https://github.com/Quotient-Lab/ReAct-Manip
+Project-URL: Repository, https://github.com/Quotient-Lab/ReAct-Manip
+Project-URL: Issues, https://github.com/Quotient-Lab/ReAct-Manip/issues
+Keywords: robotics,manipulation,mujoco,benchmark,evaluation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <3.11,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy==1.26.4
+Requires-Dist: mujoco==3.3.1
+Requires-Dist: robosuite==1.5.2
+Requires-Dist: scipy==1.15.3
+Requires-Dist: numba==0.67.0
+Requires-Dist: PyYAML>=6
+Provides-Extra: assets
+Requires-Dist: trimesh==5.1.1; extra == "assets"
+Requires-Dist: pycollada==0.9.3; extra == "assets"
+Requires-Dist: lxml==6.1.3; extra == "assets"
+Requires-Dist: python-dateutil==2.9.0.post0; extra == "assets"
+Requires-Dist: six==1.17.0; extra == "assets"
+Requires-Dist: coacd==1.0.7; extra == "assets"
+Requires-Dist: rtree==1.4.1; extra == "assets"
+Requires-Dist: networkx==3.4.2; extra == "assets"
+Provides-Extra: visualize
+Requires-Dist: pygame==2.6.1; extra == "visualize"
+Requires-Dist: imageio==2.37.2; extra == "visualize"
+Requires-Dist: imageio-ffmpeg==0.6.0; extra == "visualize"
+Provides-Extra: harness-vla
+Requires-Dist: jsonschema; extra == "harness-vla"
+Requires-Dist: pydantic-ai-slim[anthropic,cli,openai]==2.53.0; extra == "harness-vla"
+Requires-Dist: pydantic-ai-harness==0.53.0; extra == "harness-vla"
+Requires-Dist: tomli; python_version < "3.11" and extra == "harness-vla"
+Provides-Extra: all
+Requires-Dist: trimesh==5.1.1; extra == "all"
+Requires-Dist: pycollada==0.9.3; extra == "all"
+Requires-Dist: lxml==6.1.3; extra == "all"
+Requires-Dist: python-dateutil==2.9.0.post0; extra == "all"
+Requires-Dist: six==1.17.0; extra == "all"
+Requires-Dist: coacd==1.0.7; extra == "all"
+Requires-Dist: rtree==1.4.1; extra == "all"
+Requires-Dist: networkx==3.4.2; extra == "all"
+Requires-Dist: pygame==2.6.1; extra == "all"
+Requires-Dist: imageio==2.37.2; extra == "all"
+Requires-Dist: imageio-ffmpeg==0.6.0; extra == "all"
+Requires-Dist: jsonschema; extra == "all"
+Requires-Dist: pydantic-ai-slim[anthropic,cli,openai]==2.53.0; extra == "all"
+Requires-Dist: pydantic-ai-harness==0.53.0; extra == "all"
+Requires-Dist: tomli; python_version < "3.11" and extra == "all"
+
+# ReAct-Manip v0.3
 
 > **Robot asset update:** The active embodiments now use official PiPER-X arms:
 > `piperx`, `dual_piperx`, and `mobile_dual_piperx` (custom Tracer assembly).
@@ -15,11 +71,7 @@
 
 A robotics evaluation runtime for external policies, with 16 tasks, a fixed candidate bank, and one evaluation entry point. Optional features include a policy-view window, video recording, and keyboard control through Pygame. Training and reference solving policies are outside this release. Robot asset construction and rebuilding existing resolved instance banks are supported by scripts.
 
-> **Full evaluation scope:** A complete ReAct-Manip protocol run must run all 16 tasks in the main bank, all three Task Instances for every task, and all 15 Episodes for every instance (10 practice + 5 exam): 48 evaluation groups and 720 Episodes in total. A single task, task subset, single instance, shortened run, smoke check, aborted run, or otherwise incomplete run is for debugging or partial analysis only and must not be reported as a full protocol result. This pilot release does not yet produce an `official_score`.
-
-## License
-
-Project-authored code, benchmark records, documentation, and original assets are released under the [PolyForm Noncommercial License 1.0.0](LICENSE). This permits use, modification, and redistribution for permitted noncommercial purposes; it is a source-available license, not an Open Source Initiative approved open-source license. Third-party dependencies and assets retain their own licenses, including bundled third-party textures and robot assets obtained through the asset builder. See the notices shipped with those assets and [`scripts/piperx_assets.lock.json`](scripts/piperx_assets.lock.json).
+> **Full evaluation scope:** A complete ReAct-Manip evaluation must run all 16 tasks in the main bank, all three Task Instances for every task, and all 15 Episodes for every instance (10 practice + 5 exam): 48 evaluation groups and 720 Episodes in total. A single task, task subset, single instance, shortened run, smoke check, aborted run, or otherwise incomplete run is for debugging or partial analysis only and must not be reported as a complete Benchmark result.
 
 ## Background: why we built this Benchmark
 
@@ -38,7 +90,7 @@ Across those 15 Episodes, all four closed-loop parameter-adaptation tasks contin
 - **Generalization across scenes and tasks:** study sensitivity to the geometry, physical parameters, object choices, and initial conditions that each task actually samples. Randomization is task-specific, not a promise that every parameter varies in every task.
 - **Embodiment research:** develop policies for the single-arm, fixed dual-arm, and mobile dual-arm PiPER-X configurations. Each released task declares its supported robot; changing that embodiment requires compatible assets, task validation, and regenerated instances rather than a bank-mode CLI override.
 - **Closed-loop behavior analysis:** inspect actions, observations, contacts, task events, errors, and recovery using the feedback available for that task, alongside final scores.
-- **Geometry diagnostics:** inspect simulator geometry truth during local debugging. These Features are never inputs to a benchmark policy.
+- **Training and annotation pipelines:** collect simulator geometry truth for internal supervision, diagnostics, and Oracle comparisons, including a separate `../CL_Coach` checkout. Training algorithms and CL_Coach itself are outside this release.
 - **Simulation-to-real preparation:** investigate collision, reachability, and contact sensitivity before hardware experiments. Simulator performance alone does not establish hardware calibration or real-world transfer.
 
 ## Benchmark design principles
@@ -62,49 +114,102 @@ The main bank stores explicit Episode-level variations for all four closed-loop
 | `box_insertion` | Sliding friction of the left/right contact regions and total block mass | Friction 0.6–1.4× baseline, clipped to [0.01, 0.6]; mass 0.7–1.3× baseline |
 | `car_drive2` | Vehicle nominal-speed gain associated with throttle displacement | 0.90–1.15 m/s |
 
-Continuous variables use five-stratum coverage. Practice Episodes 1–5, practice Episodes 6–10, and exam Episodes 1–5 each cover the same full domain in an independently shuffled order. Practice and exam therefore share a parameter domain but differ in exact values and ordering. The saved instance records, including sampled parameters, are published in this repository. The policy API does not pass those records directly; which values appear in observations or feedback depends on each task's declared visibility contract. A policy must adapt through the permitted interface. A result should disclose any use of instance records or task-specific tuning, since those conditions differ from the policy-interface-only setting.
+Continuous variables use five-stratum coverage. Practice Episodes 1–5, practice Episodes 6–10, and exam Episodes 1–5 each cover the same full domain in an independently shuffled order. Practice and exam therefore share a parameter domain but differ in exact values and ordering. A public Policy is told which properties may change, but never receives the current hidden samples; it must estimate and respond through vision, contact, motion consequences, and task feedback.
 
 The variations are applied before MuJoCo model compilation and initial-state capture, then stored with the resolved runtime, model identity, and initial integration state in each Episode Instance. `phone_lean` also changes phone/support initial positions between Episodes, but support identities, sizes, masses, friction, and gravity belong to the Task Instance and stay fixed across its 15 Episodes; it is therefore reported separately from these four parameter-adaptation tasks.
 
-## Installation
+## Geometry ground-truth Feature interface (for `../CL_Coach`)
 
-The source checkout now builds a minimal wheel for the `box_insertion` development API. The distribution has **not been published to PyPI**. Installation from this checkout does not include the 16-task candidate bank or the complete evaluation CLI.
+Geometry Features are an internal, read-only channel for data collection, annotation, diagnostics, and explicitly privileged Oracles. They are obtained through [`GeometryFeatureAdapter`](react_manip/core/geometry.py), separately from the public observations sent to a policy. `../CL_Coach` refers to a separate consumer checkout; it is not a bundled dependency or an automatically started service.
 
-The candidate bank requires **Python 3.10, NumPy 1.26.4, MuJoCo 3.3.1, and robosuite 1.5.2**. Use the same virtual-environment setup on macOS or Linux. From the repository root:
-
-```bash
-python3.10 -m venv .venv
-source .venv/bin/activate
-python -m pip install -r requirements.txt
-python scripts/build_agilex_assets.py
-```
+Adapters read the compiled MuJoCo model, simulation data, and task-owned read-only state. Extraction must not advance physics, change `qpos`/`qvel`, or alter scoring and dwell timers. Body poses use world coordinates, meters, and MuJoCo `(w, x, y, z)` quaternions. Velocity fields use SI units; matrices, local coordinates, and fields explicitly suffixed `_deg` retain their task-defined conventions. Check field definitions instead of treating every numeric array as a pose.
 
-For the minimal installed API, use Python 3.10 and install from this checkout:
+The stable top-level schema is:
 
-```bash
-python3.10 -m venv .venv
-source .venv/bin/activate
-python -m pip install '.[assets]'
-react-manip-assets prepare
+```text
+{
+  "schema_version": "geometry.v1",
+  "entities": {"<entity name>": ...},
+  "relations": {"<relation name>": ...},
+  "task_state": {...},
+  "validity_mask": {...}
+}
 ```
 
-`react-manip-assets prepare` builds the checksum-locked PiPER-X assets in the checkout when installed from source, or in the user cache when installed from a wheel. The first build needs network access. To try a wheel without publishing it, build one with `python -m pip wheel . --no-deps` and install that wheel with its `[assets]` extra.
+Entity contents and array sizes vary by task; some entries are lists of objects. The validity mask describes the adapter's reported entities, not a universal sensor-quality certificate. Geometry diagnostic fields are not the scoring authority: use the task's declared final `info[score_key]` and terminal feedback for evaluation.
+
+### Collection-side interface
 
-The installed development API generates one validated Task/Episode pair, replays it, and exposes the task's current score. It is for debugging and integration work; it does not produce an official benchmark result:
+Keep the returned environment wrapper for `reset()` and `step()`, and unwrap it only to select the task's geometry adapter. This minimal internal collection example uses the button task and one zero-action transition; it is not a solving policy or a scored evaluation:
 
 ```python
 import numpy as np
-from react_manip import create_instance, open_instance, task_score
-
-bundle = create_instance('box_insertion', seed=7, episode_index=0)
-bundle.save('example_instance')
-with open_instance(bundle, cameras=False) as env:
-    obs, reset_info = env.reset()
-    obs, reward, terminated, truncated, info = env.step(np.zeros(env.action_dim))
-    print(task_score(info, 'box_insertion'))
+from react_manip.builtin import discover_task_definitions
+from react_manip.core import GeometryFeatureAdapter, normalize_reset, normalize_step
+from react_manip.core.compatibility import resolve_task_robot
+
+spec, factory = next(
+    (spec, factory) for spec, factory in discover_task_definitions()
+    if spec.task_id == "button_indicator_matching"
+)
+robot_id = resolve_task_robot(spec)
+env = factory(seed=0, robot_id=robot_id,
+              has_offscreen_renderer=False, use_camera_obs=False)
+try:
+    observation, info = normalize_reset(env.reset())
+    task_env = getattr(env, "env", env)
+    adapter = GeometryFeatureAdapter.for_task(task_env)
+    before = adapter.extract()
+    transition = normalize_step(env.step(np.zeros(env.action_dim)))
+    after = adapter.extract()
+    record = {
+        "task_id": spec.task_id,
+        "robot_id": robot_id,
+        "scenario_id": getattr(getattr(env, "scenario", None), "scenario_id", None),
+        "simulation_time_s": float(task_env.sim.data.time),
+        "features": after,
+        "reward": transition.reward,
+        "terminated": transition.terminated,
+        "truncated": transition.truncated,
+    }
+finally:
+    env.close()
 ```
 
-Robot assets are not committed to Git. The builder downloads official source models and meshes from pinned upstream commits and generates `assets/robots/agilex/`. The first build requires network access; cached sources are reused. Generated assets are gitignored and do not need to be downloaded again for evaluation. Small scene assets are included in the repository. Do not substitute other object assets: the bank validates the compiled model identity. The single `requirements.txt` also includes asset-builder, visualization, Pygame, and HarnessVLA API dependencies.
+Extract a fresh snapshot after each step and align it with that transition's action, public observation, language, feedback, and simulation timestamp. A training dataset should additionally record Task/Episode IDs, scenario and runtime digests, phase, step index, schema version, and camera IDs when images are enabled. NumPy arrays require an array-capable storage format or explicit conversion before JSON serialization. The example disables RGB; collection requiring images should enable the documented camera interface on the same environment.
+
+Keep privileged Features in a separate dataset field or stream. Do not use robosuite's concatenated `object-state` as a cross-task schema, and do not pass an unfiltered raw observation directly to a public policy. The runner applies [`policy_observation` and `policy_info`](react_manip/core/observation.py); declared legacy privileged keys are filtered, and geometry truth is attached only for an explicit internal Oracle opt-in. Public candidate-bank evaluation rejects `requires_geometry_truth=True`. `--trace-dir` records the public evaluation stream; it is not a substitute for this internal geometry collector. The current contracts remain task-specific, so a data pipeline must audit which additional state fields are public.
+
+### Available adapter entry points
+
+These are the adapters currently implemented in this release, not a claim that all 16 tasks expose geometry Features. Most live in [`react_manip/core/geometry.py`](react_manip/core/geometry.py); the drawer-search adapter registers from its task module when that environment is imported.
+
+| Task | Adapter | Feature contents |
+| --- | --- | --- |
+| `box_insertion` | `BoxInsertionGeometry` | Block and end-effector geometry, slot bounds, clearance, contact force, and insertion state |
+| `laptop_into_drawer` | `LaptopIntoDrawerGeometry` | Laptop, drawer, handle, and end-effector geometry; containment bounds and relative distances |
+| `find_object_in_drawer2` | `FindObjectInDrawer2Geometry` | Object poses and drawer membership, drawer slides, destination-box bounds, current target, and placement state |
+| `conveyor_grasp` | `ConveyorGraspGeometry` | Object poses, velocities, categories, bins, examples, assignments, and sorting state |
+| `phone_lean` | `PhoneLeanGeometry` | Phone, selected supports, and end-effector poses; relative positions and diagnostic distance/height fields |
+| `pitch_pot` | `PitchPotGeometry` | Projectile pose/velocity, pot and tray geometry, relative position, and hit/attempt state |
+| `button_indicator_matching` | `ButtonIndicatorMatchingGeometry` | Buttons, indicator labels and states, hidden wiring, current target, raw score, and events |
+
+For a new task, subclass `GeometryFeatureAdapter`, register its task ID with `@GeometryFeatureAdapter.register("my_task")`, implement `extract()` using `_result(...)`, and declare the field semantics and visibility in TaskSpec. Add reset/step checks for shapes, validity, and read-only behavior. Collection must report a missing adapter explicitly rather than inventing a generic geometry view. Existing registration does not require a task-specific branch in the runner or Pygame frontend.
+
+## Installation
+
+The candidate bank requires **Python 3.10, NumPy 1.26.4, MuJoCo 3.3.1, and robosuite 1.5.2**. Install the released package and the asset-building dependencies in a Python 3.10 environment:
+
+```bash
+python3.10 -m venv .venv
+source .venv/bin/activate
+python -m pip install "react-manip[assets]==0.3.0"
+react-manip-build-assets
+```
+
+Use `react-manip[all]` to include visualization and HarnessVLA integration dependencies. For development from a source checkout, `python -m pip install -e ".[all]"` is supported.
+
+Robot assets are not included in the wheel because the generated bundle is too large for a normal PyPI distribution. The builder downloads checksum-locked official source models and meshes from pinned upstream commits. A source checkout keeps assets under `assets/robots/agilex/`; a wheel install uses `~/.cache/react-manip/assets/robots/agilex/` by default. Override either location with `AGILEX_ASSET_DIR`. The first build requires network access and later builds reuse cached sources. Small scene assets, textures, task definitions, and the candidate bank are included in the wheel. Do not substitute other object assets: the bank validates the compiled model identity.
 
 The runtime defaults to `NUMBA_DISABLE_JIT=0` before importing simulation dependencies, matching the recorded bank. Do not switch JIT modes within one process. Optional IK or private-configuration warnings from robosuite do not imply missing dependencies for the controllers used here.
 
@@ -112,7 +217,7 @@ Visual evaluation requires a working OpenGL context. macOS uses its default back
 
 ## Evaluation
 
-The main-bank command below performs a full protocol run. It does not use `--draw-seed` to choose only one candidate per task: it runs all 16 tasks, all 48 Task Instances, and all 720 Episodes, including all 180 parameter-varying Episodes from the four closed-loop tasks. The aggregate `protocol_score` is a full-run pilot result only when every group finishes validly; if any group is missing or invalid, the score is `null`. `--task`, task-specific manifests, and `--state-only-smoke` are not full protocol runs.
+The main-bank command below performs the complete evaluation. It does not use `--draw-seed` to choose only one candidate per task: it runs all 16 tasks, all 48 Task Instances, and all 720 Episodes, including all 180 parameter-varying Episodes from the four closed-loop tasks. The aggregate `protocol_score` represents a complete Benchmark result only when every group finishes validly; if any group is missing or invalid, the score is `null`. `--task`, task-specific manifests, and `--state-only-smoke` are not complete evaluations.
 
 When neither `--manifest` nor `--task` is specified, evaluation defaults to the shipped `react_manip/suites/piperx_candidates_v1/bank.json`, resolved relative to the repository rather than the current working directory. `--draw-seed` remains required. Use `--candidate-bank <path>` to select another bank; explicit manifest and task modes retain their existing behavior.
 
@@ -188,19 +293,7 @@ The factory must return a fresh policy. Fixed-bank evaluation creates one policy
 
 Actions must be finite vectors of length `action_dim`, with all values in `[-1, 1]`. Invalid actions invalidate the group; they are not silently clipped. Each Task Instance selects its declared PiPER-X embodiment and recorded controller layout; a seven-dimensional single-arm policy cannot be applied unchanged to a dual-arm instance. Actual observation dictionaries and TaskSpecs define the image, instruction, and proprioceptive inputs. Instance files are not passed to the policy. Observation filtering follows task declarations; some tasks still expose task state or physical parameters. The public track rejects policies with `requires_geometry_truth=True`.
 
-An instance/group score is the mean of its five exam scores; the candidate-bank protocol score is the mean across all 48 groups (equivalently, each task's 15 exam episodes receive equal weight). If any group is invalid, the protocol score is null and the CLI exits with a nonzero status. `official_score` remains null: this pilot release has not established an official comparison track or certified solvability for every task. Report `protocol_score` as a pilot protocol result, together with the observation track, policy setup, and run provenance. Simulation advances synchronously; slow inference does not consume extra control steps.
-
-## Reported pilot baselines
-
-The following results were reported from tests using the [RPent framework](https://github.com/RLinf/RPent) on the 48-group, 720-Episode protocol. Each completed row uses 480 practice and 240 exam Episodes; the exam mean is on a 0–100 scale. Pass counts and mean scores are reported values, not independently reproduced by this repository. The exact RPent configuration, policy implementation, prompts, run logs, runtime revision, and any timeout overrides are not included with these figures here. Comparisons should disclose those settings and any access to the published instance records.
-
-| Model / configuration | Practice passes | Exam passes | Exam mean / 100 | Groups passing all five exams |
-| --- | ---: | ---: | ---: | ---: |
-| GPT-6 Astra | 177/480 (36.88%) | 130/240 (54.17%) | 52.62 | 22/48 |
-| GPT-6.1 Sol | 134/480 (27.92%) | 95/240 (39.58%) | 38.30 | 16/48 |
-| GPT-6.1 Terra | 96/480 (20.00%) | 94/240 (39.17%) | 33.73 | 17/48 |
-| GPT-5.6 Sol | 42/480 (8.75%) | 31/240 (12.92%) | 17.93 | 4/48 |
-| GPT-6 Astra + PI - 0.5 | Pending | Pending | Pending | Pending |
+An instance/group score is the mean of its five exam scores; the candidate-bank protocol score is the mean across all 48 groups (equivalently, each task's 15 exam episodes receive equal weight). If any group is invalid, the protocol score is null and the CLI exits with a nonzero status. `official_score` remains null: this pilot release is not a certification of solvability for every task. Simulation advances synchronously; slow inference does not consume extra control steps.
 
 ## First-person cameras and visualization
 
@@ -342,81 +435,3 @@ Use a new output directory. The script rebuilds task/episode records and the can
 Language is owned by each task’s `env.py` through `get_episode_language_prompt()`. The adapter refreshes it after reset and every step and supplies `info["language_prompt"]` and `info["language_prompt_structured"]` to the policy. Structured fields separate `task_instruction` from `round_instruction` and `round_index` (zero-based, or null when no round is active). Missing runtime interfaces fail explicitly; task JSON is not a language fallback.
 
 The drawer search task (`find_object_in_drawer2`) accepts either arm or both arms together. Both pose commands and both grippers are active. Its fixed rules, current-round instructions, constraints and end statuses are English-only; all five ordered placements still share 600 seconds and earn 20 points each.
-
-## Geometry ground-truth Feature interface (debugging only)
-
-Geometry Features are an internal, read-only channel used only for local debugging and diagnostics. They are obtained through [`GeometryFeatureAdapter`](react_manip/core/geometry.py), separately from public policy observations. Do not expose these privileged Features to a benchmark policy or use them for benchmark evaluation or scoring.
-
-Adapters read the compiled MuJoCo model, simulation data, and task-owned read-only state. Extraction must not advance physics, change `qpos`/`qvel`, or alter scoring and dwell timers. Body poses use world coordinates, meters, and MuJoCo `(w, x, y, z)` quaternions. Velocity fields use SI units; matrices, local coordinates, and fields explicitly suffixed `_deg` retain their task-defined conventions. Check field definitions instead of treating every numeric array as a pose.
-
-The stable top-level schema is:
-
-```text
-{
-  "schema_version": "geometry.v1",
-  "entities": {"<entity name>": ...},
-  "relations": {"<relation name>": ...},
-  "task_state": {...},
-  "validity_mask": {...}
-}
-```
-
-Entity contents and array sizes vary by task; some entries are lists of objects. The validity mask describes the adapter's reported entities, not a universal sensor-quality certificate. Geometry diagnostic fields are not the scoring authority: use the task's declared final `info[score_key]` and terminal feedback for evaluation.
-
-### Debugging example
-
-Keep the returned environment wrapper for `reset()` and `step()`, and unwrap it only to select the task's geometry adapter. This minimal internal debugging example uses the button task and one zero-action transition; it is not a solving policy or a scored evaluation:
-
-```python
-import numpy as np
-from react_manip.builtin import discover_task_definitions
-from react_manip.core import GeometryFeatureAdapter, normalize_reset, normalize_step
-from react_manip.core.compatibility import resolve_task_robot
-
-spec, factory = next(
-    (spec, factory) for spec, factory in discover_task_definitions()
-    if spec.task_id == "button_indicator_matching"
-)
-robot_id = resolve_task_robot(spec)
-env = factory(seed=0, robot_id=robot_id,
-              has_offscreen_renderer=False, use_camera_obs=False)
-try:
-    observation, info = normalize_reset(env.reset())
-    task_env = getattr(env, "env", env)
-    adapter = GeometryFeatureAdapter.for_task(task_env)
-    before = adapter.extract()
-    transition = normalize_step(env.step(np.zeros(env.action_dim)))
-    after = adapter.extract()
-    record = {
-        "task_id": spec.task_id,
-        "robot_id": robot_id,
-        "scenario_id": getattr(getattr(env, "scenario", None), "scenario_id", None),
-        "simulation_time_s": float(task_env.sim.data.time),
-        "features": after,
-        "reward": transition.reward,
-        "terminated": transition.terminated,
-        "truncated": transition.truncated,
-    }
-finally:
-    env.close()
-```
-
-Extract a fresh snapshot after each step and align it with that transition's action, public observation, language, feedback, and simulation timestamp. For reproducible debugging, also record Task/Episode IDs, scenario and runtime digests, phase, step index, schema version, and camera IDs when images are enabled. NumPy arrays require an array-capable storage format or explicit conversion before JSON serialization. The example disables RGB; enable the documented camera interface on the same environment when debugging with images.
-
-Keep privileged Features in a separate debugging record. Do not use robosuite's concatenated `object-state` as a cross-task schema, and do not pass an unfiltered raw observation directly to a public policy. The runner applies [`policy_observation` and `policy_info`](react_manip/core/observation.py); declared legacy privileged keys are filtered, and geometry truth requires an explicit internal opt-in that must be used only for debugging. Public candidate-bank evaluation rejects `requires_geometry_truth=True`. `--trace-dir` records the public evaluation stream; use this interface only for separate local diagnostics. The current contracts remain task-specific, so debugging code must check which additional state fields are public.
-
-### Available adapter entry points
-
-These are the adapters currently implemented in this release, not a claim that all 16 tasks expose geometry Features. Most live in [`react_manip/core/geometry.py`](react_manip/core/geometry.py); the drawer-search adapter registers from its task module when that environment is imported.
-
-| Task | Adapter | Feature contents |
-| --- | --- | --- |
-| `box_insertion` | `BoxInsertionGeometry` | Block and end-effector geometry, slot bounds, clearance, contact force, and insertion state |
-| `laptop_into_drawer` | `LaptopIntoDrawerGeometry` | Laptop, drawer, handle, and end-effector geometry; containment bounds and relative distances |
-| `find_object_in_drawer2` | `FindObjectInDrawer2Geometry` | Object poses and drawer membership, drawer slides, destination-box bounds, current target, and placement state |
-| `conveyor_grasp` | `ConveyorGraspGeometry` | Object poses, velocities, categories, bins, examples, assignments, and sorting state |
-| `phone_lean` | `PhoneLeanGeometry` | Phone, selected supports, and end-effector poses; relative positions and diagnostic distance/height fields |
-| `pitch_pot` | `PitchPotGeometry` | Projectile pose/velocity, pot and tray geometry, relative position, and hit/attempt state |
-| `button_indicator_matching` | `ButtonIndicatorMatchingGeometry` | Buttons, indicator labels and states, hidden wiring, current target, raw score, and events |
-
-For a new task, subclass `GeometryFeatureAdapter`, register its task ID with `@GeometryFeatureAdapter.register("my_task")`, implement `extract()` using `_result(...)`, and declare the field semantics and visibility in TaskSpec. Add reset/step checks for shapes, validity, and read-only behavior. Debugging code must report a missing adapter explicitly rather than inventing a generic geometry view. Existing registration does not require a task-specific branch in the runner or Pygame frontend.