embodichain.lab.task_program.integrations.scene_expansion

This integration evaluates one SceneVariant through the existing Task Program and Gym demonstration execution path. An injected host prepares the physical scene; a separate validator supplies measured task evidence. The API currently requires a single environment row and an explicit or environment-configured Task Program.

ScenePreparationResult	Host-owned settled state identity and explicit initial-state checks.
SceneVariantEpisodeResult	Independent scene preparation, program execution, and measured outcome.
execute_scene_variant	Prepare and evaluate one scene through the ordinary demo execution path.

Preparation and execution boundary

The preparation callback applies or restores the candidate, settles physics, checks the actual initial state, saves its initial-state artifact, and refreshes recording observations and affected bindings. It returns a ScenePreparationResult with the actual initial-state ID and nonempty ValidationResult checks. Rejecting that initial state prevents execution. Physical preparation and workspace screening are supplied by the caller at this layer; the fixed-candidate API does not instantiate a simulation host.

For valid initial states, execute_scene_variant creates a fresh bridge using the canonical EmbodiedEnv.create_demo_segments(task_program=...) path and passes the resulting segments through execute_demo_episode. Handwritten segment-planner overrides do not replace the selected Task Program. The normal Gym executor owns env.step(). Automatic resets are suspended throughout preparation, execution, and measurement. Explicit resets during either callback discard recording buffers while the attempt remains in progress; the attempt’s persistence guard survives replacement of episode metadata by those resets.

Measured acceptance and persistence

SceneVariantEpisodeResult preserves initial checks, program execution, and measured task checks independently. program_completed records normal completion of the selected canonical bridge, and program_completion_mask owns its single-row acceptance snapshot. The execution entry point leaves the mask empty when the bridge did not complete. program_success requires that bridge evidence and a successful demo execution. Generic Gym success from a legacy task override or early termination does not establish program completion. Acceptance requires valid initial checks, program_success, and passing measured task checks. Empty checks, unavailable evidence, a failed program, or failed measured goals cannot accept the scene. A completed program with projected effects still needs physical evidence from the measured validator.

The attempt’s proposal, actual initial-state identity, and validation evidence are published under scene_expansion in the existing episode metadata. Preparation provenance is owned and recursively immutable; to_metadata() returns JSON-compatible values, including the canonical bridge completion evidence. While an attempt is active, reset cannot persist dataset, camera, or trajectory buffers, even after a preparation or measurement reset replaces the pending metadata. Failed or interrupted recordings remain ineligible for these writes, including explicit commit-row requests and failed-episode recording.

Rejection belongs to the recording buffers until reset actually discards them. Replacing episode annotations or starting another demo does not clear it. A later successful attempt without that reset can return accepted=True but cannot make the earlier rejected recording eligible to save. Discard the recording before retrying, using env.reset(options={"save_data": False}).

The integration performs one attempt, propagates configuration and host errors, and creates no retry scheduler or persistence session. The caller closes the normal transaction with env.reset(options={"save_data": result.accepted}). An accepted execution is not confirmation that a dataset write succeeded.

Injecting a host and measured validator

The following helper accepts the fixed source from the scene proposal example. Both callbacks are required application implementations, so the example does not substitute a constant passing check for physical evidence:

from collections.abc import Callable

from embodichain.lab.gym.envs.embodied_env import EmbodiedEnv
from embodichain.lab.sim.motion.expansion import ValidationResult
from embodichain.lab.sim.scene_expansion import (
    FixedSceneCandidateSource,
    SceneVariant,
)
from embodichain.lab.task_program.integrations.scene_expansion import (
    ScenePreparationResult,
    SceneVariantEpisodeResult,
    execute_scene_variant,
)

def collect_fixed_variants(
    env: EmbodiedEnv,
    source: FixedSceneCandidateSource,
    *,
    prepare_scene: Callable[[SceneVariant], ScenePreparationResult],
    measured_validator: Callable[[], ValidationResult],
) -> list[SceneVariantEpisodeResult]:
    results = []
    for variant in source:
        result = execute_scene_variant(
            env,
            variant,
            prepare_scene=prepare_scene,
            measured_validator=measured_validator,
            episode_index=variant.ordinal,
            attempt_id=variant.ordinal,
        )
        results.append(result)
        env.reset(options={"save_data": result.accepted})
    return results

The environment must already have its Task Program integration configured. prepare_scene begins each candidate from a clean recording boundary using reset with save_data=False when needed, including after any rejected or interrupted attempt. It captures state and reseeds observations only after settling and refreshing bindings. The measured callback reads terminal state and any required intermediate-event evidence; it returns ValidationResult rather than an arbitrary truthy value. Applications retain their own bounded retry policy and exceptional-attempt cleanup.

Public interfaces

class embodichain.lab.task_program.integrations.scene_expansion.ScenePreparationResult

Host-owned settled state identity and explicit initial-state checks.

Parameters:

• initial_state_id (str) – Identity of the actual state saved by the host after preparation and settling. This is distinct from the proposal ID.

• validation (ValidationResult) – Required initial-state checks based on the actual scene. Empty or unavailable checks reject the candidate.

• metadata (Mapping[str, object]) – JSON-compatible provenance such as scene/integration versions and the identity of the host’s saved initial-state artifact.

Methods:

__init__(initial_state_id, validation[, ...])

__init__(initial_state_id, validation, metadata=<factory>)

class embodichain.lab.task_program.integrations.scene_expansion.SceneVariantEpisodeResult

Independent scene preparation, program execution, and measured outcome.

Parameters:

• variant (SceneVariant) – Exact proposed scene evaluated by this attempt.

• preparation (ScenePreparationResult) – Actual settled initial-state identity and checks.

• execution (DemoEpisodeResult | None) – Existing demo executor result, absent for an invalid initial scene. Program completion alone does not imply acceptance.

• measured_validation (ValidationResult | None) – Required measured task checks after execution, absent when initial-state validation prevented execution.

• program_completed (bool) – Whether the selected canonical bridge completed all segment lifecycles normally. Generic Gym success is insufficient.

• program_completion_mask (tuple[bool, ...]) – Owned single-row bridge acceptance snapshot, available only after normal program completion.

Methods:

__init__(variant, preparation, execution, ...)
to_metadata()	Export JSON-compatible proposal, initial-state, and outcome evidence.

Attributes:

accepted	Return whether initial checks, execution, and measured checks passed.
program_success	Return whether the canonical program and demo execution succeeded.

__init__(variant, preparation, execution, measured_validation, program_completed=False, program_completion_mask=())

property accepted: bool

Return whether initial checks, execution, and measured checks passed.

Returns:

Acceptance for this scene and attempt only; persistence is owned by the existing caller and is not implied by this result.

property program_success: bool

Return whether the canonical program and demo execution succeeded.

Returns:

Success only with normal bridge completion and its acceptance mask.

to_metadata()

Export JSON-compatible proposal, initial-state, and outcome evidence.

Return type:

dict[str, object]

Returns:

Provenance suitable for the existing episode recording path.

embodichain.lab.task_program.integrations.scene_expansion.execute_scene_variant(env, variant, *, prepare_scene, measured_validator, task_program=None, episode_index=0, attempt_id=0, execution_cfg=None)

Prepare and evaluate one scene through the ordinary demo execution path.

The host prepares/restores the candidate, settles physics, validates the actual initial state, and refreshes recording observations and bindings. Only then does the canonical EmbodiedEnv.create_demo_segments(task_program=...) create the fresh runtime bridge. Its segments flow through execute_demo_episode(), including for subclasses with a handwritten segment-planner override.

This function performs one attempt and no persistence. The caller retains the existing transaction boundary: reset to commit an accepted episode or reset with save_data=False to discard it. Failed or unverified scene acceptance also blocks a later ordinary reset from saving this recording. Automatic resets and persistence remain suspended throughout preparation, execution, and measurement. A rejected recording stays ineligible until the host resets its buffers, including before a later accepted attempt.

Parameters:

• env (EmbodiedEnv) – Initialized single-row EmbodiedEnv or a wrapper around one.

• variant (SceneVariant) – Existing-entity scene candidate to evaluate.

• prepare_scene (Callable[[SceneVariant], ScenePreparationResult]) – Narrow host callback that applies/restores the variant, settles and refreshes observations, and returns explicit checks.

• measured_validator (Callable[[], ValidationResult]) – Callback reading physical state and required execution evidence. It must return ValidationResult, independently of Task Program completion; arbitrary truthy values are rejected.

• task_program (TaskProgramCfg | CompiledTaskProgram | None) – Explicit config/compiled program, or the environment’s configured Task Program. Handwritten action-list execution is not accepted by this entry point.

• episode_index (int) – Existing demo episode metadata index.

• attempt_id (int) – Existing demo execution attempt index.

• execution_cfg (DemoExecutionCfg | None) – Existing demo persistence layout settings.

Return type:

SceneVariantEpisodeResult

Returns:

Separate initial-state, program, and measured validation results with an acceptance decision. Invalid initial checks prevent execution.

Raises:

• TypeError – For invalid contracts, callbacks, or program types.

• ValueError – For unsupported batching or invalid attempt identifiers.

• RuntimeError – If another scene expansion attempt is already active.

• Exception – Host, planning, execution, and measurement errors propagate after the episode is marked ineligible for persistence.