Informative warnings for CAGRA construction with low intermediate degree

[landrumb]

Resolves #2033 with more informative warnings about the intermediate graph degree parameter.

[copy-pr-bot]

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.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 370edac3-2cf8-4341-b002-bba632d15354

📥 Commits

Reviewing files that changed from the base of the PR and between 41ac9af and 0625256.

📒 Files selected for processing (3)

• cpp/src/neighbors/detail/cagra/cagra_build.cuh
• cpp/src/neighbors/detail/cagra/graph_core.cuh
• cpp/src/neighbors/detail/cagra/utils.hpp

✅ Files skipped from review due to trivial changes (1)

• cpp/src/neighbors/detail/cagra/graph_core.cuh

🚧 Files skipped from review as they are similar to previous changes (1)

• cpp/src/neighbors/detail/cagra/cagra_build.cuh

---

📝 Walkthrough

Summary by CodeRabbit

Release Notes

• Improvements
  • Added configuration validation warnings recommending intermediate degree settings (1.5× target graph degree) to prevent connectivity issues during graph optimization.
  • Enhanced error messages with actionable guidance on configuring graph parameters to resolve construction failures.

Walkthrough

Adds a constexpr helper to compute a recommended intermediate degree (~1.5× graph_degree), warns when provided intermediate_degree is below that threshold during pre-build checks, and enhances the GPU pruning assertion to include the recommended value and more specific diagnostic guidance.

Changes

CAGRA Graph Degree Diagnostics

Layer / File(s)	Summary
Recommended-degree helper and pre-check cpp/src/neighbors/detail/cagra/utils.hpp, cpp/src/neighbors/detail/cagra/cagra_build.cuh	Adds recommended_intermediate_graph_degree(size_t) and updates check_graph_degree to compute the recommended intermediate degree (~1.5 * graph_degree) and emit a warning if intermediate_degree is below it.
Prune assertion diagnostic cpp/src/neighbors/detail/cagra/graph_core.cuh	Updates prune_graph_gpu assertion to compute and include the recommended intermediate degree in its diagnostic when pruning fails, and reports both output_graph_degree and knn_graph_degree with guidance about invalid/duplicate neighbor causes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding informative warnings for CAGRA construction when intermediate degree is low, which directly addresses the linked issue's objective.
Description check	✅ Passed	The description relates to the changeset by referencing issue #2033 and stating that it adds more informative warnings about intermediate graph degree parameter, which matches the code changes.
Linked Issues check	✅ Passed	All coding requirements from issue #2033 are met: warning implementation in cagra_build.cuh [#2033], improved assertion messaging in graph_core.cuh [#2033], and centralized recommendation function in utils.hpp [#2033] that computes 1.5× relationship.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to addressing issue #2033: adding warnings and recommendations for intermediate degree parameter across three CAGRA-related files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[divyegala]

Could you make the PR title more specific and descriptive please? As we use squash commits, the PR title acts as the commit message after the PR is merged.

[cjnolet]

/ok to test 41ac9af

[divyegala]

/ok to test dfdeced

[divyegala]

/ok to test 9118410

[dantegd]

/ok to test 0625256