feat(sim): add semantic skill IR and compiler

[yuecideng]

Description

Stack

• Layer: 3/14
• Base: feat/atomic-action-pr2c-runtime-endpoints
• Depends on: refactor(atomic-actions): generalize runtime endpoints #488
• Followed by: feat(atomic-actions): add verified effect-aware runtime #495

Consolidation

Consolidates #489, #490, and #491 into this layer. Scope: semantic IR, call catalog, integration manifest, and compiler.
Add the canonical semantic compiler that resolves calls through the scene registry, robot profile, exact providers, and named policy presets into typed atomic-action invocations.

Compilation is lazy where goals depend on physical effects, validates all reachable resources/providers before execution, and keeps object-centric Pick, Place, HandOver, and articulation semantics out of task-owned motion code.

Refs #471
Refs #474

Type of change

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

Screenshots

Not applicable.

Validation

• Focused coverage: tests/sim/skills/test_compiler.py plus related atomic-action goal tests
• Final affected-suite regression on the stack tip: 1215 passed, 2 skipped, 8 deselected
• Changed Python files pass Black 26.3.1; the Sphinx build and rollout-report drift check pass at the stack tip

Checklist

• Changed Python files pass Black 26.3.1.
• Corresponding public/design documentation is included in this stack.
• Tests cover the affected behavior.
• No dependency update is required.

[greptile-apps]

Greptile Summary

The PR introduces a semantic skill intermediate representation, integration binding, compiler, and runtime facade over Atomic Actions.

• Adds typed Pick, Place, HandOver, and registered semantic-call compilation.
• Resolves scene entities, robot resources, policy presets, and grounding providers before execution.
• Adds JIT per-call grounding, effect verification, sticky environment eligibility, and task lifecycle management.
• Extends Atomic Action planning with bounded scene-dependency monitoring and initial eligible-cohort support.
• Adds focused tests, tutorials, API references, and architecture documentation.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains within the eligible follow-up review scope.

No blocking failure remains.

Important Files Changed

Filename	Overview
embodichain/lab/sim/skills/compiler.py	Adds provider-free workflow analysis and JIT lowering of semantic calls into typed Atomic Action invocations.
embodichain/lab/sim/skills/runtime.py	Adds task ownership, per-call execution orchestration, effect verification, eligibility propagation, and terminal cleanup.
embodichain/lab/sim/skills/integration.py	Adds manifest-based binding and validation across scene, robot profile, call catalog, and grounding providers.
embodichain/lab/sim/skills/calls.py	Defines the semantic-call IR, descriptors, catalog, and built-in call contracts.
embodichain/lab/sim/atomic_actions/execution.py	Adds sticky initial eligible-cohort handling and bounded scene-dependency monitoring for staged plans.
embodichain/lab/sim/atomic_actions/primitives/pick_up.py	Bounds PickUp target monitoring to its reversible approach segment so grasp-induced movement does not trigger invalidation.
embodichain/lab/sim/skills/scene.py	Extends canonical scene metadata and manifest contracts used by semantic integration.
tests/sim/skills/test_compiler.py	Covers semantic linking, resource inheritance, provider selection, late grounding, and registered-call boundaries.

Sequence Diagram

sequenceDiagram
participant App as Application
participant Runtime as SemanticSkillRuntime
participant Compiler as SemanticSkillCompiler
participant Scene as Scene Registry / Providers
participant Engine as AtomicActionEngine
participant Runner as ExecutionRunner
App->>Runtime: start SemanticTask
Runtime->>Compiler: analyze workflow
Compiler->>Scene: resolve entities, resources, providers
Runtime->>Compiler: ground next call from fresh observation
Compiler-->>Runtime: GroundedSemanticCall
Runtime->>Engine: start invocation with eligible mask
Engine-->>Runner: ExecutionSession
Runner->>Engine: tick with latest observations
Engine-->>Runner: commands / effect request
Runner-->>Runtime: terminal result and verified TaskState
alt more semantic calls
Runtime->>Compiler: ground next call
else task complete
Runtime-->>App: SemanticTaskResult
end

Loading

_{Reviews (9): Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Adds a new semantic skill compilation layer in embodichain.lab.sim.skills that statically analyzes object-centric workflows (Pick/Place/HandOver/registered calls) and then JIT-lowers each call into typed atomic-action invocations using the bound scene registry + robot profile + installed providers/grounders/lowerers.

Changes:

• Introduces SemanticSkillCompiler with workflow analysis (SemanticWorkflow) and per-call grounding (GroundedSemanticCall), including look-ahead targets and verified held-object dependencies.
• Extends scene/profile integration: SceneRegistry.object_semantics() for owned ObjectSemantics snapshots; RobotSkillProfile.grounding_providers for selecting named grounding providers (e.g., handover pose providers).
• Updates atomic actions to accept late-bound pose goal values (SceneEntityPose or tensors) and correctly collect scene dependencies / resolve targets at plan time; adds focused regression tests.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/sim/skills/test_scene.py	Adds coverage for rejecting non-owning affordance deepcopy behavior and for owned ObjectSemantics snapshots.
tests/sim/skills/test_profiles.py	Tests immutability/validation for new grounding_providers mapping on RobotSkillProfile.
tests/sim/skills/test_compiler.py	New comprehensive tests for semantic workflow analysis + JIT lowering behavior, provider selection, and validation.
tests/sim/atomic_actions/test_core.py	Tightens regression around late-bound pose ownership semantics.
tests/sim/atomic_actions/test_actions.py	Adds tests ensuring pose options own late-bound transforms and replan resolves latest scene snapshot targets.
embodichain/lab/sim/skills/scene.py	Hardens affordance metadata copying and adds SceneRegistry.object_semantics() helper.
embodichain/lab/sim/skills/profiles.py	Adds grounding_providers field and normalizes it as an immutable mapping.
embodichain/lab/sim/skills/integration.py	Shifts “registered lowerer installed” validation away from link_call (now enforced by compiler analysis).
embodichain/lab/sim/skills/compiler.py	New compiler module implementing analysis + grounding registries (relation grounders, registered lowerers, handover pose providers).
embodichain/lab/sim/skills/init.py	Exports compiler surface types from the skills package.
embodichain/lab/sim/atomic_actions/primitives/pick_up.py	Allows downstream look-ahead targets as pose goal values; resolves them at plan time; collects scene deps.
embodichain/lab/sim/atomic_actions/primitives/hand_over.py	Allows pose goal values for middle/final targets; resolves/collects deps at plan time.
embodichain/lab/sim/atomic_actions/goals.py	Adds SceneEntityPose.snapshot() and exposes collect_scene_dependencies() for late-bound pose values.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.