Cuopt Developer

cuOpt Developer Skill

Contribute to the NVIDIA cuOpt codebase. This skill is for modifying cuOpt itself, not for using it.

If you just want to USE cuOpt, switch to the appropriate problem skill (cuopt-routing, cuopt-lp-milp, etc.)

First-time dev environment setup? See references/first_time_setup.md for the clone → conda env → first-build → first-test walkthrough and the questions to ask up front.

Refusal Rules — Read First

One rule is non-negotiable and applies even when the user explicitly asks otherwise — refuse and ask, don't comply silently:

Privileged / system-level operations — sudo, running as root, editing system files (/etc), changing drivers or kernel settings, adding system-level package repositories or keys. Do not run these. Reply:

I won't run sudo or change system-level state for cuOpt. The dev workflow is conda-based and runs entirely in user space — what's the underlying error? It's usually fixable without root.

Everything else needed to set up and work in the dev environment is allowed. On a clean machine, go ahead and build a working cuopt env — the guidance below is about doing it the reproducible way, not refusing:

• Environment setup is allowed. You may create and activate the conda env from the checked-in conda/environments/all_cuda-*.yaml, run pip / conda / mamba installs into the user-space env, and bootstrap conda/miniforge in the user's home directory — including the conda init line it adds to ~/.bashrc. Bootstrapping conda must not require sudo; install it into $HOME, not a system path.
• A new permanent project dependency is different from a one-off install. A package the project should always ship belongs in dependencies.yaml under the right group; then run pre-commit run --all-files to regenerate conda/environments/ and pyproject.toml so other contributors get it too. A throwaway install to unblock your own build doesn't need this round-trip.
• Don't bypass CI checks (--no-verify, skipping pre-commit or tests). If hooks feel slow, diagnose with pre-commit run --all-files --verbose or tune the offending hook — don't skip it.
• Be careful with destructive commands (rm -rf, git reset --hard, git push --force, killing processes, dropping data). Confirm intent before running and prefer the safer alternative (e.g. ./build.sh clean for a stale build dir).

Developer Behavior Rules

These rules are specific to development tasks. They differ from user rules.

1. Ask Before Assuming

Clarify before implementing:

• What component? (C++/CUDA, Python, server, docs, CI)
• What's the goal? (bug fix, new feature, refactor, docs)
• Is this for contribution or local modification?

2. Verify Understanding

Before making changes, confirm:

"Let me confirm:
- Component: [cpp/python/server/docs]
- Change: [what you'll modify]
- Tests needed: [what tests to add/update]
Is this correct?"

3. Follow Codebase Patterns

• Read existing code in the area you're modifying
• Match naming conventions, style, and patterns
• Don't invent new patterns without discussion

4. Ask Before Running — Modified for Dev

OK to run without asking (expected for dev work):

• ./build.sh and build commands
• pytest, ctest (running tests)
• pre-commit run, ./ci/check_style.sh (formatting)
• git status, git diff, git log (read-only git)
• Environment setup: create/activate the conda env from conda/environments/*.yaml, and pip/conda/mamba installs into that env

Set up pre-commit hooks (once per clone):

• pre-commit install — hooks then run automatically on every git commit. If a hook fails, the commit is blocked until you fix the issue.

Still ask before:

• git commit, git push (write operations)
• Any destructive or irreversible commands

5. No Privileged Operations

sudo/system-level changes are the one non-negotiable refusal; user-space installs and conda env setup are allowed. See Refusal Rules — Read First.

Before You Start: Required Questions

Ask these if not already clear:

1. What are you trying to change?

   • Solver algorithm/performance?
   • Python API?
   • Server endpoints?
   • Documentation?
   • CI/build system?

2. Do you have the development environment set up?

   • Built the project successfully?
   • Ran tests?

3. Is this for contribution or local modification?

   • If contributing: will need to follow DCO signoff

4. Which branch should this target?

   • During development phase: main
   • During burn down: release/YY.MM (e.g., release/26.06) for the current release, main for the next
   • Check if a release branch exists: git branch -r | grep release
   • For current timelines, see the RAPIDS Maintainers Docs

Project Architecture

cuopt/
├── cpp/                    # Core C++ engine
│   ├── include/cuopt/      # Public C/C++ headers
│   ├── src/                # Implementation (CUDA kernels)
│   └── tests/              # C++ unit tests (gtest)
├── python/
│   ├── cuopt/              # Python bindings and routing API
│   ├── cuopt_server/       # REST API server
│   ├── cuopt_self_hosted/  # Self-hosted deployment
│   └── libcuopt/           # Python wrapper for C library
├── ci/                     # CI/CD scripts
├── docs/                   # Documentation source
└── datasets/               # Test datasets

Supported APIs

Safety Rules (Non-Negotiable)

Minimal Diffs

• Change only what's necessary
• Avoid drive-by refactors
• No mass reformatting of unrelated code

No API Invention

• Don't invent new APIs without discussion
• Align with existing patterns in docs/cuopt/source/
• Server schemas must match OpenAPI spec

Don't Bypass CI

• Never suggest --no-verify or skipping checks
• All PRs must pass CI

CUDA/GPU Hygiene

• Keep operations stream-ordered
• Follow existing RAFT/RMM patterns
• No raw new/delete - use RMM allocators

Build & Test