[RLlib] Overhaul of the typing module & better device typing

[Daraan]

Resolves: #55288 (wrong np.array in TensorType)

Furthermore changes:

• Changed comments to (semi)docstring which will be displayed as tooltips by IDEs (e.g. VSCode + Pylance) making that information available to the user.
• AgentID: Any -> Hashable as it used for dict keys
• changed DeviceType to be not a TypeVar (makes no sense in the way it is currently used), also includes DeviceLikeType (int | str | device) from torch. IMO it can fully replace the current type but being defensive I only added it as an extra possible type
• Used updated DeviceType to improve type of Runner._device and make it more correct
• Used torch's own type in data, current code supports more than just str. I refrained from adding a reference to rllib despite it being nice if they would be in sync.
• Some extra formatting that is forced by pre-commit

---

Note

Revamps rllib.utils.typing (NDArray-based TensorType, broader DeviceType, AgentID as Hashable, docstring cleanups) and updates call sites to use optional device typing and improved hints.

• Types:
  • Overhaul rllib/utils/typing.py:
    • TensorType now uses numpy.typing.NDArray; heavy use of TYPE_CHECKING to avoid runtime deps on torch/tf/jax.
    • DeviceType widened to Union[str, torch.device, int] (was TypeVar).
    • AgentID tightened to Hashable; NetworkType uses keras.Model.
    • Refined aliases (e.g., FromConfigSpec, SpaceStruct) and added concise docstrings.
• Runners:
  • Runner._device now Optional (Union[DeviceType, None]) with updated docstring; same change in offline runners’ _device properties.
• Connectors:
  • NumpyToTensor: device param typed as Optional[DeviceType] (via TYPE_CHECKING).
• Utils:
  • from_config: typed config: Optional[FromConfigSpec] with TYPE_CHECKING import.
• Misc:
  • Minor formatting/import ordering and comment typo fixes.

^{Written by Cursor Bugbot for commit ae2e422. This will update automatically on new commits. Configure here.}

[gemini-code-assist]

Summary of Changes

Hello @Daraan, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

I've made significant updates to RLlib's typing module, focusing on improving type accuracy and consistency, particularly for device handling. This includes resolving an issue with np.array in TensorType, refining AgentID and DeviceType definitions, and enhancing device type annotations across the codebase, especially within ray.data and RLlib's Runner classes.

Highlights

• Refined RLlib Typing: Overhauled the rllib/utils/typing.py module to improve type definitions for tensors, networks, and devices, making them more robust and explicit.
• Enhanced Device Typing: Updated DeviceType to be a Union of str, torch.device, and torch._prims_common.DeviceLikeType, providing more comprehensive device type support.
• Corrected TensorType: Fixed an incorrect np.array reference in TensorType to use numpy.typing.NDArray, ensuring proper NumPy array type hinting.
• Improved AgentID Definition: Changed AgentID from Any to Hashable to accurately reflect its usage as a dictionary key.
• Consistent Device Usage in Ray Data: Integrated torch's DeviceLikeType into ray.data's iter_torch_batches function for more precise device parameter typing.
• Clarified Runner Device Property: Modified the _device property in RLlib's Runner classes to explicitly allow None, indicating cases where a device might not be supported or set.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments or fill out our survey to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request provides a significant overhaul of the typing in rllib/utils/typing.py and improves device typing across ray.data and rllib. The changes are excellent, enhancing the correctness and clarity of type hints. Key improvements include correcting TensorType to use NDArray, fixing DeviceType from an incorrect TypeVar to a Union, and making AgentID more specific. The addition of docstrings to many type aliases is also a valuable documentation improvement. I have a couple of suggestions to make the docstrings for TensorType and DeviceType even more consistent with their type hints. Overall, this is a solid contribution.

[github-actions]

This pull request has been automatically marked as stale because it has not had
any activity for 14 days. It will be closed in another 14 days if no further activity occurs.
Thank you for your contributions.

You can always ask for help on our discussion forum or Ray's public slack channel.

If you'd like to keep this open, just leave any comment, and the stale label will be removed.

[Daraan]

Follow up PRs:

• [air] [air] Upgrade and unify device types with dataset.TorchDeviceType #56745
• [data] [data] Small (typing) overhaul of valid torch device types #56743

[Daraan]

@kamil-kaczmarek the failing test / example is not related to this PR right? Hard to tell from the (missing) logs, locally it is fine for me.

[kamil-kaczmarek]

@Daraan yes, we're currently fixing an upstream issue. Fix will unblock this PR.

[pseudo-rnd-thoughts]

@Daraan We have fixed the upstream issue, could you resolve the merge conflict then we can hopefully merge the PR