Reuse environments for semantic asset replacement and pouring

[yuecideng]

Description

Prepare semantically compatible asset combinations and collect Task Program demonstrations through the existing replace_assets_from_group functor. Collection retains one B=1 environment, robot, unselected scene objects, sensors and recorder instances across asset batches. The functor jointly replaces the selected rigid bodies through replace_rigid_objects() and refreshes their task bindings before execution.

The original entity_cfg / folder_path directory-sampling constructor and call remain supported. The new mutually exclusive deployment input consumes verified artifacts produced by Provider preparation, semantic matching and explicit geometry adaptation. Provider I/O and matching happen before collection. Runtime applies each combination at a cleared batch boundary, after previous recording buffers are consumed and before new observation/recording state is seeded.

Native-bound Task Program policy ports are constructed after replacement. Manager terms declaring SceneEntityCfg selectors for replaced bodies obtain fresh bindings; unrelated terms and recorders retain their state. Independent physical objectives retain their authored criteria and bind to the replacement body. Configuration provenance refreshes without restarting session identity or recorder counters. Changes to fixed robot, backend, control/schema or unselected-object declarations are rejected before native mutation; native preparation errors stop collection.

Expansion examples are consolidated under examples/expansion/: asset catalogs, asset generalization and trajectory expansion. Primitive cube/platform and bottle/cup acceptance configurations live beside the examples, reusing SDK embodiments/policies without adding official tasks. The PourWater adapter checks profile-bound calibration, recalculates grasp/staging/return geometry and measures simultaneous tilt, mouth alignment and height, cup stability and final bottle return.

Refs #810. Planned PR6 online generation remains deferred.

Stack

• Layer: 5/5
• Base: main
• Depends on: Materialize asset-bound Task Program deployments #814 (merged)
• Followed by: none

Validation

• 354 passed, 1 skipped across replacement/seed functors, shared collection and failure cleanup, materialization, pouring adaptation/monitor, real Task Program policy ports, scene acceptance, recording provenance and docs/context tooling.
• Focused regressions cover legacy directory construction/sampling, joint replacement, unchanged robot/unselected objects, adapter binding after replacement, cached manager-term rebinding, independent objective rebinding, provenance refresh, incompatible configuration/tampering rejection, inactive/B=1 boundaries and retained recorder counters.
• Native Default-backend CobotMagic PourWater completed two combinations in one environment: original bottle/original cup and taller bottle/wider cup. The sampled monitor recorded 68 and 78 qualifying simultaneous samples, respectively. Both episodes passed task/physical checks and returned the bottle upright.
• Both saved trajectories were reopened. Environment/robot/table instance IDs match across batches; bottle/cup instance IDs, asset identities and configuration fingerprints differ. The report records environment_constructions: 1, both episodes accepted/submitted and final shared close completed. Fluid transfer is explicitly unmeasured.
• 33 supplemental acceptance tests passed after fixing two existing review findings: omitted pouring tolerances now retain the schema default (0.03 m), and the primitive Place segment measures cube position relative to the live platform. Generated 4/5 cm variants update that measured offset with primitive size. Saved native primitive endpoints pass the new bounds; a cube on the floor fails them.
• Both example-local deployments passed the read-only Task Program inspector (2 primitive segments, 4 pour segments). Black 26.3.1 (black .), changed-file syntax/header/export checks, context validation/routing and public API docs coverage (2678/2678) passed.

Validation uses pinned DexSim 0.5.1rc1 and Warp 1.17.0 through process-local dependency paths; no shared installation was changed. Native qualification covers rigid B=1 replacement on the Default backend. Custom consumers with hidden cached handles need explicit selectors or live UID lookup. Full native workspace/material-randomization and asynchronous camera/dataset combinations remain unqualified; recorder/provenance contracts are covered by focused CPU tests. DexSim teardown still emits the previously observed entity-balance warning. Liquid transfer, articulated replacement and heterogeneous parallel scenes remain outside scope.

A Sphinx dummy build completed; the changed asset/functor APIs emitted no diagnostics. Existing unrelated cross-reference warnings remain.

Context guidance now describes shared-environment replacement, fresh native bindings and session recording. Existing physical scene, Task Program language and motion contracts remain applicable.

Usage

See examples/expansion/README.md and examples/expansion/asset_generalization/README.md.

python examples/expansion/asset_generalization/pour_water.py \
  --output /tmp/pour-assets --seed 1 --batches 2 --execute

PourWater accepts --bottle-catalog and --cup-catalog; failed acceptance exits nonzero and retains diagnostics separately from accepted trajectories. run.py remains the direct Cube-primitive baseline.

Type of change

• Enhancement (non-breaking change which improves existing functionality)
• New feature (non-breaking change which adds functionality)

Checklist

• I have run black . with Black 26.3.1.
• I reviewed affected documentation and agent context and updated lifecycle/ownership guidance.
• Public API documentation coverage passes.
• Focused production tests and real PourWater acceptance passed.
• Dependencies reviewed; no new package requirements.

[greptile-apps]

Confidence Score: 4/5

[Medium impact] Adds asset preparation and pouring task features.

Fix the settings comparison before merging so supported sensor-disabled and no-render runs can collect asset batches.

Findings

1.  Filtered settings stop collection ▶

Fix with agent prompt

### Issue 1
embodichain/lab/gym/envs/_asset_replacement.py:97-100
`_check_environment` compares the running environment's filtered manager settings with a freshly loaded, unfiltered configuration. With `enable_sensor=False` and sensor-dependent terms, environment setup replaces those terms with `None`. The first replacement then raises `ValueError` even when it reloads the same deployment, stopping collection before any objects are replaced. No-render runs with visual terms fail the same way.

Compare equally filtered settings, or retain the original declarations for this check.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

The PR prepares compatible asset batches and reuses one environment through replace_assets_from_group.

• Prepared asset batches reuse one environment across replacements.
• Position checks can follow a rotated reference object.
• PourWater batches match bottle mouths to cups and measure the pour motion.
• Expansion examples now share one directory.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Prepare and match assets] --> B[Verified deployments]
    B --> C[Create one environment]
    C --> D[Clear previous recording buffers]
    D --> E[Check fixed settings]
    E --> F[Replace selected bodies]
    F --> G[Refresh task bindings]
    G --> H[Execute and measure]
    H --> I[Commit or discard episode]
    I -->|Next batch| D
    I -->|Finished| J[Close shared recorders]

Loading

_{Reviews (6) · Last reviewed commit: "fix(assets): preserve tolerance defaults..." · Reviewed by Greptile}

[greptile-apps]

Filtered settings stop collection

_check_environment compares the running environment's filtered manager settings with a freshly loaded, unfiltered configuration. With enable_sensor=False and sensor-dependent terms, environment setup replaces those terms with None. The first replacement then raises ValueError even when it reloads the same deployment, stopping collection before any objects are replaced. No-render runs with visual terms fail the same way.

Compare equally filtered settings, or retain the original declarations for this check.

Knowledge Base Used: Gym environments and task integration

Prompt To Fix With AI

This is a comment left during a code review.
Path: embodichain/lab/gym/envs/_asset_replacement.py
Line: 97-100

Comment:
**Filtered settings stop collection**

`_check_environment` compares the running environment's filtered manager settings with a freshly loaded, unfiltered configuration. With `enable_sensor=False` and sensor-dependent terms, environment setup replaces those terms with `None`. The first replacement then raises `ValueError` even when it reloads the same deployment, stopping collection before any objects are replaced. No-render runs with visual terms fail the same way.

Compare equally filtered settings, or retain the original declarations for this check.

**Knowledge Base Used:** [Gym environments and task integration](https://app.greptile.com/dexforce/-/custom-context/knowledge-base/dexforce/embodichain/-/docs/gym-environments.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.