feat(manip): add GraspGenX proposal provider

[TomCC7]

Contribution path

• Linked issue: DIM-1401

Problem

The manipulation stack needs a typed, import-safe boundary for ranked grasp proposals. Without one, downstream planning code must depend directly on the optional GraspGenX runtime and cannot exchange candidates through stable DimOS message contracts.

Solution

• Add GraspCandidate and GraspCandidateArray message contracts.
• Add the GraspGenX provider and runtime boundary.
• Keep provider imports safe when the optional GraspGenX runtime is unavailable.
• Exclude the standalone verification demo and recorded fixture from production.

This is stack 1 of 5. Base: main. Next: #3363.

How to Test

uv run pytest dimos/manipulation/grasping/test_grasp_gen_x.py dimos/msgs/manipulation_msgs/test_grasp_candidate.py -v

Verified: 29 focused tests passed; Ruff and git diff --check passed.

AI assistance

OpenAI Codex with GPT-5 was used extensively for branch extraction, implementation cleanup, verification, and this description.

Checklist

• I have read and approved the CLA.

[codecov]

Codecov Report

❌ Patch coverage is 96.79487% with 10 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
dimos/manipulation/grasping/grasp_gen_x.py	90.82%	6 Missing and 4 partials ⚠️

@@            Coverage Diff             @@
##             main    #3367      +/-   ##
==========================================
+ Coverage   75.75%   75.81%   +0.05%     
==========================================
  Files        1172     1178       +6     
  Lines      113650   113966     +316     
  Branches    10272    10287      +15     
==========================================
+ Hits        86093    86399     +306     
- Misses      24566    24572       +6     
- Partials     2991     2995       +4     

Flag	Coverage Δ
OS-ubuntu-24.04-arm	69.95% <96.79%> (+0.07%)	⬆️
OS-ubuntu-latest	71.96% <96.79%> (+0.06%)	⬆️
Py-3.10	71.95% <96.79%> (+0.07%)	⬆️
Py-3.11	71.95% <96.79%> (+0.06%)	⬆️
Py-3.12	71.94% <96.79%> (+0.06%)	⬆️
Py-3.13	71.95% <96.79%> (+0.07%)	⬆️
Py-3.14	71.95% <96.79%> (+0.06%)	⬆️
Py-3.14t	71.94% <96.79%> (+0.07%)	⬆️
SelfHosted-Large	29.63% <41.02%> (+0.04%)	⬆️
SelfHosted-Linux	35.75% <41.02%> (+0.02%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
dimos/manipulation/grasping/grasp_gen_spec.py	100.00% <100.00%> (ø)
dimos/manipulation/grasping/test_grasp_gen_x.py	100.00% <100.00%> (ø)
dimos/msgs/manipulation_msgs/GraspCandidate.py	100.00% <100.00%> (ø)
...imos/msgs/manipulation_msgs/GraspCandidateArray.py	100.00% <100.00%> (ø)
...mos/msgs/manipulation_msgs/test_grasp_candidate.py	100.00% <100.00%> (ø)
dimos/robot/all_blueprints.py	100.00% <ø> (ø)
dimos/manipulation/grasping/grasp_gen_x.py	90.82% <90.82%> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[greptile-apps]

Greptile Summary

Adds an import-safe GraspGenX proposal provider and typed ranked-grasp messages while retaining the existing grasp orchestration contract during a transition.

• Introduces validated GraspGenX configuration, deferred optional-runtime loading, inference result validation, ranking, and TCP-frame conversion.
• Adds GraspCandidate and GraspCandidateArray message types with focused serialization and provider tests.
• Registers the new module and adds the pinned optional dependency set.

Confidence Score: 4/5

The PR does not appear safe to merge until the new GraspGenX provider is connected to a consumer that uses its ranked proposal contract.

GraspingModule still requests LegacyGraspGenSpec and calls generate_grasps with object and scene clouds, while GraspGenXModule implements only GraspGenSpec.propose_grasps and returns GraspCandidateArray, so the previously reported integration path remains disconnected.

Files Needing Attention: dimos/manipulation/grasping/grasp_gen_spec.py, dimos/manipulation/grasping/grasping.py, dimos/manipulation/grasping/grasp_gen_x.py

Important Files Changed

Filename	Overview
dimos/manipulation/grasping/grasp_gen_spec.py	Splits the legacy PoseArray generator contract from the ranked candidate proposal contract, but the previously reported provider-consumer disconnection remains.
dimos/manipulation/grasping/grasp_gen_x.py	Adds the import-safe GraspGenX adapter, configuration validation, inference checks, candidate ranking, and output conversion.
dimos/manipulation/grasping/grasp_gen_x_runtime.py	Adds the deferred optional runtime boundary, pinned checkpoint acquisition, gripper setup, and tensor conversion.
dimos/manipulation/grasping/grasping.py	Retypes the existing orchestrator dependency to the legacy contract, leaving it unable to consume the new GraspGenX provider.
dimos/msgs/manipulation_msgs/GraspCandidate.py	Adds a finite-score grasp candidate message carrying a TCP pose and ranking score.
dimos/msgs/manipulation_msgs/GraspCandidateArray.py	Adds an ordered, header-bearing collection for ranked grasp candidates.
pyproject.toml	Adds the GraspGenX extra, pinned Git source, compatibility overrides, and type-checker import allowances.
uv.lock	Updates the locked dependency graph for the optional GraspGenX runtime.

_{Reviews (5): Last reviewed commit: "Merge branch 'main' into feat/grasp-02-p..." | Re-trigger Greptile}