AgiBot X1 training skill

Use this repo skill when a task involves the AgiBot X1 DH stand locomotion task, x1_dh_stand, DH PPO, checkpoint discovery, interactive Isaac Gym playback, TorchScript/ONNX policy export, or MuJoCo sim2sim validation.

Route by intent

• Train or modify the X1 DH PPO task: read training.
• Play a runner checkpoint in Isaac Gym: read playback.
• Export a checkpoint to JIT or JIT to ONNX: read export.
• Validate an exported policy in MuJoCo: read sim2sim.
• Check whether this skill matches a repository revision: read provenance.
• Diagnose shared installation, backend, path, or artifact failures: read troubleshooting.

Do not combine a runner checkpoint, JIT policy, and ONNX file interchangeably. The normal handoff is:

training checkpoint (.pt) -> export -> policy_dh.jit -> sim2sim
                                      -> ONNX (optional deployment artifact)
training checkpoint (.pt) -> playback (interactive Isaac Gym)

Package and backend contract

This is a legacy Isaac Gym Preview 4 project rather than a CPU-only Python library. The documented baseline is Python 3.8, PyTorch 1.13.1 with CUDA 11.7, NumPy 1.23.x, Isaac Gym Preview 4, and the package's runtime dependencies. The main task imports isaacgym through the environment, terrain, utility, and registry chain. Isaac Gym Preview 4 is not available in the construction runtime, so native CUDA/PhysX training, playback, source export, and the full sim2sim script remain BLOCKED_REQUIRED_BACKEND until a compatible vendor installation is supplied and verified. Never replace it with a fake module or claim that a CPU import proves the simulator works.

MuJoCo 2.3.6 is the documented sim2sim dependency. MuJoCo XML/URDF and model-side checks can be performed separately, but they do not substitute for Isaac Gym task construction. Read the nearest sub-skill's backend boundary before launching any viewer, simulator, or long-running job.

For a fresh supported installation, install Isaac Gym Preview 4 from its vendor-distributed archive first, verify its own example, then install the repository in editable mode. Do not copy private archive paths, credentials, or machine-specific environment names into reports or reusable instructions.

A minimal package import check after all required dependencies are installed is:

python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
python -c "import isaacgym; import humanoid; import humanoid.envs"

If the second command fails with ModuleNotFoundError: isaacgym, stop all native task execution and preserve the backend block. Use the bundled sub-skill preflights for path, shape, XML, and artifact checks that do not require importing the simulator.

Cross-workflow operating rules

1. Pin --task=x1_dh_stand; it is the registered task covered by this graph.
2. Treat the X1 observation contract as fixed unless every dependent config, policy, exporter, checkpoint, and sim2sim assumption is updated together: 66 history frames × 47 values = 3102 actor observations, 5 × 47 = 235 short history values, 3 × 73 = 219 privileged observations, and 12 actions.
3. Keep source-relative resource resolution intact. The X1 URDF, MJCF includes, and mesh tree must be available to the actual runtime; use preflight helpers to detect missing assets rather than inventing replacements.
4. Treat logs/ paths and run/checkpoint names as explicit handoff data. The source uses logs/, while some README snippets use stale singular log/.
5. Start with one environment and a bounded preflight. Do not launch training, interactive playback, conversion, or a 100-second viewer loop as a smoke test.
6. Keep the hardware/backend verdict separate from CPU algorithm or serialized artifact checks. A successful static check is not a locomotion or robot-safety result.

Bundled references and helpers

• troubleshooting covers shared dependency, import, path, asset, checkpoint, and backend failures.
• repo provenance records the source revision and evidence baseline for staleness checks.
• routing metadata is structured import metadata for the managed repository-skill router.

The four focused routes contain their own references and safe helpers. Helpers are intentionally preflight-oriented: they do not download dependencies, launch a viewer, start pygame, open a simulator, or run full training by default. They must be run from arbitrary working directories with explicit paths when a checkout or artifact location is needed.