griip-core 0.1.0__tar.gz

griip_core-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: griip-core
+Version: 0.1.0
+Summary: GRIIP shared foundation: the griip protobuf contract and shared helpers (transforms, joint math, VRMCS registration), depended on by both the mmai-griip-api server and the griip-sdk client.
+Author: VentionCo
+License: Proprietary
+Requires-Python: <3.11,>=3.10
+Requires-Dist: grpcio>=1.78.0
+Requires-Dist: numpy<2,>=1.24
+Requires-Dist: protobuf>=4.0
+Requires-Dist: spatialmath-python<2.0.0,>=1.1.15

griip_core-0.1.0/README.md

@@ -0,0 +1,38 @@
+# griip-core
+
+Shared foundation for GRIIP, by [Vention](https://vention.io).
+
+Holds the code that both the `mmai-griip-api` server and the `griip-sdk` client
+need. The SDK talks to the API over gRPC, so neither can depend on the other.
+Code both sides need lives here.
+
+## Contents
+
+The proto contract: `proto/griip.proto` and its committed generated stubs
+(`griip_core.generated`). One definition of the five services (`GriipApiAdmin`,
+`PlanningService`, `PerceptionService`, `PickingService`, `PlacingService`), so
+server and client import the same stubs and the wire contract cannot drift.
+
+Shared primitives:
+
+- `utils/transforms.py`: SE3 and rotation-matrix math (`se3_to_pose_list`,
+  `normalize_rotation_matrix_to_se3`, `normalize_rotation_matrix_to_so3`).
+- `utils/joint_math.py`: `normalize_joint_configurations_to_reference`, which
+  wraps joint angles to the value closest to a reference.
+- `hardware/vrmcs_registration.py`: `find_compatible_registration` and
+  `adopt_existing_registration`, which reuse an existing VRMCS robot
+  registration instead of registering again.
+
+That is the whole package. No orchestration, hardware clients, or calibration;
+those stay in `griip-sdk`.
+
+## Proto changes
+
+Edit `proto/griip.proto`, then regenerate the stubs:
+
+```bash
+python scripts/generate_proto.py
+```
+
+CI runs `tools/check-griip-proto-stubs-current.py` and fails if the committed
+stubs are stale.

griip_core-0.1.0/project.json

@@ -0,0 +1,85 @@
+{
+  "name": "griip-core",
+  "$schema": "../../../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "library",
+  "sourceRoot": "projects/physical-ai/libs/griip-core/src",
+  "release": {
+    "version": {
+      "versionActions": "@nxlv/python/release/version-actions"
+    }
+  },
+  "targets": {
+    "generate-proto": {
+      "executor": "@nxlv/python:run-commands",
+      "options": {
+        "command": "uv run python scripts/generate_proto.py",
+        "cwd": "projects/physical-ai/libs/griip-core"
+      }
+    },
+    "proto-check": {
+      "executor": "@nxlv/python:run-commands",
+      "cache": true,
+      "inputs": [
+        "{projectRoot}/proto/griip.proto",
+        "{projectRoot}/scripts/generate_proto.py",
+        "{projectRoot}/src/griip_core/generated/**/*",
+        "{workspaceRoot}/tools/check-griip-proto-stubs-current.py"
+      ],
+      "options": {
+        "command": "uv run python tools/check-griip-proto-stubs-current.py",
+        "cwd": "."
+      }
+    },
+    "test": {
+      "executor": "@nxlv/python:run-commands",
+      "cache": true,
+      "dependsOn": ["proto-check"],
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+      "options": {
+        "commands": [
+          {
+            "command": "PYTHONPATH=./src uv run pytest src/ -v --cov=src/griip_core --cov-report=xml:../../../../coverage/projects/physical-ai/libs/griip-core/coverage.xml --cov-report=html:../../../../coverage/projects/physical-ai/libs/griip-core/html",
+            "forwardAllArgs": false
+          }
+        ],
+        "cwd": "{projectRoot}"
+      }
+    },
+    "lint": {
+      "executor": "@nxlv/python:run-commands",
+      "options": {
+        "command": "uv run ruff check src/",
+        "cwd": "projects/physical-ai/libs/griip-core"
+      }
+    },
+    "format": {
+      "executor": "@nxlv/python:run-commands",
+      "options": {
+        "command": "uv run ruff format src/",
+        "cwd": "projects/physical-ai/libs/griip-core"
+      }
+    },
+    "build": {
+      "executor": "@nxlv/python:build",
+      "outputs": ["{projectRoot}/dist"],
+      "options": {
+        "outputPath": "projects/physical-ai/libs/griip-core/dist",
+        "publish": false,
+        "lockedVersions": false
+      }
+    },
+    "nx-release-publish": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build"],
+      "options": {
+        "command": "npx tsx tools/python-publish-if-not-exists/src/python-publish-if-not-exists.ts --projectRoot={projectRoot} --dryRun={args.dryRun}"
+      }
+    },
+    "upload-codecov": {
+      "executor": "nx:run-commands",
+      "options": {
+        "commands": ["bash tools/codecov-upload.sh griip-core coverage/projects/physical-ai/libs/griip-core/coverage.xml"]
+      }
+    }
+  }
+}

griip_core-0.1.0/proto/griip.proto

@@ -0,0 +1,452 @@
+syntax = "proto3";
+
+package griip;
+
+option java_multiple_files = true;
+option java_package = "com.vention.griip";
+
+// ---------------------------------------------------------------------------
+// GriipApiAdmin
+//
+// One-shot warm-up RPC. The API process starts idle (no yaml on disk, no env
+// var) and rejects Pick/Plan/Place RPCs with UNAVAILABLE until Initialize
+// returns OK. The SDK consumer calls Initialize from its app yaml's cell
+// + active part. Calling Initialize a second time atomically swaps the
+// subsystems for the new config (e.g. switching parts).
+// ---------------------------------------------------------------------------
+
+service GriipApiAdmin {
+  rpc Initialize (InitializeRequest) returns (InitializeResponse);
+  rpc StartPerceptionMcapRecording (StartPerceptionMcapRecordingRequest) returns (StartPerceptionMcapRecordingResponse);
+  rpc StopPerceptionMcapRecording (StopPerceptionMcapRecordingRequest) returns (StopPerceptionMcapRecordingResponse);
+}
+
+message McapRecordingConfig {
+  bool enabled = 1;
+  string output_dir = 2;
+  int32 max_duration_s = 3;
+  string filename_prefix = 4;
+}
+
+message CameraCalibrationInput {
+  repeated double camera_intrinsics = 1;
+  int32 image_width = 2;
+  int32 image_height = 3;
+  string frame_id = 4;
+}
+
+message InitializeRequest {
+  MockConfig mocks = 1;
+  RobotConfig robot = 2;
+  PerceptionServicesConfig perception_services = 3;
+  PlannerConfig planner = 4;
+  GraspFilteringConfig grasp_filtering = 5;
+  PartConfig part = 6;
+  JointAngles home_joint_angles = 7;
+  repeated CollisionLineSegment collision_checking_line_segments = 8;
+  double simulated_delay_seconds = 9;
+  McapRecordingConfig perception_mcap = 10;
+  CameraCalibrationInput camera_calibration = 11;
+}
+
+message InitializeResponse {
+  enum Status {
+    STATUS_UNSPECIFIED = 0;
+    STATUS_OK = 1;
+    STATUS_INVALID_CONFIG = 2;
+    STATUS_BUILD_FAILED = 3;
+  }
+  Status status = 1;
+  string error_message = 2;
+  repeated double tcp_to_flange_offset = 3;
+}
+
+message StartPerceptionMcapRecordingRequest {}
+
+message StartPerceptionMcapRecordingResponse {
+  enum Status {
+    STATUS_UNSPECIFIED = 0;
+    STATUS_OK = 1;
+    STATUS_NOT_INITIALIZED = 2;
+    STATUS_NOT_CONFIGURED = 3;
+  }
+  Status status = 1;
+  string error_message = 2;
+}
+
+message StopPerceptionMcapRecordingRequest {}
+
+message StopPerceptionMcapRecordingResponse {
+  enum Status {
+    STATUS_UNSPECIFIED = 0;
+    STATUS_OK = 1;
+  }
+  Status status = 1;
+  string error_message = 2;
+}
+
+message MockConfig {
+  bool vamp = 1;
+  bool vrmcs_robot = 2;
+  bool collision_model = 3;
+  bool sam = 4;
+  bool foundation_pose = 5;
+  bool foundation_stereo = 6;
+}
+
+message RobotConfig {
+  string model = 1;
+  string driver = 2;
+  string vrmcs_url = 3;
+  string robot_ip = 4;
+  repeated double joint_lower_limits = 5;
+  repeated double joint_upper_limits = 6;
+}
+
+message PerceptionServicesConfig {
+  string sam_url = 1;
+  string foundation_pose_url = 2;
+  string foundation_stereo_url = 3;
+}
+
+message PlannerConfig {
+  string planner_name = 1;
+  int32 max_iterations = 2;
+  int32 max_samples = 3;
+  double range = 4;
+  bool dynamic_domain = 5;
+  double radius = 6;
+  bool start_tree_first = 7;
+  int32 simp_max_iterations = 8;
+}
+
+message GraspFilteringConfig {
+  double aggressive_angle_threshold_bin_floor_degrees = 1;
+  double aggressive_angle_threshold_gravity_axis_degrees = 2;
+}
+
+// `tcp_offset` is the [x,y,z] translation from the flange origin to the TCP;
+// rotation is always identity in current cells, so we send the offset only.
+// `grasp_definitions_json` is the raw contents of the part's grasps_<id>.json
+// (the SDK reads the file locally and inlines it). Polymorphic schema
+// (ExternalJawGrasp / InternalJawGrasp / ...) is preserved without bloating
+// the proto with one field per subclass.
+message PartConfig {
+  string part_id = 1;
+  string part_model_id = 2;
+  repeated double tcp_offset = 3;
+  string grasp_definitions_json = 4;
+  repeated CollisionSpheres held_object_collision_spheres = 5;
+  string mesh_path = 6;
+}
+
+message CollisionLineSegment {
+  repeated double points = 1;
+}
+
+// ---------------------------------------------------------------------------
+// PlanningService
+// ---------------------------------------------------------------------------
+
+service PlanningService {
+  rpc ConfigurePlanner (ConfigurePlannerRequest) returns (ConfigurePlannerResponse);
+  rpc PlanPath (PlanPathRequest) returns (PlanPathResponse);
+}
+
+message ConfigurePlannerRequest {
+  string cuboids_path = 1;
+  string robot_model = 2;
+  string gripper_collision_spheres_path = 3;
+  optional string object_mesh_path = 4;
+  repeated double tcp_to_camera_transform = 5;
+  optional int32 planner_max_iterations = 6;
+  optional double planner_max_cost = 7;
+  repeated CollisionSpheres gripper_collision_spheres = 8;
+}
+
+message ConfigurePlannerResponse {
+  string environment_id = 1;
+  int32 robot_dof = 2;
+  int32 num_cuboids_loaded = 3;
+}
+
+message PlanPathRequest {
+  repeated double start_joint_angles = 1;
+  oneof target {
+    JointAngles target_joint_angles = 2;
+    Pose target_pose = 3;
+  }
+  bool linear = 4;
+  double velocity_scaling = 5;
+  double acceleration_scaling = 6;
+  repeated CollisionSpheres held_object_collision_spheres = 7;
+  repeated CollisionSpheres world_collision_spheres = 8;
+  optional bytes additional_point_clouds = 9;
+  optional double gripper_opening_width = 10;
+  repeated CollisionSpheres gripper_collision_spheres_override = 11;
+  optional bool normalize_to_start = 12;
+  repeated Cuboid cuboids = 13;
+  optional bool cuboids_replace_scene = 14;
+}
+
+message PlanPathResponse {
+  bool success = 1;
+  optional string failure_reason = 2;
+  repeated JointAngles trajectory = 3;
+  optional double planning_time_ms = 4;
+  optional double path_cost = 5;
+}
+
+// ---------------------------------------------------------------------------
+// PerceptionService
+// ---------------------------------------------------------------------------
+
+service PerceptionService {
+  rpc EstimateDepth (EstimateDepthRequest) returns (EstimateDepthResponse);
+  rpc DetectObjects (DetectObjectsRequest) returns (DetectObjectsResponse);
+  rpc EstimatePose (EstimatePoseRequest) returns (EstimatePoseResponse);
+}
+
+message EstimateDepthRequest {
+  bytes left_image = 1;
+  bytes right_image = 2;
+  repeated double camera_intrinsics = 3;
+  double stereo_baseline = 4;
+}
+
+message EstimateDepthResponse {
+  bytes depth_data = 1;
+}
+
+message DetectObjectsRequest {
+  string image_id = 1;
+  bytes color_image = 2;
+  bytes depth_image = 3;
+  repeated double camera_intrinsics = 4;
+  repeated double camera_pose_in_world = 5;
+  repeated BinWall bin_walls = 6;
+  repeated int32 roi = 7;
+}
+
+message DetectObjectsResponse {
+  repeated DetectedObject detections = 1;
+}
+
+message DetectedObject {
+  int32 index = 1;
+  bytes mask_data = 2;
+  int32 mask_height = 3;
+  int32 mask_width = 4;
+  repeated int32 bbox = 5;
+  double score = 6;
+}
+
+message EstimatePoseRequest {
+  string image_id = 1;
+  bytes color_image = 2;
+  bytes depth_image = 3;
+  bytes object_mask = 4;
+  int32 mask_height = 5;
+  int32 mask_width = 6;
+  repeated double camera_intrinsics = 7;
+}
+
+message EstimatePoseResponse {
+  bool success = 1;
+  Pose pose = 2;
+}
+
+// ---------------------------------------------------------------------------
+// PickingService
+// ---------------------------------------------------------------------------
+
+service PickingService {
+  rpc GeneratePicks (GeneratePicksRequest) returns (stream GeneratePicksResponse);
+  rpc ReportSelectedPick (ReportSelectedPickRequest) returns (ReportSelectedPickResponse);
+}
+
+message ReportSelectedPickRequest {
+  string image_id = 1;
+  repeated double object_pose_in_world = 2;
+  repeated double prep_pose = 3;
+  int64 capture_timestamp_ns = 4;
+}
+
+message ReportSelectedPickResponse {
+  bool ok = 1;
+}
+
+message GeneratePicksRequest {
+  string image_id = 1;
+  bytes color_image = 2;
+  bytes depth_image = 3;
+  repeated double camera_intrinsics = 4;
+  repeated double camera_pose_in_world = 5;
+  repeated double tcp_pose_at_capture = 6;
+  JointAngles capture_joint_angles = 7;
+  repeated BinWall bin_walls = 8;
+  int32 max_detections = 9;
+  int32 max_picks_per_object = 10;
+  BinWall bin_floor = 11;
+  repeated int32 roi = 12;
+  int64 capture_timestamp_ns = 13;
+  // Per-phase end-effector collision spheres (flange frame), generated by the
+  // SDK's collision model. prep: all spheres, fingers closed. plunge: all
+  // spheres, fingers opened. scoop: all except fingertips, fingers opened.
+  // Empty => fall back to the spheres configured via ConfigurePlanner.
+  repeated CollisionSpheres prep_gripper_collision_spheres = 14;
+  repeated CollisionSpheres plunge_gripper_collision_spheres = 15;
+  repeated CollisionSpheres scoop_gripper_collision_spheres = 16;
+}
+
+message GeneratePicksResponse {
+  oneof payload {
+    PickResultMessage pick_result = 1;
+    PickTerminalMessage terminal_message = 2;
+  }
+}
+
+message PickResultMessage {
+  int32 pick_id = 1;
+  string grasp_name = 2;
+  repeated double object_pose_in_world = 4;
+  repeated double object_in_tcp = 5;
+  repeated double prep_pose = 6;
+  repeated double plunge_pose = 7;
+  repeated double scoop_pose = 8;
+  repeated JointAngles prep_trajectory = 9;
+  int32 priority = 10;
+  double distance_to_home = 11;
+  double retract_move_distance = 12;
+  int32 detected_object_index = 16;
+  oneof executor_params {
+    ParallelJawParams parallel_jaw = 20;
+    SuctionParams suction = 21;
+    ThreeFingerParams three_finger = 22;
+  }
+}
+
+enum GraspMode {
+  GRASP_MODE_EXTERNAL = 0;
+  GRASP_MODE_INTERNAL = 1;
+}
+
+message ScoopMotionParams {
+  double plunge_velocity = 1;
+  double scoop_velocity = 2;
+  double force_torque_sensor_threshold = 3;
+}
+
+message ParallelJawParams {
+  GraspMode mode = 1;
+  int32 prep_width = 2;
+  int32 engaged_width = 3;
+  int32 grip_force = 4;
+  int32 grip_check_min_width = 5;
+  int32 grip_check_max_width = 6;
+  ScoopMotionParams scoop_motion = 7;
+}
+
+message SuctionParams {
+  double vacuum_engage_threshold = 1;
+  ScoopMotionParams scoop_motion = 2;
+}
+
+message ThreeFingerParams {
+  GraspMode mode = 1;
+  int32 grip_force = 2;
+  ScoopMotionParams scoop_motion = 3;
+  // IO-backed three-finger grippers (e.g. OnRobot 3FG15). When set, the SDK
+  // uses IOThreeFingerExecutor instead of the width-based ThreeFingerExecutor.
+  int32 prep_io_state = 4;
+  int32 engaged_io_state = 5;
+}
+
+message PickTerminalMessage {
+  bool no_parts_detected = 1;
+  int32 total_picks_generated = 2;
+  bool has_only_ungraspable_objects = 3;
+}
+
+// ---------------------------------------------------------------------------
+// PlacingService
+// ---------------------------------------------------------------------------
+
+service PlacingService {
+  rpc GeneratePlacement (GeneratePlacementRequest) returns (GeneratePlacementResponse);
+}
+
+message GeneratePlacementRequest {
+  string image_id = 1;
+  bytes left_png = 2;
+  bytes depth_png = 3;
+  repeated double camera_intrinsics = 4;
+  repeated double tcp_to_camera = 5;
+  repeated double object_in_tcp = 6;
+  repeated double target_pose = 7;
+  repeated double planning_start_joint_angles = 8;
+  double max_object_diameter = 9;
+  repeated double axis_in_object_frame = 10;
+  int32 number_of_rotations = 11;
+  bool enable_in_hand_pose_estimation = 12;
+}
+
+message GeneratePlacementResponse {
+  bool success = 1;
+  optional string failure_reason = 2;
+  repeated double refined_object_in_tcp = 3;
+  repeated PlacementIkSolution ik_solutions = 4;
+}
+
+message PlacementIkSolution {
+  repeated double joint_angles = 1;
+  repeated double target_object_pose_in_world = 2;
+  double distance_to_start = 3;
+}
+
+// ---------------------------------------------------------------------------
+// Reusable sub-messages
+// ---------------------------------------------------------------------------
+
+message JointAngles {
+  repeated double values = 1;
+}
+
+message Quaternion {
+  double w = 1;
+  double x = 2;
+  double y = 3;
+  double z = 4;
+}
+
+message Vector3 {
+  double x = 1;
+  double y = 2;
+  double z = 3;
+}
+
+message Pose {
+  Vector3 position = 1;
+  Quaternion orientation = 2;
+}
+
+message CollisionSpheres {
+  Vector3 center = 1;
+  double radius = 2;
+}
+
+message BinWall {
+  string name = 1;
+  double width_x = 2;
+  double width_y = 3;
+  double width_z = 4;
+  repeated double pose = 5;
+}
+
+message Cuboid {
+  string name = 1;
+  double wx = 2;
+  double wy = 3;
+  double wz = 4;
+  repeated double pose = 5;
+}

griip_core-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+dependency-groups = { }
+
+[project]
+name = "griip-core"
+version = "0.1.0"
+description = "GRIIP shared foundation: the griip protobuf contract and shared helpers (transforms, joint math, VRMCS registration), depended on by both the mmai-griip-api server and the griip-sdk client."
+requires-python = ">=3.10,<3.11"
+dependencies = [
+  "grpcio>=1.78.0",
+  "protobuf>=4.0",
+  "numpy>=1.24,<2",
+  "spatialmath-python>=1.1.15,<2.0.0"
+]
+
+  [[project.authors]]
+  name = "VentionCo"
+
+  [project.license]
+  text = "Proprietary"
+
+[build-system]
+requires = [ "hatchling" ]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = [ "src/griip_core" ]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.ruff]
+line-length = 140
+extend-exclude = [ "src/griip_core/generated" ]
+
+[tool.pytest.ini_options]
+testpaths = [ "src" ]

griip_core-0.1.0/scripts/generate_proto.py

@@ -0,0 +1,70 @@
+"""Generate Python gRPC stubs from proto/griip.proto.
+
+griip-core is the single source of truth for the 'griip' wire contract. Both
+the mmai-griip-api server and the griip-sdk client depend on griip-core and
+import these stubs, so only one descriptor set is ever registered.
+
+The generated stubs are committed so the published griip-core wheel ships them
+and resolves standalone. CI guards against stale stubs via
+tools/check-griip-proto-stubs-current.py.
+
+Usage:
+    python scripts/generate_proto.py
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+PROTO_DIR = PROJECT_ROOT / "proto"
+PROTO_FILE = PROTO_DIR / "griip.proto"
+OUT_DIR = PROJECT_ROOT / "src" / "griip_core" / "generated"
+
+
+def _fix_imports(directory: Path) -> None:
+    """Rewrite absolute proto imports to relative imports so they work inside a package."""
+    for py_file in directory.glob("*_pb2_grpc.py"):
+        content = py_file.read_text()
+        fixed = re.sub(r"^import (\w+_pb2) as", r"from . import \1 as", content, flags=re.MULTILINE)
+        if fixed != content:
+            py_file.write_text(fixed)
+            print(f"  Fixed imports in {py_file.name}")
+
+
+def main() -> None:
+    OUT_DIR.mkdir(parents=True, exist_ok=True)
+
+    cmd = [
+        sys.executable,
+        "-m",
+        "grpc_tools.protoc",
+        f"--proto_path={PROTO_DIR}",
+        f"--python_out={OUT_DIR}",
+        f"--grpc_python_out={OUT_DIR}",
+        f"--pyi_out={OUT_DIR}",
+        f"--mypy_grpc_out={OUT_DIR}",
+        str(PROTO_FILE),
+    ]
+
+    print(f"Running: {' '.join(cmd)}")
+    result = subprocess.run(cmd, capture_output=True, text=True)
+
+    if result.returncode != 0:
+        print(f"protoc failed:\n{result.stderr}", file=sys.stderr)
+        sys.exit(result.returncode)
+
+    _fix_imports(OUT_DIR)
+
+    init_file = OUT_DIR / "__init__.py"
+    if not init_file.exists():
+        init_file.touch()
+
+    print(f"Generated stubs in {OUT_DIR}")
+
+
+if __name__ == "__main__":
+    main()