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 adds static analysis and lazy grounding for semantic skill workflows, including typed relation grounders, handover pose providers, and registered-call lowerers.

• Compiles Pick, Place, HandOver, and registered semantic calls into atomic-action invocations.
• Tracks held-object effects and downstream pose dependencies across workflows.
• Adds late-bound pose support to pickup and handover options.
• Extends robot profiles and scene registries with grounding-provider selection and owned object semantics.
• Adds focused compiler, profile, scene, and atomic-action coverage.

Confidence Score: 5/5

The PR appears safe to merge; no concrete changed-code failure remains after reviewing workflow analysis, grounding, eligibility, and pose-resolution paths.

The compiler validates workflow ownership, provider availability, resource bindings, held-object state, target types, and late-bound scene dependencies, while the investigated edge cases were either unreachable through the established execution flow or consistent with existing contracts.

Important Files Changed

Filename	Overview
embodichain/lab/sim/skills/compiler.py	Adds workflow analysis, effect tracking, extension registries, and context-sensitive lowering into typed atomic-action invocations; no actionable defect was established.
embodichain/lab/sim/atomic_actions/primitives/pick_up.py	Extends pickup look-ahead targets to support owned, late-bound scene poses and resolves them against each planning context.
embodichain/lab/sim/atomic_actions/primitives/hand_over.py	Adds scene-relative middle and final handover targets with dependency collection and late resolution.
embodichain/lab/sim/skills/scene.py	Adds owned conversion from registered object affordances to atomic-action object semantics and strengthens deepcopy ownership validation.
embodichain/lab/sim/skills/profiles.py	Adds immutable semantic-call-to-grounding-provider selections to robot profiles.
embodichain/lab/sim/skills/integration.py	Defers registered semantic-call lowerer validation from generic integration linking to the new compiler registry.
embodichain/lab/sim/atomic_actions/goals.py	Makes scene-relative pose values own their transform tensors and provides explicit snapshot copying.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Compiler as SemanticSkillCompiler
    participant Integration as BoundSemanticIntegration
    participant Registry as SceneRegistry
    participant Provider as Grounder/Provider
    participant Engine as AtomicActionEngine
    Client->>Compiler: analyze(semantic calls)
    Compiler->>Integration: link_call(call)
    Integration->>Registry: resolve objects and affordances
    Compiler-->>Client: SemanticWorkflow
    Client->>Compiler: ground(workflow, call_index, context)
    Compiler->>Provider: ground relation / resolve handover target
    Provider-->>Compiler: PoseGoalValue
    Compiler-->>Client: GroundedSemanticCall
    Client->>Engine: resolve and execute invocation

Loading

_{Reviews (1): Last reviewed commit: "feat(sim): compile semantic skill workfl..." | 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.