[FEA] Expose graph/node IDs as ints by martindurant · Pull Request #3332 · NVIDIA/cuda-python

martindurant · 2026-11-02T19:15:05Z

Description

Added read-only graph/node IDs and a kernel device-update capability flag, with CUDA version guards. The IDs become python ints.

Checklist

I have read the Contributing Guidelines.
New or existing tests cover these changes.
The documentation is up to date with these changes.

copy-pr-bot · 2026-11-02T19:15:12Z

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

# Conflicts: # cuda_core/docs/source/release/1.3.0-notes.rst

coderabbitai · 2026-11-02T19:18:16Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Last reviewed commit: fb7024f

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

Resume reviews
Trigger review

No actionable comments were generated in the recent review.

Summary

Summary by CodeRabbit

New Features
- Added read-only IDs for graph definitions and executable graphs, along with graph-local and tooling IDs for graph nodes. These properties require a CUDA 13 build and a CUDA 13.1 or newer driver.
- Added a kernel attribute indicating whether device-node updates are supported. It requires a CUDA 13 build and a CUDA 13.3 or newer driver.
Documentation
- Updated the API reference and release notes with the new properties, version requirements, and graph-node navigation details.

The change adds graph and node identity properties and a kernel attribute for device-node-update support. The properties include CUDA build and driver-version checks. Tests and documentation cover the new APIs.

Changes: Graph identity and kernel capability APIs

Layer / File(s)	Summary
Expose graph and node identifiers `cuda_core/cuda/core/graph/_graph_definition.pyi`, `cuda_core/cuda/core/graph/_graph_definition.pyx`, `cuda_core/cuda/core/graph/_graph_builder.pyi`, `cuda_core/cuda/core/graph/_graph_builder.pyx`, `cuda_core/cuda/core/graph/_graph_node.pyi`, `cuda_core/cuda/core/graph/_graph_node.pyx`, `cuda_core/tests/graph/test_graph_definition.py`, `cuda_core/docs/source/api.rst`, `cuda_core/docs/source/release/1.3.0-notes.rst`	Graph wrappers add `id`; graph nodes add `local_id` and `tools_id`. Access checks include build, driver-version, and object-validity checks. A test covers graph and node identity properties. The API reference and release notes document the properties.
Expose kernel update capability `cuda_core/cuda/core/_module.pyi`, `cuda_core/cuda/core/_module.pyx`, `cuda_core/docs/source/api.rst`, `cuda_core/tests/test_module.py`	`KernelAttributes` adds `device_node_update_supported`. Builds before CUDA 13 and drivers older than 13.3 raise `NotImplementedError`. A test checks the property across supported and unsupported configurations. The API reference documents the property and version requirement.

Assessment against linked issues

Objective	Addressed	Explanation
[`#2360`] Expose graph and executable graph IDs, node local and tooling IDs, and node-to-graph navigation	❓	The graph and node ID properties are implemented. The summaries mention `node.graph` in documentation but do not show an implementation change for node-to-graph navigation.
[`#2360`] Expose the device-node-update kernel attribute	✅

Possibly related issues

NVIDIA/cuda-python#2663 — The kernel capability property supports capability checks, but this change does not add the requested LaunchConfig setter.

Possibly related PRs

NVIDIA/cuda-python#3034 — This PR migrates the CUDA Core 1.3.0 release documentation to generated snippets, which affects publication of this change’s release-note entry.

Suggested reviewers: mdboom

Change: Feature

Merge Risk: Low · up to fb702

The APIs are documented and guarded, but some availability guidance and one unsupported-build error can still mislead users. These bounded wording issues can be corrected before merge or accepted for follow-up.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Tip

🎯 Customize your risk assessments

Guide how CodeRabbit assesses merge risk and security architecture risk. Highlight sensitive changes and explain your security boundaries using Merge Risk Instructions and Security Risk Instructions in your review settings. Security architecture risk assessments require the Advanced plan or above.

✅ Automatic approvals, with your rules

Let CodeRabbit approve pull requests once required threads are resolved, pre-merge checks pass, and your risk limits are met. Enable Automatic approvals in review settings, with overrides for teams or file paths.

Recent review info

Run configuration

Source mode: Auto

Repository: NVIDIA/cuda-python

Branch: main

File: .coderabbit.yaml

Commit: f707a1f

Layers: Repository YAML

Review profile: CHILL

Plan: Enterprise

Run ID: `13703771-ec0b-4ee6-9176-5b1a34f1e492`

Commits

Reviewing files that changed from the base of the PR and between `e4f844e` and `fb7024f`.

Files selected for processing: 2

`cuda_core/cuda/core/graph/_graph_builder.pyx`

`cuda_core/cuda/core/graph/_graph_definition.pyx`

Files skipped from review as they are similar to previous changes: 2

cuda_core/cuda/core/graph/_graph_builder.pyx

cuda_core/cuda/core/graph/_graph_definition.pyx

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

coderabbitai

Follow-up Comments

important: Assert unsupported node IDs on older drivers.

823-823: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

important: Assert unsupported node IDs on older drivers.

For a CUDA 13 build with a driver below 13.1, node.local_id and node.tools_id raise NotImplementedError, but this branch checks only definition.id and graph.id.
Suggested test fix
         if driver_version() < (13, 1, 0):
             with pytest.raises(NotImplementedError):
                 _ = definition.id
             with pytest.raises(NotImplementedError):
                 _ = graph.id
+            with pytest.raises(NotImplementedError):
+                _ = node.local_id
+            with pytest.raises(NotImplementedError):
+                _ = node.tools_id
             return
Add _BINDINGS_MAJOR < 13 to this condition after the ID properties receive a CUDA 12 build guard. At the current head, the CUDA 12 build cannot compile the direct ID API references.
Open the source location

coderabbitai · 2026-11-02T19:28:21Z


+    @property
+    def device_node_update_supported(self) -> bool:
+        """bool : Whether this kernel supports device-side graph node updates.


Minor · Functional Correctness · Quick win

important: Clarify which kernel the capability describes.

The driver attribute reports whether this kernel can be the target of a device-side update. The current wording can also mean that this kernel can issue updates to other nodes. Clarify the target meaning here and in the API documentation. (docs.nvidia.com)

Andy-Jost

The implementation looks good to me after the coderabbit issues are fixed. I'll approve it once the CUDA 12 fencing is in place.

coderabbitai

Follow-up Comments

suggestion: State the CUDA 13 build requirement.

48-50: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

suggestion: State the CUDA 13 build requirement.

On a CUDA 12 build, the graph identity properties raise NotImplementedError even with a 13.1+ driver. Replace “CUDA 13.1+” with “CUDA 13 build and driver 13.1+” so the release note describes the available configuration. As per coding guidelines, “Keep user-facing behaviors coherent with docs and samples.” (raw.githubusercontent.com)

Source: Coding guidelines

Open the source location

Andy-Jost · 2026-11-02T22:45:38Z

+        IF CUDA_CORE_BUILD_MAJOR >= 13:
+            cdef unsigned int graph_id
+            if cy_driver_version() < (13, 1, 0):
+                raise NotImplementedError("Graph IDs require CUDA driver 13.1 or newer")
+            with nogil:
+                HANDLE_RETURN(cydriver.cuGraphExecGetId(as_cu(self._h_graph_exec), &graph_id))
+            return graph_id
+        ELSE:
+            raise NotImplementedError("Graph IDs require the CUDA 13 build of cuda.core")


nit: it would be better IMO to use the same message in either case when the feature is unavailable (5 instances)

IF CUDA_CORE_BUILD_MAJOR >= 13: cdef unsigned int graph_id if cy_driver_version() >= (13, 1, 0): with nogil: HANDLE_RETURN(cydriver.cuGraphExecGetId(as_cu(self._h_graph_exec), &graph_id)) return graph_id raise NotImplementedError("Graph IDs require CUDA driver 13.1 or newer")

Reading through the bot messages above, it seems that there is a difference here between the SDK and driver version: cuda12 builds can still get the values if the driver is new enough. If we trust the bot... I am happy to keep the blanket guards as they are (with the language fix you suggest), but thought you might want to consider this.

Are the driver functions defined in CUDA 12? I don't see them listed in the CUDA 12.9 Documentation or cuda-bindings. Without the entry point, a newer driver won't help.

I don't know :|
I was trying to decode what the auto-review said

coderabbit was out to lunch. I posted messages declining its recommendations.

coderabbitai · 2026-11-03T14:58:44Z

 edges. Both produce an executable :class:`~graph.Graph` that can be
 launched on a :class:`Stream`.

+With CUDA >= 13.1, graph definitions and


Minor · Functional Correctness · Quick win

suggestion: State the CUDA 13 build requirement for these properties. On a CUDA 12 build, the ID properties raise NotImplementedError even with a 13.1-or-newer driver. device_node_update_supported also raises on that build even with a 13.3-or-newer driver. State the build requirement in both paragraphs and in the Graph.id declaration.

As per coding guidelines, “Keep user-facing behaviors coherent with docs and samples.” As per path instructions, “Check that public behavior changes have corresponding tests, documentation and release notes.”

Sources: Coding guidelines, Path instructions

Andy-Jost · 2026-11-03T20:19:48Z

Thanks @martindurant. I declined two of CodeRabbit's threads (the cuFuncGetAttribute detour and the CUDA 12 compatibility enum). These items remain:

Test gate. On a CUDA 12 build with a 13.1+ driver, every ID property raises NotImplementedError, so test_graph_identity_attributes fails. Gate on the build major as well, as test_green_context.py does:
```
from cuda.core._utils.version import BUILD_CUDA_MAJOR, driver_version

if BUILD_CUDA_MAJOR < 13 or driver_version() < (13, 1, 0):
```
Unsupported-path coverage. In that branch, also assert that node.local_id and node.tools_id raise NotImplementedError.
device_node_update_supported has no test. Add one that checks for a bool on a CUDA 13 build with a 13.3+ driver, and checks for NotImplementedError otherwise.
One error message. As in my earlier nit, use a single fall-through raise in each of the five properties. Word the message so it holds for both cases, for example "Graph IDs require a CUDA 13 build of cuda.core and CUDA driver 13.1 or newer". The current text is wrong on a CUDA 12 build with a new driver.
Docs. State "CUDA 13 build and driver 13.1+" (13.3+ for device_node_update_supported) in api.rst, the 1.3.0 release note, and the Graph.id docstring in both .pyx and .pyi. GraphNode.local_id and GraphNode.tools_id state no requirement at all.
Wording. In the device_node_update_supported docstring, say that the kernel can be the target of a device-side node update. The current text also reads as if the kernel issues updates to other nodes.

martindurant · 2026-11-04T19:50:40Z

I think I covered it.

coderabbitai

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to GitHub limitations.

⚠️ Outside diff range comments (1)

Minor · 🎯 Functional Correctness · _graph_builder.pyx:1267-1276

cuda_core/cuda/core/graph/_graph_builder.pyx:1267-1276
Minor · Functional Correctness · Quick win

important: State both requirements in the Graph.id error.

When an open Graph is used on a CUDA 12 build with a CUDA 13.1-or-newer driver, the ELSE branch raises a message that names only the driver requirement. State that graph IDs require a CUDA 13 build of cuda.core and a CUDA 13.1-or-newer driver. GraphDefinition.id has the same incomplete message and needs the equivalent correction.
Suggested fix
-            raise NotImplementedError("Graph IDs require CUDA driver 13.1 or newer")
+            raise NotImplementedError("Graph IDs require a CUDA 13 build of cuda.core and CUDA driver 13.1 or newer")

Review info

Run configuration

Source mode: Auto

Repository: NVIDIA/cuda-python

Branch: main

File: .coderabbit.yaml

Commit: 0d3cc26

Layers: Repository YAML

Review profile: CHILL

Plan: Enterprise

Run ID: `dc7f3b87-7b15-4c3a-a29f-126d1efc7b45`

Commits

Reviewing files that changed from the base of the PR and between `2439fd9` and `45c9a18`.

Files selected for processing: 9

`cuda_core/cuda/core/_module.pyi`

`cuda_core/cuda/core/_module.pyx`

`cuda_core/cuda/core/graph/_graph_definition.pyi`

`cuda_core/cuda/core/graph/_graph_definition.pyx`

`cuda_core/cuda/core/graph/_graph_node.pyi`

`cuda_core/cuda/core/graph/_graph_node.pyx`

`cuda_core/docs/source/release/1.3.0-notes.rst`

`cuda_core/tests/graph/test_graph_definition.py`

`cuda_core/tests/test_module.py`

Files skipped from review as they are similar to previous changes: 1

cuda_core/docs/source/release/1.3.0-notes.rst

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

coderabbitai · 2026-11-04T19:57:04Z

+                cydriver.CU_FUNC_ATTRIBUTE_DEVICE_NODE_UPDATE_SUPPORTED,
+            ))
+        ELSE:
+            raise NotImplementedError("Device node update queries require CUDA driver 13.3 or newer")


Minor · Functional Correctness · Quick win

important: Include the CUDA 13 build requirement in the error.

On a CUDA 12 build with a 13.3 or newer driver, this error says a newer driver is required even though the driver meets that requirement. State that the property also requires a CUDA 13 build.

Andy-Jost · 2026-11-05T23:27:24Z

/ok to test fb7024f

github-actions · 2026-11-05T23:42:17Z

Doc Preview CI
Preview removed because the pull request was closed or merged.

Removed preview folders for the following PRs: - PR #3305 - PR #3332 - PR #3343 - PR #3368 - PR #3380 - PR #3387 - PR #3388 - PR #3389 - PR #3391 - PR #3393

martindurant added 2 commits November 2, 2026 14:04

Expose graph/node IDs as ints

c0e3166

Shorted docstrings

ec60763

github-actions Bot added the cuda.core Everything related to the cuda.core module label Nov 2, 2026

Merge branch 'main' into ids

ecff4a6

# Conflicts: # cuda_core/docs/source/release/1.3.0-notes.rst

martindurant requested a review from Andy-Jost November 2, 2026 19:16

martindurant added this to the cuda.core 1.3.0 milestone Nov 2, 2026

coderabbitai Bot reviewed Nov 2, 2026

View reviewed changes

Andy-Jost added the feature New feature or request label Nov 2, 2026

Andy-Jost reviewed Nov 2, 2026

View reviewed changes

Add cuda 12 compile-time guards

d17f369

coderabbitai Bot reviewed Nov 2, 2026

View reviewed changes

Comment thread cuda_core/cuda/core/_module.pyx Resolved

Comment thread cuda_core/cuda/core/graph/_graph_definition.pyx Resolved

Andy-Jost approved these changes Nov 2, 2026

View reviewed changes

martindurant self-assigned this Nov 3, 2026

martindurant added 2 commits November 3, 2026 09:45

Make messages match

84f8dc8

Merge branch 'main' into ids

2439fd9

coderabbitai Bot reviewed Nov 3, 2026

View reviewed changes

Merge branch 'main' into ids

527debf

Small changes

45c9a18

coderabbitai Bot reviewed Nov 4, 2026

View reviewed changes

martindurant added 2 commits November 4, 2026 16:21

Merge branch 'main' into ids

e4f844e

Update message

fb7024f

Andy-Jost enabled auto-merge (squash) November 5, 2026 23:27

Andy-Jost merged commit ddc2a2a into NVIDIA:main Nov 6, 2026
116 checks passed

Conversation

martindurant commented Nov 2, 2026

Description

Checklist

Uh oh!

copy-pr-bot Bot commented Nov 2, 2026

Uh oh!

coderabbitai Bot commented Nov 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Summary by CodeRabbit

Uh oh!

coderabbitai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Follow-up Comments

Uh oh!

coderabbitai Bot Nov 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Andy-Jost left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Follow-up Comments

Uh oh!

Uh oh!

Uh oh!

Andy-Jost Nov 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

martindurant Nov 3, 2026

Choose a reason for hiding this comment

Uh oh!

Andy-Jost Nov 3, 2026

Choose a reason for hiding this comment

Uh oh!

martindurant Nov 3, 2026

Choose a reason for hiding this comment

Uh oh!

Andy-Jost Nov 3, 2026

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Nov 3, 2026

Choose a reason for hiding this comment

Uh oh!

Andy-Jost commented Nov 3, 2026

Uh oh!

martindurant commented Nov 4, 2026

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Nov 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Andy-Jost commented Nov 5, 2026

Uh oh!

github-actions Bot commented Nov 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

coderabbitai Bot commented Nov 2, 2026 •

edited

Loading

coderabbitai Bot left a comment •

edited

Loading

Andy-Jost left a comment •

edited

Loading

coderabbitai Bot left a comment •

edited

Loading

Andy-Jost Nov 2, 2026 •

edited

Loading

github-actions Bot commented Nov 5, 2026 •

edited

Loading