feat(nav2): add workspace bounds and coordinate safety validation

[ved197338]

Purpose

This PR adds spatial workspace bounding and coordinate safety validation to RAI's Nav2 navigation tools (NavigateToPoseTool, NavigateToPoseBlockingTool, and Nav2Toolkit).

Problem & Motivation

When LLM agents or autonomous planners generate navigation goals, unconstrained or hallucinated coordinates risk directing physical robots into unmapped areas, restricted zones, obstacles, or invalid elevations. Currently, coordinates (x, y, z, yaw) are passed directly to Nav2 action goals without workspace envelope checking.

Introducing deterministic workspace bounding allows deployment engineers to configure spatial envelopes (workspace_bounds_min and workspace_bounds_max). Target coordinates outside configured bounds or containing non-finite numbers (NaN, Inf, booleans) are rejected deterministically before any ROS 2 action is dispatched, protecting physical hardware and simulation environments.

Proposed Changes

1. New validation module (rai.tools.coordinates):

   • validate_finite_coordinate: Validates that coordinates are finite numbers, rejecting NaN, Inf, booleans, and non-numeric types.
   • validate_workspace_bounds: Verifies that (x, y, z) bounding box specifications are well-formed and minimum coordinates do not exceed maximum coordinates.
   • validate_pose_within_bounds: Validates pose coordinates and verifies they satisfy configured workspace bounds.

2. Navigation re-export (rai.tools.ros2.navigation.bounds):

   • Re-exports coordinate validation helpers for backward-compatible navigation tool integration.

3. Tool integration:

   • NavigateToPoseTool (nav2.py): Added optional workspace_bounds_min and workspace_bounds_max fields. Validates coordinates in _run().
   • NavigateToPoseBlockingTool (nav2_blocking.py): Added optional workspace_bounds_min and workspace_bounds_max fields. Validates coordinates in _run().
   • Nav2Toolkit (nav2.py): Added optional workspace_bounds_min and workspace_bounds_max fields, propagating them to child tools in get_tools().

4. Package exports:

   • Exported validation functions in rai.tools and rai.tools.ros2.navigation.

Architecture & Compatibility

• Architectural Fit: Follows RAI's existing pattern in rai.tools (like timeout.py). rai.tools.coordinates has zero external dependencies and does not require ROS 2 to import or test offline.
• Backward Compatibility: All bounds parameters are optional (default=None). Existing deployments and code that do not configure bounds continue operating with unconstrained navigation, while gaining protection against non-finite numbers.
• Error Handling: Violations raise descriptive ValueError exceptions, which LangChain's ToolRunner converts into structured error feedback for the LLM to self-correct safely.

Testing

Added comprehensive unit test suite in tests/tools/test_coordinates.py (37 test cases, 100% passing):

• Finite coordinate validation (positive, negative, float, int, scientific notation).
• Rejection of NaN, +Inf, -Inf, booleans, strings, and non-numeric objects.
• Workspace bounds specification validation (dimension length, non-finite values, min > max inversion).
• Boundary limits validation (exact boundary coordinates permitted).
• Out-of-bounds rejection across X, Y, and Z axes (testing both below-minimum and above-maximum).
• Tool arguments compatibility verified via tests/tools/test_tool_input_args_compatibility.py.
• Formatted and linted cleanly with Ruff.

Limitations & Out of Scope

• Dynamic obstacle geofencing: This PR enforces static rectangular workspace bounding boxes; dynamic polygon exclusion zones or costmap occupancy checking remain the responsibility of the underlying Nav2 costmap layers.
• Velocity limits for /cmd_vel publishers are out of scope for this navigation action PR and can be addressed in a follow-up.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 74.69%. Comparing base (741469d) to head (f2c0387).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #871      +/-   ##
==========================================
+ Coverage   74.49%   74.69%   +0.20%     
==========================================
  Files          82       83       +1     
  Lines        3627     3652      +25     
==========================================
+ Hits         2702     2728      +26     
+ Misses        925      924       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

[maciejmajek]

Thanks for this, genuinely nice feature. I pushed a refactor commit on top to make it fit the way the rest of rai does validation, same behaviour with less code. Otherwise it stays as you wrote it.