diff --git a/.agents/build-cuml/SKILL.md b/.agents/build-cuml/SKILL.md new file mode 100644 index 0000000000..4023e44138 --- /dev/null +++ b/.agents/build-cuml/SKILL.md @@ -0,0 +1,191 @@ +--- +name: build-cuml +description: Build cuML (libcuml C++ library and cuml Python package) from source in a conda dev environment, using the repo's build.sh script. Use whenever the user asks to build, compile, install, or rebuild cuML from source, install local cuML changes, or before testing local edits to cuML C++/CUDA/Cython/Python code. +--- + +# Building cuML + +This skill teaches the agent how to build cuML from source in this repository. The canonical reference is [BUILD.md](../../BUILD.md) at the repo root; this skill captures the high-frequency workflows so the agent can act without re-reading the full doc each time. + +## Quick start (TL;DR) + +With a cuML dev env already active, build and install everything for the local GPU arch: + +```bash +./build.sh --ccache +``` + +This builds and installs `libcuml` (C++), `cuml` (Python), and `prims` (tests) into `$CONDA_PREFIX`. + +> **Important (sm_121 / new arch + conda RAPIDS libs):** there is a known bug in the default `NATIVE` build path (documented in [rapidsai/cuml#8021](https://github.com/rapidsai/cuml/issues/8021)). Until fixed upstream, use one of these workarounds when mixing with conda-installed RAPIDS shared libraries: +> +> ```bash +> ./build.sh --allgpuarch +> # or +> CUML_EXTRA_CMAKE_ARGS="-DCMAKE_CUDA_ARCHITECTURES=120-real" ./build.sh +> ``` +> +> Bug details: [rapidsai/cuml#8021](https://github.com/rapidsai/cuml/issues/8021). + +## When to apply this skill + +- The user asks to build / compile / install / rebuild cuML. +- The agent has edited C++/CUDA/Cython/Python code in this repo and needs to rebuild before testing. +- A test run fails with `ImportError`, missing `libcuml.so`, stale `.so`, or "module not found" symptoms after a code change — the local install is likely stale and needs a rebuild. + +## 1. Confirm the active development environment + +Building cuML requires an **active** development environment containing all build and runtime dependencies. Building with the wrong env active (or none) can install into — and test against — the wrong prefix. If the active environment is missing or ambiguous, and the current agent context does not provide clear local instructions for choosing one, stop and ask the user which development environment to use. + +### Quick check + +```bash +echo "CONDA_PREFIX=${CONDA_PREFIX:-unset} VIRTUAL_ENV=${VIRTUAL_ENV:-unset}" +which python +python -c "import cuml; print(cuml.__file__)" 2>/dev/null \ + || echo "cuml not yet installed (fine before first build)" +``` + +`cuml.__file__` should resolve inside this worktree (`python/cuml/`) or inside the active env's `site-packages`. If it resolves into a different worktree or env, stop and ask for the local environment instructions before building. + +## 2. Build with `build.sh` + +`build.sh` lives at the repo root and is the recommended entry point. Targets are space-separated; flags can be mixed in. With no targets it builds and installs `libcuml`, `cuml`, and `prims` for the detected GPU arch. + +### Common targets + +```bash +./build.sh # libcuml + cuml + prims (default) +./build.sh libcuml # C++ library only +./build.sh cuml # Python package only (assumes libcuml installed) +./build.sh libcuml cuml # both, explicit +./build.sh clean # wipe all build artifacts (run first if state is corrupt) +./build.sh prims bench # ml-prims tests + C++ benchmark +``` + +### Most useful flags + +| Flag | Effect | +| --- | --- | +| `--ccache` | Cache compilations via ccache/sccache. **Strongly recommended for any iterative work.** | +| `-g` | Build with debug info (`RelWithDebInfo`). | +| `-v` | Verbose build output. | +| `-n` | Build but don't install. | +| `--allgpuarch` | Build for all RAPIDS-supported archs (slow; default is `NATIVE` = local GPU only). | +| `--singlegpu` | Drop multi-GPU/MNMG components from `libcuml` and `cuml`. Faster, smaller. | +| `--nolibcumltest` | Skip C++ test binaries (faster libcuml builds). | +| `--configure-only` | Run cmake configure but don't compile (e.g. for clang-tidy DB generation). | + +### Environment variables + +- `PARALLEL_LEVEL=N` — limit ninja parallelism. **Use this on shared machines or when ninja OOMs the system.** Default is `nproc`. +- `INSTALL_PREFIX=/path` — install location. Default is `$CONDA_PREFIX` when a conda env is active. +- `CMAKE_GENERATOR='Unix Makefiles'` — switch from Ninja to make. +- `CUML_EXTRA_CMAKE_ARGS="..."` — append extra `-D...` flags to cmake. +- `CUML_EXTRA_PYTHON_ARGS="..."` — append extra args to the `pip install` step. + +### Recommended fast-iteration command + +For day-to-day editing (any code: C++, CUDA, Cython, Python): + +```bash +PARALLEL_LEVEL=$(nproc) ./build.sh --ccache +``` + +For C++-only edits, skip the Python rebuild: + +```bash +./build.sh libcuml --ccache +``` + +For Python-only edits (no C++ touched), skip the C++ rebuild: + +```bash +./build.sh cuml +``` + +## 3. ccache / sccache for fast rebuilds + +Branch switching, debug↔release toggles, and CI-style rebuilds become much cheaper with a compile cache. cuML supports both `ccache` and `sccache` (sccache is preferred in CI). + +### Enable + +Pass `--ccache` to `build.sh`. This sets `-DUSE_CCACHE=ON` for the cmake configure step. + +### Verify a cache is installed and used + +```bash +which ccache sccache 2>/dev/null + +# After a build, inspect stats: +ccache -s # if using ccache +sccache --show-stats # if using sccache +``` + +If neither is on `PATH`, install one into the active dev env: + +```bash +conda install -y -c conda-forge ccache +# or +conda install -y -c conda-forge sccache +``` + +### Cache hit reporting in builds + +Add `--build-metrics --incl-cache-stats` to record cache hit rate and produce an HTML build report at `cpp/build/ninja_log.html`: + +```bash +./build.sh libcuml --ccache --build-metrics --incl-cache-stats +``` + +### When to clear the cache + +- Compiler version changed (`gcc`/`nvcc` upgrade) — invalidate to avoid stale objects: `ccache -C` or `sccache --zero-stats` then re-run. +- After CUDA toolkit upgrade. +- Otherwise: leave it alone; clearing the cache defeats the purpose. + +## 4. Verify the build + +After the install step finishes, confirm libcuml and cuml are importable from the active env: + +```bash +test -f "$CONDA_PREFIX/lib/libcuml.so" && echo "libcuml.so installed" +python -c "import cuml; print(cuml.__version__, cuml.__file__)" +``` + +The `cuml.__file__` path should be inside the active conda env (or the editable source tree). + +## 5. Common gotchas + +- **`ImportError` after pulling new commits**: rebuild — the C++ ABI or Cython-generated code likely changed. +- **`libcuml.so` not found at runtime**: `INSTALL_PREFIX` mismatched the active env. Re-run `build.sh` with the correct env activated. +- **`cuml.__file__` points to a different checkout than the one you're editing**: the wrong env is active. Activate the intended dev environment for this checkout and rebuild. +- **Out-of-memory or thermal throttling during build**: lower `PARALLEL_LEVEL` (e.g. `PARALLEL_LEVEL=8`). +- **Stale build state after a failed build**: run `./build.sh clean` then rebuild from scratch. +- **Building without a GPU**: the build itself works on CPU-only hosts; only running cuML at test time requires a GPU. +- **`--singlegpu` + multi-GPU tests**: skip MNMG tests (e.g. `pytest --ignore=cuml/tests/dask --ignore=cuml/tests/test_nccl.py`). + +## 6. Manual cmake / pip path + +`build.sh` is a thin wrapper around `cmake` + `pip install`. If the user explicitly wants the manual flow, or `build.sh` is unavailable, see the **"Manual Process"** section of [BUILD.md](../../BUILD.md). The two key invocations are: + +```bash +# C++ library +cd cpp && mkdir -p build && cd build +cmake -DCMAKE_INSTALL_PREFIX="$CONDA_PREFIX" \ + -DCMAKE_CUDA_ARCHITECTURES=NATIVE \ + -DUSE_CCACHE=ON .. +cmake --build . -j"$(nproc)" --target install + +# Python package (from repo root) +python -m pip install --no-build-isolation --no-deps \ + --config-settings rapidsai.disable-cuda=true \ + python/cuml +``` + +## Additional resources + +- Full build docs and all cmake flags: [BUILD.md](../../BUILD.md) +- Contributing workflow (pre-commit, clang-tidy, branch naming): [CONTRIBUTING.md](../../CONTRIBUTING.md) +- Conda environment files: `conda/environments/all_cuda-*_arch-*.yaml` +- Build script source (the source of truth for flag behavior): `build.sh` diff --git a/.agents/test-cuml/SKILL.md b/.agents/test-cuml/SKILL.md new file mode 100644 index 0000000000..65f646a329 --- /dev/null +++ b/.agents/test-cuml/SKILL.md @@ -0,0 +1,250 @@ +--- +name: test-cuml +description: Run cuML test suites — C++ gtests, standard Python tests, dask tests, cuml.accel tests, upstream library tests (sklearn/umap/hdbscan) under cuml.accel, and integration tests. Use when the user asks to run, invoke, or debug cuML tests, pytest, ctest, run sklearn tests under cuml.accel, run dask tests, run integration tests, or wants to verify a code change works. +--- + +# Running cuML Tests + +This skill covers all cuML test suites. The canonical source of truth for each suite is the corresponding `ci/run_*` and `ci/test_*` script — when in doubt, read those first. + +## 0. Prerequisites + +**A cuML dev env must be active before running any tests.** If the active environment is missing or ambiguous, and the current agent context does not provide clear local instructions for choosing one, stop and ask the user which development environment to use before running tests. + +Quick sanity check before invoking any test command: + +```bash +echo "CONDA_PREFIX=${CONDA_PREFIX:-unset} VIRTUAL_ENV=${VIRTUAL_ENV:-unset}" +which python +python -c "import cuml; print(cuml.__file__)" 2>/dev/null \ + || echo "cuml not yet installed — rebuild first" +``` + +Additional prerequisites: + +- After editing C++/CUDA/Cython code, rebuild before testing. See [.agents/build-cuml/SKILL.md](../build-cuml/SKILL.md). +- If you see `No module named pytest` (or `python` resolves to the base conda install instead of the dev env), the dev environment is not active — the cuML dev env includes `pytest` and the rest of the test stack. +- All Python tests require a GPU. Most suites support `pytest-xdist` parallelism (`-n auto` or `--numprocesses=N --dist=worksteal`). +- CI entry scripts such as `ci/run_cuml_singlegpu_pytests.sh` call `python` on your `PATH`; they assume an appropriate environment is already activated. + +--- + +## 1. C++ gtests (libcuml) + +Test binaries are built by the default `./build.sh` targets and installed to `$CONDA_PREFIX/bin/gtests/libcuml/`. + +**Canonical entry point:** [`ci/run_ctests.sh`](../../ci/run_ctests.sh) — changes into the install dir (or falls back to `cpp/build/latest`) and runs `ctest --output-on-failure --no-tests=error`. + +```bash +# Run all gtests in parallel (matches CI) +./ci/run_ctests.sh -j9 + +# Run a single test suite by regex +./ci/run_ctests.sh -R SG_DBSCAN_TEST + +# Run only prims tests +./ci/run_ctests.sh -R PRIMS_ +``` + +**Direct binary invocation** (faster iteration on one algorithm): + +```bash +cd "$CONDA_PREFIX/bin/gtests/libcuml" +./SG_DBSCAN_TEST --gtest_filter='*' +./SG_RF_TEST --gtest_filter='RandomForestClassifierTest*' +./SG_DBSCAN_TEST --gtest_list_tests # list available test cases +``` + +Test binary names come from `cpp/tests/CMakeLists.txt` (`SG_*` for single-GPU, `PRIMS_*` for ml-prims, `MG_*` for multi-GPU). Prims tests install to `$CONDA_PREFIX/bin/gtests/libcuml_prims/`. + +If binaries are missing, rebuild: `./build.sh` (default targets include the test build). + +--- + +## 2. Standard Python tests (single-GPU, no dask) + +**Path:** `python/cuml/tests/` (ignoring the `dask/` subdir). +**Canonical entry point:** [`ci/run_cuml_singlegpu_pytests.sh`](../../ci/run_cuml_singlegpu_pytests.sh) + +```bash +# Run the full suite (CI-style, parallel) +./ci/run_cuml_singlegpu_pytests.sh --numprocesses=8 --dist=worksteal + +# Quick targeted run +./ci/run_cuml_singlegpu_pytests.sh -k test_kmeans + +# Single file, verbose +./ci/run_cuml_singlegpu_pytests.sh -v python/cuml/tests/test_kmeans.py + +# Alternatively, run pytest directly from the tests dir +cd python/cuml/tests +pytest --ignore=dask -k test_linear_regression -x +``` + +**Test categories** (from [`python/cuml/tests/conftest.py`](../../python/cuml/tests/conftest.py)): + +| Flag | Runs | Default | +| --- | --- | --- | +| `--run_unit` | `@pytest.mark.unit` tests | Yes (implied when no `--run_*` flag given) | +| `--run_quality` | `@pytest.mark.quality` tests | No | +| `--run_stress` | `@pytest.mark.stress` tests | No | +| `--run_memleak` | `@pytest.mark.memleak` tests | No | + +`HYPOTHESIS_ENABLED=true` enables full Hypothesis search (CI nightly behavior; default in CI runs quality/stress profiles). + +--- + +## 3. Dask tests (multi-GPU) + +**Path:** `python/cuml/tests/dask/` — each test spins up a `LocalCUDACluster` (TCP by default, UCXX optional). +**Canonical entry point:** [`ci/run_cuml_dask_pytests.sh`](../../ci/run_cuml_dask_pytests.sh) + +```bash +# Standard TCP run (default) +./ci/run_cuml_dask_pytests.sh -k test_dask_kmeans + +# Full parallel CI run +./ci/run_cuml_dask_pytests.sh --numprocesses=8 --dist=worksteal + +# UCXX-only tests (skips all non-UCX tests) +./ci/run_cuml_dask_pytests.sh --run_ucx +``` + +CI runs both TCP and UCXX passes — see [`ci/test_python_dask.sh`](../../ci/test_python_dask.sh). + +**Note on the env:** The single-GPU CI job intentionally errors if `dask` is importable. Use a dask-enabled env (one that has `cuml[dask,test-dask]`: `dask-cudf`, `raft-dask`, `dask-cuda`, `dask-ml`) when running the dask suite. + +--- + +## 4. cuml.accel tests (proxy estimator suite) + +**Path:** `python/cuml/cuml_accel_tests/` — `conftest.py` calls `cuml.accel.install()` so all collected tests run with the proxy enabled. The `upstream/` subdir is in `collect_ignore` and must be run separately (see §5). +**Canonical entry point:** [`ci/run_cuml_singlegpu_accel_pytests.sh`](../../ci/run_cuml_singlegpu_accel_pytests.sh) + +```bash +# Full suite (CI-style, parallel) +./ci/run_cuml_singlegpu_accel_pytests.sh --numprocesses=8 --dist=worksteal + +# Targeted run +./ci/run_cuml_singlegpu_accel_pytests.sh -k test_estimator_proxy + +# Direct pytest +cd python/cuml/cuml_accel_tests +pytest test_estimator_proxy.py -k LogisticRegression -x -v +``` + +The `integration/` subdir inside `cuml_accel_tests/` belongs to the integration suite (§6), not here. + +--- + +## 5. Upstream tests (scikit-learn / umap / hdbscan under cuml.accel) + +Each upstream library has a `run-tests.sh` in `python/cuml/cuml_accel_tests/upstream//`. The script runs the library's own test suite with `-p cuml.accel` and an `xfail-list.yaml`. + +Full workflow reference: [`python/cuml/cuml_accel_tests/upstream/README.md`](../../python/cuml/cuml_accel_tests/upstream/README.md). + +### scikit-learn + +[`upstream/scikit-learn/run-tests.sh`](../../python/cuml/cuml_accel_tests/upstream/scikit-learn/run-tests.sh) — uses `--pyargs sklearn`. + +```bash +# Run all sklearn tests under cuml.accel +./python/cuml/cuml_accel_tests/upstream/scikit-learn/run-tests.sh + +# Targeted +./python/cuml/cuml_accel_tests/upstream/scikit-learn/run-tests.sh -k test_kmeans + +# Parallel + XML report +./python/cuml/cuml_accel_tests/upstream/scikit-learn/run-tests.sh \ + -n auto --dist worksteal --junitxml=report.xml + +# Run known-xfailed tests to see actual results +./python/cuml/cuml_accel_tests/upstream/scikit-learn/run-tests.sh --runxfail +``` + +**`run-tests.sh` and the xfail list:** the script always passes `--pyargs sklearn` and [`--xfail-list=.../xfail-list.yaml`](../../python/cuml/cuml_accel_tests/upstream/scikit-learn/xfail-list.yaml). The `cuml.accel` pytest plugin marks xfails and **requires every condition-matched id in the YAML to match a collected test**; if you instead run e.g. `pytest -p cuml.accel --pyargs sklearn.neighbors.tests.test_kde --xfail-list=...`, most xfail entries have no corresponding collected test and you get `UnmatchedXfailTests` (treated as an error by [`python/cuml/cuml_accel_tests/upstream/pytest.ini`](../../python/cuml/cuml_accel_tests/upstream/pytest.ini)). For targeted runs **with** the official xfail list, keep using `run-tests.sh` and filter with `-k` (full sklearn collection, then deselect; still usually seconds of overhead). For a **fast local loop** on one module only, you may run `python -m pytest -p cuml.accel --pyargs sklearn. ...` **without** `--xfail-list` — but tests listed as xfail in the YAML may then appear as real failures. + +### umap + +[`upstream/umap/run-tests.sh`](../../python/cuml/cuml_accel_tests/upstream/umap/run-tests.sh) — clones the umap repo at the tag matching the installed `umap.__version__` into `umap-upstream/`. + +```bash +./python/cuml/cuml_accel_tests/upstream/umap/run-tests.sh +./python/cuml/cuml_accel_tests/upstream/umap/run-tests.sh -k test_umap_transform +``` + +### hdbscan + +[`upstream/hdbscan/run-tests.sh`](../../python/cuml/cuml_accel_tests/upstream/hdbscan/run-tests.sh) — uses `--pyargs hdbscan.tests`. + +```bash +./python/cuml/cuml_accel_tests/upstream/hdbscan/run-tests.sh +./python/cuml/cuml_accel_tests/upstream/hdbscan/run-tests.sh -k test_hdbscan +``` + +### Analyzing results + +```bash +# Summary (pass/fail counts) +./python/cuml/cuml_accel_tests/upstream/summarize-results.py report.xml + +# Verbose — show failure details +./python/cuml/cuml_accel_tests/upstream/summarize-results.py -v report.xml + +# Enforce a minimum pass rate (e.g. 80%) +./python/cuml/cuml_accel_tests/upstream/summarize-results.py -f 80 report.xml + +# Tracebacks for specific failures +./python/cuml/cuml_accel_tests/upstream/summarize-results.py \ + --format=traceback -k logistic report.xml + +# Generate a new xfail list from results +./python/cuml/cuml_accel_tests/upstream/summarize-results.py \ + --format=xfail_list report.xml > new-xfail-list.yaml +``` + +For editing the xfail list (adding/updating reasons, markers, conditions), use `xfail_manager.py` — see the [README](../../python/cuml/cuml_accel_tests/upstream/README.md). + +--- + +## 6. Integration tests (cudf.pandas + cuml.accel) + +Runs the standard `python/cuml/tests/` suite (not dask) with `-p cudf.pandas` so pandas operations route through the cudf-pandas wrapper, plus `--quick_run` to keep runtime bounded. +**Canonical entry point:** [`ci/run_cuml_integration_pytests.sh`](../../ci/run_cuml_integration_pytests.sh) + +```bash +# Full CI run +./ci/run_cuml_integration_pytests.sh --numprocesses=8 --dist=worksteal + +# Targeted +./ci/run_cuml_integration_pytests.sh -k test_linear_regression + +# Direct pytest equivalent +cd python/cuml/tests +pytest -p cudf.pandas --cache-clear --ignore=dask --quick_run . +``` + +Tests marked `@pytest.mark.cudf_pandas` are skipped unless `-p cudf.pandas` is loaded (enforced in `tests/conftest.py`). + +CI script: [`ci/test_python_integration.sh`](../../ci/test_python_integration.sh). + +--- + +## 7. Common gotchas + +- **`ImportError` or wrong `cuml.__file__`**: the wrong env is active. Activate the intended dev environment for this checkout and rebuild. See the [build skill](../build-cuml/SKILL.md). +- **C++ test binaries not found**: the install dir `$CONDA_PREFIX/bin/gtests/libcuml/` is absent. Run `./build.sh` (default builds and installs the tests). +- **Dask import error in single-GPU env**: the single-GPU CI script (`test_python_singlegpu.sh`) intentionally fails if `dask` is installed. Use a dask-capable env for §3 tests. +- **`UnmatchedXfailTests` in upstream sklearn tests**: (1) the xfail list references a test id that no longer exists in the installed library version — triage and update the list (see the upstream [README](../../python/cuml/cuml_accel_tests/upstream/README.md)). (2) You passed `--xfail-list` while collecting only a **subset** of the suite (e.g. `--pyargs sklearn.neighbors.tests.test_kde`); use [`run-tests.sh`](../../python/cuml/cuml_accel_tests/upstream/scikit-learn/run-tests.sh) with `-k` instead, or drop `--xfail-list` for a quick narrow run. +- **xdist worker crash after CUDA error**: this is intentional — `tests/conftest.py` calls `os._exit(1)` on sticky CUDA errors so xdist spawns a clean worker. Don't attempt to suppress it. + +--- + +## 8. Additional resources + +- Build skill: [.agents/build-cuml/SKILL.md](../build-cuml/SKILL.md) +- Full build doc and manual cmake/test paths: [BUILD.md](../../BUILD.md) +- Upstream test workflow and xfail management: [python/cuml/cuml_accel_tests/upstream/README.md](../../python/cuml/cuml_accel_tests/upstream/README.md) +- Pytest markers and filterwarnings: [`python/cuml/pyproject.toml`](../../python/cuml/pyproject.toml) `[tool.pytest.ini_options]` +- Test suite conftest (markers, xdist hooks, Hypothesis profiles): [`python/cuml/tests/conftest.py`](../../python/cuml/tests/conftest.py) +- Dask conftest (cluster fixtures, `--run_ucx` option): [`python/cuml/tests/dask/conftest.py`](../../python/cuml/tests/dask/conftest.py) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index a38c72cbcc..4a9fd6fa69 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -20,6 +20,10 @@ CMakeLists.txt @rapidsai/cuml-cmake-codeowners *.cmake @rapidsai/cuml-cmake-codeowners **/cmake/ @rapidsai/cuml-cmake-codeowners +# agent instruction owners +**/AGENTS.md @rapidsai/cuml-python-codeowners @rapidsai/cuml-cpp-codeowners +**/.agents/ @rapidsai/cuml-python-codeowners @rapidsai/cuml-cpp-codeowners + #CI code owners /.github/ @rapidsai/ci-codeowners /ci/ @rapidsai/ci-codeowners diff --git a/.github/workflows/pr.yaml b/.github/workflows/pr.yaml index 3351be575d..0c0a01dc19 100644 --- a/.github/workflows/pr.yaml +++ b/.github/workflows/pr.yaml @@ -89,7 +89,8 @@ jobs: files_yaml: | build_docs: - '**' - - '!**/*/agents.md' + - '!**/AGENTS.md' + - '!**/.agents/**' - '!.coderabbit.yaml' - '!.devcontainer/**' - '!.git-blame-ignore-revs' @@ -113,7 +114,8 @@ jobs: - '!codecov.yml' test_cpp: - '**' - - '!**/*/agents.md' + - '!**/AGENTS.md' + - '!**/.agents/**' - '!.coderabbit.yaml' - '!.devcontainer/**' - '!.git-blame-ignore-revs' @@ -148,7 +150,8 @@ jobs: - '!wiki/**' test_notebooks: - '**' - - '!**/*/agents.md' + - '!**/AGENTS.md' + - '!**/.agents/**' - '!.coderabbit.yaml' - '!.devcontainer/**' - '!.git-blame-ignore-revs' @@ -180,7 +183,8 @@ jobs: - '!wiki/**' test_python_conda: - '**' - - '!**/*/agents.md' + - '!**/AGENTS.md' + - '!**/.agents/**' - '!.coderabbit.yaml' - '!.devcontainer/**' - '!.git-blame-ignore-revs' @@ -217,7 +221,8 @@ jobs: - '!wiki/**' test_python_wheels: - '**' - - '!**/*/agents.md' + - '!**/AGENTS.md' + - '!**/.agents/**' - '!.coderabbit.yaml' - '!.devcontainer/**' - '!.git-blame-ignore-revs' diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..e55d6678cb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,46 @@ +# Agent Guide + +Onboarding notes for AI coding agents working in the cuML repository. + +## Repository overview + +This is [cuML](https://github.com/rapidsai/cuml), the RAPIDS GPU-accelerated machine learning library. The repo contains: + +- `cpp/` — `libcuml` C++/CUDA library and ML primitives. +- `python/cuml/` — `cuml` Python package (Cython + Python, scikit-learn-compatible API). +- `conda/environments/` — pinned conda env files for development and CI. +- `ci/` — CI scripts. +- `docs/` — Sphinx documentation. + +## Building cuML + +Before testing any local code change that touches C++/CUDA/Cython, the local install must be rebuilt in an active cuML development environment. Follow the dedicated build skill: + +- [.agents/build-cuml/SKILL.md](.agents/build-cuml/SKILL.md) — `build.sh` usage, ccache, and common gotchas. + +The full build reference is [BUILD.md](BUILD.md). + +## Running tests + +For running the C++ gtests, the standard pytest suite, dask tests, the cuml.accel suite, upstream-library tests under cuml.accel, and the integration tests, follow the dedicated test skill: + +- [.agents/test-cuml/SKILL.md](.agents/test-cuml/SKILL.md) — active environment checks, `ci/run_*` entry points, common pytest args, and per-suite gotchas. + +The CI scripts under [ci/](ci/) (`test_cpp.sh`, `test_python_singlegpu.sh`, `test_python_dask.sh`, `test_python_integration.sh`, `test_python_scikit_learn_tests.sh`, `test_python_cuml_accel_upstream.sh`) are the source of truth for how each suite is invoked. + +## Contributing workflow + +For pre-commit hooks, clang-tidy, branch naming, and the PR process, see [CONTRIBUTING.md](CONTRIBUTING.md). + +Key conventions: + +- Linter errors are auto-fixed by pre-commit hooks — don't fix them manually unless asked. + +## Code review guidelines + +When reviewing changes, agents should follow the layer-specific review rubrics: + +- C++/CUDA changes: [cpp/agents.md](cpp/agents.md) +- Python changes: [python/agents.md](python/agents.md) + +Both files focus on CRITICAL and HIGH issues only and target a sub-3% false-positive rate.