Add move_through_joint_positions and get_3d_models to Arm (BREAKING)

[Nick Hehr (HipsterBrown)]

⚠️ Breaking change — requires a release note

Arm now declares two new @abc.abstractmethods. Every existing third-party arm module will fail at startup until it implements both:

TypeError: Can't instantiate abstract class MyArm with abstract methods
get_3d_models, move_through_joint_positions

This is not a deprecation or a runtime warning — the module does not start. The release carrying this needs an explicit upgrade note, since the TypeError gives module authors no hint about what to implement.

Abstract (rather than concrete-raising-MethodNotImplementedError) was a deliberate choice for consistency with the other seven Arm methods.

Summary

Brings the Python SDK's Arm to RPC parity with the Go SDK (rdk) by implementing the two arm RPCs the SDK did not expose:

• move_through_joint_positions(positions, options=None, ...) — executes a multi-waypoint joint trajectory under optional kinematic ceilings (MoveOptions). Previously the only way to do this from Python was a move_to_joint_positions loop with no velocity or acceleration control.
• get_3d_models() -> Mapping[str, Mesh] — retrieves the arm's 3D meshes.

Both are implemented across all three layers (ABC, ArmRPCService, ArmClient), plus all seven in-repo Arm subclasses. MoveOptions and Mesh are now re-exported from viam.components.arm.

No proto regeneration — the generated stubs and types already existed. src/viam/gen/** and src/viam/proto/** are untouched.

Coverage before/after

RPC	proto	Go RDK	Python (before)	Python (after)
GetEndPosition, MoveToPosition, GetJointPositions, MoveToJointPositions, Stop, IsMoving, DoCommand, GetStatus, GetKinematics, GetGeometries	✅	✅	✅	✅
MoveThroughJointPositions	✅	✅	❌	✅
Get3DModels	✅	✅	❌	✅
MoveThroughJointPositionsStreamed	✅	❌	❌	❌ (intentional)

Notes for reviewers

MoveOptions presence is two levels deep. The options field has explicit presence, so the service branches on request.HasField("options") — without it, a caller who omitted options would hand the driver a zeroed MoveOptions, and max_vel_degs_per_sec == 0.0 could be misread as "do not move" rather than "no limit requested". The scalars inside MoveOptions have presence too, so the ABC docstring directs implementers to check options.HasField(...) per field. It also documents the proto's precedence rule (max_vel_degs_per_sec is ignored when max_vel_degs_per_sec_joints is set), which nothing else in the SDK surfaced.

get_3d_models returns dict(response.models), not the raw container. Protobuf map fields mimic C++ semantics — __getitem__ on a missing key default-constructs and inserts rather than raising KeyError. Returning the live container would mean models["gripper_link"] on an absent link yields an empty Mesh and silently grows the caller's mapping, breaking the declared Mapping[str, Mesh] contract. A test pins the KeyError.

No client-side joint-limit validation, unlike Go. rdk's client calls Kinematics() and runs checkDesiredJointPositions before every MoveThroughJointPositions. Python has no equivalent of referenceframe.Model — get_kinematics() returns raw URDF/SVA bytes with no parser — so there is nothing to validate against. The asymmetry is documented in the ABC docstring's Note:: the Go client refuses out-of-limit waypoints, the Python client forwards them to the driver. Adding a parser is its own project.

MoveThroughJointPositionsStreamed deliberately left unimplemented — it exists in the generated stubs but is implemented in neither rdk nor here.

Known follow-up (not in this PR)

get_kinematics returns response.meshes_by_urdf_filepath — the same live protobuf container, with the same missing-key auto-insert bug described above. Pre-existing, so it was left out of scope here, but it warrants a separate fix.

Test Plan

• make test — 876 passed, 0 failed (includes tests/test_examples.py, which launches the server and complex_module example modules)
• make typecheck — 0 errors (1 pre-existing warning in src/viam/module/types.py)
• make lint / make format — clean, 301 files
• git diff --stat -- src/viam/gen src/viam/proto — empty
• Arm.__abstractmethods__ contains both new methods; ArmClient.__abstractmethods__ is empty
• End-to-end over ChannelFor: waypoints and MoveOptions round-trip intact; omitted options arrive as None rather than zeroed; get_3d_models returns a real dict that raises KeyError without inserting
• All seven Arm subclasses instantiate — verified in subprocesses for the example/docs arms, which no lint, typecheck, or test covers
• docs/examples/example.ipynb — valid JSON, cell sources still list-of-lines, embedded MyModularArm parses

10 new tests across TestArm, TestService, and TestClient.

🤖 Generated with Claude Code

https://claude.ai/code/session_015RbNNgUjePEdPuUGAdU3qb

[github-actions]

Warning your change may break code samples. If your change modifies any of the following functions please contact @viamrobotics/fleet-management. Thanks!

component	function
base	is_moving
board	gpio_pin_by_name
button	push
genericcomponent	do_command
camera	get_images
encoder	get_position
motor	is_moving
sensor	get_readings
servo	get_position
switch	get_position
arm	get_end_position
gantry	get_lengths
gripper	is_moving
movement_sensor	get_linear_acceleration
input_controller	get_controls
audio	get_properties
pose_tracker	get_poses
power_sensor	get_power
motion	get_pose
vision	get_properties
mlmodel	metadata
genericservice	do_command
slam	get_point_cloud_map
audio_in	get_properties
audio_out	get_properties

[viambot]

👋 Thanks for requesting a review from the team!

We aim to review PRs within one business day. If this is urgent
or blocking you, please reach out in #team-sdk and
we'll prioritize it.