add-embodiment-component

name	add-embodiment-component
description	Add or update a reusable EmbodiChain embodiment YAML component that owns one simulation robot, its sensor suite, and an optional Task Program skill_profile. Use for configs/components/embodiments, new Task Program-compatible robots, or multi-embodiment task deployment.

Add Embodiment Component

Create the reusable physical and semantic declaration that lets one robot configuration serve many tasks.

Establish scope

An embodiment component belongs at:

embodichain_tasks/configs/components/embodiments/<embodiment_id>.yaml

It owns exactly:

• embodiment_id;
• one simulation robot mapping;
• the complete sensor list;
• optional skill_profile.

It does not own a task, physical scene, Task Program, execution policy, task-local object IDs, or runnable Gym ID. Component files do not use a compatibility version field.

Load current context

Read agent_context/MAP.yaml, then resolve:

• robot-system;
• sensor-system; and
• task-programs when a skill_profile is requested.

Inspect the closest current component under embodichain_tasks/configs/components/embodiments/ and the intended runnable task deployment.

Reuse or add the robot

If an existing registered robot config can express the request, select it in simulation and add only necessary config overrides. If a new RobotCfg/URDF/control-part implementation is required, invoke $add-robot first. This skill does not duplicate robot registration logic in YAML.

Keep the sensor suite atomic with the embodiment. Sensor parent link names must exist on the selected robot.

Add skill_profile only when needed

Handwritten and RL deployments may use an embodiment without semantic metadata. A configured Task Program requires skill_profile with:

• contract_id: the compatibility contract tasks/policies require;
• profile_id: stable unversioned profile identity;
• resources: logical task-facing resources;
• command_presets: named control commands;
• optional runtime_services.

Each resource declares logical endpoints. Endpoint declarations map to actual control_part names and list only capabilities the selected robot/runtime can provide. Grasp endpoints that require open/grasp commands select a matching command preset.

Use logical resource IDs such as primary_manipulator, left, or right; Task Program integrations bind Semantic Call slots to these IDs. Do not expose task-local names as reusable resources.

Runtime service ownership

Put embodiment-calibrated services in skill_profile.runtime_services, such as gripper-specific antipodal grasp generation or control-part evidence. Put task-specific targets, poses, and overrides in the task integration.

For reusable joint-position constraint evidence, omit object_ids unless the embodiment truly supports only an explicit global set. Omission lets runtime assembly scope evidence to graspable objects in the selected task scene.

Only use service kinds accepted by the current configured decoder. Never serialize a dotted import or callable.

Attach without copying

A runnable deployment selects:

embodiment:
  component: ../../../components/embodiments/<embodiment_id>.yaml

Optional deployment overrides are limited to uid, init_pos, init_rot, and init_qpos. Do not repeat inline robot or sensor fields.

One task can provide multiple thin deployments selecting compatible embodiments. Keep the program embodiment-independent and validate the integration and policy contracts against every variant.

Validation

At minimum:

1. decode the YAML as a closed embodiment component;
2. build the selected robot config and verify control parts;
3. verify sensor parent links and shapes;
4. verify every profile endpoint/control part/capability and command preset;
5. compose at least one intended task deployment;
6. for Task Program use, run $add-task-program's deployment inspector;
7. run a minimal live robot/sensor smoke test when available.

Checklist

• Component owns exactly one robot and one atomic sensor suite
• Existing robot config was reused, or $add-robot was completed first
• Profile is omitted when no semantic consumer needs it
• Contract/profile/resource/preset IDs are stable and unversioned
• Endpoint control parts exist on the robot
• Declared capabilities and commands are actually supported
• Reusable services contain no task-local object IDs or poses
• At least one intended deployment composes successfully