Skip to content

Commit a772555

Browse files
cpcloudcpcloud
authored
docs: seed AGENTS.md guidance across CUDA Python packages [no-ci] (#1734)
* docs: seed package-specific AGENTS guidance Create initial AGENTS.md coverage at root plus cuda_pathfinder, cuda_bindings, cuda_core, and cuda_python with clearer root-vs-package scope and practical conventions for agent behavior. Treat this as an initial seed to iterate on with real usage rather than a final policy spec. Made-with: Cursor * chore: add claude links
1 parent f720e48 commit a772555

10 files changed

Lines changed: 496 additions & 77 deletions

File tree

‎AGENTS.md‎

Lines changed: 263 additions & 77 deletions
Large diffs are not rendered by default.

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

‎cuda_bindings/AGENTS.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
This file describes `cuda_bindings`, the low-level CUDA host API bindings
2+
subpackage in the `cuda-python` monorepo.
3+
4+
## Scope and principles
5+
6+
- **Role**: provide low-level, close-to-CUDA interfaces under
7+
`cuda.bindings.*` with broad API coverage.
8+
- **Style**: prioritize correctness and API compatibility over convenience
9+
wrappers. High-level ergonomics belong in `cuda_core`, not here.
10+
- **Cross-platform**: preserve Linux and Windows behavior unless a change is
11+
intentionally platform-specific.
12+
13+
## Package architecture
14+
15+
- **Public module layer**: Cython modules under `cuda/bindings/` expose user
16+
APIs (`driver`, `runtime`, `nvrtc`, `nvjitlink`, `nvvm`, `cufile`, etc.).
17+
- **Internal binding layer**: `cuda/bindings/_bindings/` provides lower-level
18+
glue and loader helpers used by public modules.
19+
- **Platform internals**: `cuda/bindings/_internal/` contains
20+
platform-specific implementation files and support code.
21+
- **Build/codegen backend**: `build_hooks.py` drives header parsing, template
22+
expansion, extension configuration, and Cythonization.
23+
24+
## Generated-source workflow
25+
26+
- **Do not hand-edit generated binding files**: many files under
27+
`cuda/bindings/` (including `*.pyx`, `*.pxd`, `*.pyx.in`, and `*.pxd.in`)
28+
are generated artifacts.
29+
- **Generated files are synchronized from another repository**: changes to these
30+
files in this repo are expected to be overwritten by the next sync.
31+
- **If generated output must change**: make the change at the generation source
32+
and sync the updated artifacts back here, rather than patching generated files
33+
directly in this repo.
34+
- **Header-driven generation**: parser behavior and required CUDA headers are
35+
defined in `build_hooks.py`; update those rules when introducing new symbols.
36+
- **Platform split files**: keep `_linux.pyx` and `_windows.pyx` variants
37+
aligned when behavior should be equivalent.
38+
39+
## Testing expectations
40+
41+
- **Primary tests**: `pytest tests/`
42+
- **Cython tests**:
43+
- build: `tests/cython/build_tests.sh` (or platform equivalent)
44+
- run: `pytest tests/cython/`
45+
- **Examples**: example coverage is pytest-based under `examples/`.
46+
- **Benchmarks**: run with `pytest --benchmark-only benchmarks/` when needed.
47+
- **Orchestrated run**: from repo root, `scripts/run_tests.sh bindings`.
48+
49+
## Build and environment notes
50+
51+
- `CUDA_HOME` or `CUDA_PATH` must point to a valid CUDA Toolkit for source
52+
builds that parse headers.
53+
- `CUDA_PYTHON_PARALLEL_LEVEL` controls build parallelism.
54+
- `CUDA_PYTHON_PARSER_CACHING` controls parser-cache behavior during generation.
55+
- Runtime behavior is affected by
56+
`CUDA_PYTHON_CUDA_PER_THREAD_DEFAULT_STREAM` and
57+
`CUDA_PYTHON_DISABLE_MAJOR_VERSION_WARNING`.
58+
59+
## Editing guidance
60+
61+
- Keep CUDA return/error semantics explicit and avoid broad fallback behavior.
62+
- Reuse existing helper layers (`_bindings`, `_internal`, `_lib`) before adding
63+
new one-off utilities.
64+
- If you add or change exported APIs, update relevant docs under
65+
`docs/source/module/` and tests in `tests/`.
66+
- Prefer changes that are easy to regenerate/rebuild rather than patching
67+
generated output directly.

‎cuda_bindings/CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

‎cuda_core/AGENTS.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
This file describes `cuda_core`, the high-level Pythonic CUDA subpackage in the
2+
`cuda-python` monorepo.
3+
4+
## Scope and principles
5+
6+
- **Role**: provide higher-level CUDA abstractions (`Device`, `Stream`,
7+
`Program`, `Linker`, memory resources, graphs) on top of `cuda.bindings`.
8+
- **API intent**: keep interfaces Pythonic while preserving explicit CUDA
9+
behavior and error visibility.
10+
- **Compatibility**: changes should remain compatible with supported
11+
`cuda.bindings` major versions (12.x and 13.x).
12+
13+
## Package architecture
14+
15+
- **Main package**: `cuda/core/` contains most Cython modules (`*.pyx`, `*.pxd`)
16+
implementing runtime behaviors and public objects.
17+
- **Subsystems**:
18+
- memory/resource stack: `cuda/core/_memory/`
19+
- system-level APIs: `cuda/core/system/`
20+
- compile/link path: `_program.pyx`, `_linker.pyx`, `_module.pyx`
21+
- execution path: `_launcher.pyx`, `_launch_config.pyx`, `_stream.pyx`
22+
- **C++ helpers**: module-specific C++ implementations live under
23+
`cuda/core/_cpp/`.
24+
- **Build backend**: `build_hooks.py` handles Cython extension setup and build
25+
dependency wiring.
26+
27+
## Build and version coupling
28+
29+
- `build_hooks.py` determines CUDA major version from `CUDA_CORE_BUILD_MAJOR`
30+
or CUDA headers (`CUDA_HOME`/`CUDA_PATH`) and uses it for build decisions.
31+
- Source builds require CUDA headers available through `CUDA_HOME` or
32+
`CUDA_PATH`.
33+
- `cuda_core` expects `cuda.bindings` to be present and version-compatible.
34+
35+
## Testing expectations
36+
37+
- **Primary tests**: `pytest tests/`
38+
- **Cython tests**:
39+
- build: `tests/cython/build_tests.sh` (or platform equivalent)
40+
- run: `pytest tests/cython/`
41+
- **Examples**: validate affected examples in `examples/` when changing user
42+
workflows or public APIs.
43+
- **Orchestrated run**: from repo root, `scripts/run_tests.sh core`.
44+
45+
## Runtime/build environment notes
46+
47+
- Runtime env vars commonly relevant:
48+
- `CUDA_PYTHON_CUDA_PER_THREAD_DEFAULT_STREAM`
49+
- `CUDA_PYTHON_DISABLE_MAJOR_VERSION_WARNING`
50+
- Build env vars commonly relevant:
51+
- `CUDA_HOME` / `CUDA_PATH`
52+
- `CUDA_CORE_BUILD_MAJOR`
53+
- `CUDA_PYTHON_PARALLEL_LEVEL`
54+
- `CUDA_PYTHON_COVERAGE`
55+
56+
## Editing guidance
57+
58+
- Keep user-facing behaviors coherent with docs and examples, especially around
59+
stream semantics, memory ownership, and compile/link flows.
60+
- Reuse existing shared utilities in `cuda/core/_utils/` before adding new
61+
helpers.
62+
- When changing Cython signatures or cimports, verify related `.pxd` and
63+
call-site consistency.
64+
- Prefer explicit error propagation over silent fallback paths.
65+
- If you change public behavior, update tests and docs under `docs/source/`.

‎cuda_core/CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

‎cuda_pathfinder/AGENTS.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
This file describes `cuda_pathfinder`, a Python sub-package of
2+
[cuda-python](https://github.com/NVIDIA/cuda-python). It locates and loads
3+
NVIDIA dynamic libraries (CTK, third-party, and driver) across Linux and
4+
Windows.
5+
6+
## Scope and principles
7+
8+
- **Language**: all implementation code in this package is pure Python.
9+
- **Public API**: keep user-facing imports stable via `cuda.pathfinder`.
10+
Internal modules should stay under `cuda.pathfinder._*`.
11+
- **Behavior**: loader behavior must remain deterministic and explicit. Avoid
12+
"best effort" silent fallbacks that mask why discovery/loading failed.
13+
- **Cross-platform**: preserve Linux and Windows behavior parity unless a change
14+
is explicitly platform-scoped.
15+
16+
## Package architecture
17+
18+
- **Descriptor source-of-truth**: `cuda/pathfinder/_dynamic_libs/descriptor_catalog.py`
19+
defines canonical metadata for known libraries.
20+
- **Registry layers**:
21+
- `lib_descriptor.py` builds the name-keyed runtime registry from the catalog.
22+
- `supported_nvidia_libs.py` keeps legacy exported tables derived from the
23+
catalog for compatibility.
24+
- **Search pipeline**:
25+
- `search_steps.py` implements composable find steps (`site-packages`,
26+
`CONDA_PREFIX`, `CUDA_HOME`/`CUDA_PATH`, canary-assisted CTK root flow).
27+
- `search_platform.py` and `platform_loader.py` isolate OS-specific logic.
28+
- **Load orchestration**:
29+
- `load_nvidia_dynamic_lib.py` coordinates find/load phases, dependency
30+
loading, driver-lib fast path, and cache semantics.
31+
- **Process isolation helper**:
32+
- `cuda/pathfinder/_utils/spawned_process_runner.py` is used where process
33+
global dynamic loader state would otherwise leak across tests.
34+
35+
## Editing guidance
36+
37+
- **Edit authored descriptors, not derived tables**: when adding/changing a
38+
library, update `descriptor_catalog.py` first; keep derived exports in sync
39+
through existing conversion logic and tests.
40+
- **Respect cache semantics**: `load_nvidia_dynamic_lib` is cached. Never add
41+
behavior that closes returned handles or assumes repeated fresh loads.
42+
- **Keep error contracts intact**:
43+
- unknown name -> `DynamicLibUnknownError`
44+
- known but unsupported on this OS -> `DynamicLibNotAvailableError`
45+
- known/supported but not found/loadable -> `DynamicLibNotFoundError`
46+
- **Do not hardcode host assumptions**: avoid baking in machine-local paths,
47+
shell-specific quoting, or environment assumptions.
48+
- **Prefer focused abstractions**: if a change is platform-specific, route it
49+
through existing platform abstraction points instead of branching in many call
50+
sites.
51+
52+
## Testing expectations
53+
54+
- **Primary command**: run `pytest tests/` from `cuda_pathfinder/`.
55+
- **Real-loading tests**: prefer spawned child-process tests for actual dynamic
56+
loading behavior; avoid in-process cross-test interference.
57+
- **Cache-aware tests**: if a test patches internals used by
58+
`load_nvidia_dynamic_lib`, call `load_nvidia_dynamic_lib.cache_clear()`.
59+
- **Negative-case names**: use obviously fake names (for example
60+
`"not_a_real_lib"`) in unknown/invalid-lib tests.
61+
- **INFO summary in CI logs**: use `info_summary_append` for useful
62+
test-context lines visible in terminal summaries.
63+
- **Strictness toggle**:
64+
`CUDA_PATHFINDER_TEST_LOAD_NVIDIA_DYNAMIC_LIB_STRICTNESS` controls whether
65+
missing libraries are tolerated (`see_what_works`) or treated as failures
66+
(`all_must_work`).
67+
68+
## Useful commands
69+
70+
- Run package tests: `pytest tests/`
71+
- Run package tests via orchestrator: `../scripts/run_tests.sh pathfinder`
72+
- Build package docs: `cd docs && ./build_docs.sh`

‎cuda_pathfinder/CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

‎cuda_python/AGENTS.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
This file describes `cuda_python`, the metapackage layer in the `cuda-python`
2+
monorepo.
3+
4+
## Scope
5+
6+
- `cuda_python` is primarily packaging and documentation glue.
7+
- It does not host substantial runtime APIs like `cuda_core`,
8+
`cuda_bindings`, or `cuda_pathfinder`.
9+
10+
## Main files to edit
11+
12+
- `pyproject.toml`: project metadata and dynamic dependency declaration.
13+
- `setup.py`: dynamic dependency pinning logic for matching `cuda-bindings`
14+
versions (release vs pre-release behavior).
15+
- `docs/`: top-level docs build/aggregation scripts.
16+
17+
## Editing guidance
18+
19+
- Keep this package lightweight; prefer implementing runtime features in the
20+
component packages rather than here.
21+
- Be careful when changing dependency/version logic in `setup.py`; preserve
22+
compatibility between metapackage versioning and subpackage constraints.
23+
- If you update docs structure, ensure `docs/build_all_docs.sh` still collects
24+
docs from `cuda_python`, `cuda_bindings`, `cuda_core`, and `cuda_pathfinder`.

‎cuda_python/CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

0 commit comments

Comments
 (0)