cue-ai 0.3.0

package/resources/skills/skills/nvidia/cuopt-developer/resources/build_and_test.md

@@ -0,0 +1,43 @@
+# Build & Test
+
+Read this for component-level build commands, run-test commands, and `PARALLEL_LEVEL` detail. **Pre-flight checks** (CUDA driver compatibility, conda env activation, dataset setup) live in [SKILL.md → Build & Test → Pre-flight Checks](../SKILL.md#pre-flight-checks-required-before-first-build-or-test) — always run those first.
+
+## PARALLEL_LEVEL
+
+`PARALLEL_LEVEL` controls the number of parallel compile jobs. It defaults to `$(nproc)` (all cores), which can cause OOM on machines with limited RAM — CUDA compilation needs roughly 4–8 GB per job. Set it based on available RAM:
+
+```bash
+export PARALLEL_LEVEL=8   # adjust based on available RAM
+```
+
+## Build Everything
+
+```bash
+./build.sh
+```
+
+## Build Specific Components
+
+```bash
+./build.sh --help                                       # Lists build options
+./build.sh libcuopt                                     # C++ library
+./build.sh libcuopt --skip-routing-build --skip-tests-build --skip-c-python-adapters --cache-tool=ccache  # native LP/MIP-focused build without routing/tests/adapters
+./build.sh cuopt                                        # Python package
+./build.sh cuopt_server                                 # Server
+./build.sh docs                                         # Documentation
+```
+
+## Run Tests
+
+> Activate the conda env used to build first (`conda activate <env-name>`) and ensure datasets are fetched — see [Pre-flight Checks](../SKILL.md#pre-flight-checks-required-before-first-build-or-test) in SKILL.md.
+
+```bash
+# C++ tests
+ctest --test-dir cpp/build
+
+# Python tests
+pytest -v python/cuopt/cuopt/tests
+
+# Server tests
+pytest -v python/cuopt_server/tests
+```

package/resources/skills/skills/nvidia/cuopt-developer/resources/contributing.md

@@ -0,0 +1,113 @@
+# Contributing — Commits, PRs, and Common Tasks
+
+Read this for anything related to committing, pushing, opening PRs, or making structural changes to cuOpt (adding a solver parameter, dependency, server endpoint, or CUDA kernel).
+
+## Before You Commit
+
+### 1. Install Pre-commit Hooks
+
+Run once per clone to have style checks run automatically on every `git commit`:
+
+```bash
+pre-commit install
+```
+
+If a hook fails, the commit is blocked — fix the issues and commit again. To check all files manually (e.g., before pushing), run `pre-commit run --all-files --show-diff-on-failure`.
+
+### 2. Make Meaningful Commits
+
+Group related changes into logical commits rather than committing all files at once. Each commit should represent one coherent change (e.g., separate the C++ change from the Python binding update from the test addition). This makes `git log` and `git bisect` useful for debugging later.
+
+### 3. Sign Your Commits (DCO Required)
+
+```bash
+git commit -s -m "Your message"
+```
+
+To fix a prior commit missing the sign-off, use `git commit --amend -s` (or an interactive rebase for older commits). Do **not** use `--no-verify` to bypass the DCO check.
+
+### 4. Use Forks for Pull Requests
+
+Never push branches directly to the main cuOpt repository. Use the fork workflow:
+
+```bash
+# 1. Clone the main repo
+git clone git@github.com:NVIDIA/cuopt.git
+cd cuopt
+
+# 2. Add your fork as a remote
+git remote add fork git@github.com:<your-username>/cuopt.git
+
+# 3. Create a branch from the appropriate base
+git checkout -b my-feature-branch
+
+# 4. Make changes, commit, then push to your fork
+git push fork my-feature-branch
+
+# 5. Create PR from your fork → upstream base branch
+```
+
+This applies to both human contributors and AI agents. Agents must never push to the upstream repo directly — provide the push command for the user to review and execute from their fork.
+
+### Pull Requests Created by Agents
+
+When an AI agent creates a pull request, it **must be a draft PR** (`gh pr create --draft`). This gives the developer time to review and iterate on the changes before any reviewers get pinged. The developer marks it as ready for review when satisfied.
+
+### PR Descriptions
+
+Keep summaries short — a paragraph or 3–5 bullets stating *what* and *why*. Skim recent merges on the target branch to calibrate.
+
+Skip how-it-works walkthroughs, file-by-file tables, exhaustive test-plan checklists, prose restatements of the diff, and screenshots of output the reviewer can reproduce locally. Reviewers read the code; long structured summaries signal LLM-generated and erode trust.
+
+For extra context (a design decision, unusual constraint, follow-up), one or two sentences with a link to an issue or doc beats expanding the body.
+
+### Writing scripts and CI workflows
+
+Follow YAGNI strictly here — flags, fallbacks, env-var overrides, and config knobs without a concrete failure mode they prevent should be dropped. This applies to scripts and CI workflows specifically, not the codebase as a whole.
+
+A few non-YAGNI points worth keeping in mind:
+
+- Prefer extending an existing script over adding a new one.
+- Validate inputs at the top, before any expensive work.
+- One shell command per line over chained `&&`; no comments that restate the next line.
+- Keep informational CI jobs (reporting, dashboards, comment posting) out of any required-checks list.
+
+When in doubt, mirror how the surrounding cuOpt code handles the same concern.
+
+## Common Tasks
+
+### Adding a Solver Parameter
+
+1. Add to settings struct in `cpp/include/cuopt/` and wire into `set_parameter_from_string()` in `cpp/src/`
+2. Expose in Python — if using the string-based interface, the parameter is auto-discovered (no `.pyx` change needed). Add a convenience method in `SolverSettings` if warranted. See [python_bindings.md](python_bindings.md) for the full checklist.
+3. Add to server schema (`docs/cuopt/source/cuopt_spec.yaml`) if applicable
+4. Add tests at C++ and Python levels
+5. Rebuild: `./build.sh libcuopt && ./build.sh cuopt`
+6. Update documentation
+
+### Adding a Dependency
+
+All dependencies are managed through `dependencies.yaml` — never edit `conda/environments/*.yaml` or `pyproject.toml` files directly. The file uses [RAPIDS dependency-file-generator](https://github.com/rapidsai/dependency-file-generator) format:
+
+1. Find the appropriate group in `dependencies.yaml` (e.g., `build_cpp`, `run_common`, `test_python_common`)
+2. Add the package under the correct `output_types` (`conda`, `requirements`, `pyproject`, or a combination)
+3. Run `pre-commit run --all-files` — the RAPIDS dependency file generator hook regenerates downstream files automatically
+4. Verify: check that `conda/environments/` and relevant `pyproject.toml` files were updated
+
+### Adding a Server Endpoint
+
+1. Add route in `python/cuopt_server/cuopt_server/webserver.py`
+2. Update OpenAPI spec `docs/cuopt/source/cuopt_spec.yaml`
+3. Add tests in `python/cuopt_server/tests/`
+4. Update documentation
+
+### Modifying CUDA Kernels
+
+1. Edit kernel in `cpp/src/`
+2. Follow stream-ordering patterns
+3. Run C++ tests: `ctest --test-dir cpp/build`
+4. Run benchmarks to check performance
+
+## Third-Party Code
+
+**Always ask before including external code.** When copying or adapting external code, you must attribute it properly, verify license compatibility, and flag it in the PR. See the [Third-Party Code section in CONTRIBUTING.md](../../../CONTRIBUTING.md#third-party-code) for the full process.

package/resources/skills/skills/nvidia/cuopt-developer/resources/conventions.md

@@ -0,0 +1,81 @@
+# Coding Conventions, Error Handling, and Memory Management
+
+Read this for cuOpt code style: naming, file extensions, include order, error handling, memory management, and test impact.
+
+## C++ Naming
+
+| Element | Convention | Example |
+|---------|------------|---------|
+| Variables | `snake_case` | `num_locations` |
+| Functions | `snake_case` | `solve_problem()` |
+| Classes | `snake_case` | `data_model` |
+| Test cases | `PascalCase` | `SolverTest` |
+| Device data | `d_` prefix | `d_locations_` |
+| Host data | `h_` prefix | `h_data_` |
+| Template params | `_t` suffix | `value_t` |
+| Private members | `_` suffix | `n_locations_` |
+
+## File Extensions
+
+| Extension | Usage |
+|-----------|-------|
+| `.hpp` | C++ headers |
+| `.cpp` | C++ source |
+| `.cu` | CUDA source (nvcc required) |
+| `.cuh` | CUDA headers with device code |
+
+## Include Order
+
+1. Local headers
+2. RAPIDS headers
+3. Related libraries
+4. Dependencies
+5. STL
+
+## Python Style
+
+- Follow PEP 8
+- Use type hints
+- Tests use pytest
+
+## Error Handling
+
+### Runtime Assertions
+
+```cpp
+CUOPT_EXPECTS(condition, "Error message");
+CUOPT_FAIL("Unreachable code reached");
+```
+
+### CUDA Error Checking
+
+```cpp
+RAFT_CUDA_TRY(cudaMemcpy(...));
+```
+
+## Memory Management
+
+```cpp
+// ❌ WRONG
+int* data = new int[100];
+
+// ✅ CORRECT - use RMM
+rmm::device_uvector<int> data(100, stream);
+```
+
+- All operations should accept `cuda_stream_view`
+- Views (`*_view` suffix) are non-owning
+
+Read existing code in `cpp/src/` for real examples of RMM allocation, stream-ordering, RAFT utilities, and kernel launch patterns.
+
+## Test Impact Check
+
+**Before any behavioral change, ask:**
+
+1. What scenarios must be covered?
+2. What's the expected behavior contract?
+3. Where should tests live?
+   - C++ gtests: `cpp/tests/`
+   - Python pytest: `python/.../tests/`
+
+**Add at least one regression test for new behavior.**

package/resources/skills/skills/nvidia/cuopt-developer/resources/first_time_setup.md

@@ -0,0 +1,32 @@
+# First-Time Dev Environment Setup
+
+Read this when a contributor is setting up the cuOpt dev environment for the first time — clone, conda env, initial build, initial test run. Once that's working, the rest of `cuopt-developer` (build/test commands, conventions, contribution workflow) takes over.
+
+## Required questions
+
+Ask these before issuing commands:
+
+1. **OS and GPU** — Linux? Which CUDA version does the GPU driver support (run `nvidia-smi`, top-right "CUDA Version")?
+2. **Goal** — Contributing upstream, or local fork/modification?
+3. **Component** — C++/CUDA core, Python bindings, server, docs, or CI?
+
+The component answer scopes which part of the codebase to read first and which build target to use (e.g. `./build.sh libcuopt` vs `./build.sh cuopt`).
+
+## Setup walk-through (conceptual)
+
+1. **Clone** the cuOpt repo (and submodules, if any).
+2. **Pre-flight checks** — CUDA driver compatibility, conda env selection and activation, `PARALLEL_LEVEL`, dataset setup. Walk through these before the first build using SKILL.md → [Pre-flight Checks](../SKILL.md#pre-flight-checks-required-before-first-build-or-test). Skipping any of them surfaces as confusing build- or runtime errors later.
+3. **First build** — once the env is active, run `./build.sh` (or a component-scoped variant). Targets and `PARALLEL_LEVEL` tuning live in [build_and_test.md](build_and_test.md).
+4. **First test run** — fetch datasets per `CONTRIBUTING.md` first, then run the C++/Python test suites from [build_and_test.md](build_and_test.md). A passing build + test confirms the env is wired up correctly.
+5. **Optional** — `pre-commit install` to run style checks on every `git commit` (see [contributing.md](contributing.md)).
+
+Use the repo's `README` and `CONTRIBUTING.md` as the canonical source for exact versions and any deviations.
+
+## After setup
+
+Once `./build.sh` and the test suites succeed, the env is verified. From here, ongoing build/test/debug/contribute work is covered by the rest of `cuopt-developer`:
+
+- Build/test commands and `PARALLEL_LEVEL` — [build_and_test.md](build_and_test.md)
+- Pre-commit, DCO sign-off, fork PR workflow — [contributing.md](contributing.md)
+- C++/Python/CUDA naming, memory, testing conventions — [conventions.md](conventions.md)
+- Build/CI failure diagnosis — [troubleshooting.md](troubleshooting.md)

package/resources/skills/skills/nvidia/cuopt-developer/resources/python_bindings.md

@@ -0,0 +1,233 @@
+# Python Bindings Guide
+
+How Python bindings work in cuOpt and how to extend them.
+
+## Architecture: Three Layers
+
+```text
+Python API Layer (.py)        ← User-facing, docstrings, convenience methods
+        ↓
+Cython Wrapper Layer (.pyx)   ← Memory management, GIL handling, type conversion
+        ↓
+C++ Implementation (.hpp/.cu) ← Solver logic, CUDA kernels
+```
+
+## Key Directories
+
+| Layer | Path | Purpose |
+|-------|------|---------|
+| Library loader | `python/libcuopt/libcuopt/load.py` | Dynamically loads `libcuopt.so` via ctypes |
+| Python API | `python/cuopt/cuopt/linear_programming/` | User-facing classes (`Problem`, `SolverSettings`) |
+| Python API | `python/cuopt/cuopt/routing/` | Routing API |
+| Cython bindings | `python/cuopt/cuopt/linear_programming/solver/solver_wrapper.pyx` | Solver bridge |
+| Cython bindings | `python/cuopt/cuopt/linear_programming/data_model/data_model_wrapper.pyx` | Data model bridge |
+| Cython declarations | `python/cuopt/cuopt/linear_programming/solver/solver.pxd` | C++ interface declarations |
+| Cython declarations | `python/cuopt/cuopt/linear_programming/data_model/data_model.pxd` | C++ interface declarations |
+| C++ headers | `cpp/include/cuopt/linear_programming/` | Public API |
+| C++ implementation | `cpp/src/` | Solver internals |
+
+## File Types
+
+| Extension | Purpose | Example |
+|-----------|---------|---------|
+| `.pxd` | Cython declaration — declares C++ classes, functions, enums for Cython | `solver.pxd` |
+| `.pyx` | Cython implementation — wraps C++ in Python-callable code | `solver_wrapper.pyx` |
+| `.py` | Pure Python — user-facing API, no direct C++ calls | `solver.py`, `data_model.py` |
+
+## How a Parameter Flows: End-to-End Example
+
+Tracing `optimality_tolerance` from Python to C++:
+
+### Step 1: User Python code
+
+```python
+settings = SolverSettings()
+settings.set_optimality_tolerance(1e-2)
+solution = linear_programming.Solve(data_model, settings)
+```
+
+### Step 2: Python API stores the setting
+
+`python/cuopt/cuopt/linear_programming/solver_settings/solver_settings.py`:
+
+```python
+def set_optimality_tolerance(self, eps_optimal):
+    for param in solver_params:
+        if param.endswith("tolerance"):
+            self.settings_dict[param] = eps_optimal
+```
+
+Parameters are discovered at import time from C++ via reflection (see step 3).
+
+### Step 3: Cython discovers parameter names from C++
+
+`python/cuopt/cuopt/linear_programming/solver/solver_parameters.pyx`:
+
+```cython
+cpdef get_solver_parameter_names():
+    cdef unique_ptr[solver_settings_t[int, double]] unique_solver_settings
+    unique_solver_settings.reset(new solver_settings_t[int, double]())
+    cdef vector[string] parameter_names = unique_solver_settings.get().get_parameter_names()
+
+    cdef list py_parameter_names = []
+    for i in range(parameter_names.size()):
+        py_parameter_names.append(parameter_names[i].decode("utf-8"))
+    return py_parameter_names
+
+solver_params = get_solver_parameter_names()  # Called at import time
+```
+
+### Step 4: Cython passes settings to C++
+
+`python/cuopt/cuopt/linear_programming/solver/solver_wrapper.pyx`:
+
+```cython
+cdef set_solver_setting(
+        unique_ptr[solver_settings_t[int, double]]& unique_solver_settings,
+        settings, ...):
+    cdef solver_settings_t[int, double]* c_solver_settings = unique_solver_settings.get()
+    for name, value in settings.settings_dict.items():
+        c_solver_settings.set_parameter_from_string(
+            name.encode('utf-8'),
+            str(value).encode('utf-8')
+        )
+```
+
+### Step 5: Cython calls C++ solver with GIL released
+
+```cython
+def Solve(py_data_model_obj, settings, mip=False):
+    # ... setup ...
+    with nogil:  # Release Python GIL for GPU computation
+        sol_ret_ptr = move(call_solve(
+            data_model_obj.c_data_model_view.get(),
+            unique_solver_settings.get(),
+        ))
+    return create_solution(move(sol_ret_ptr), data_model_obj)
+```
+
+### Step 6: C++ implementation receives the call
+
+`cpp/src/math_optimization/solver_settings.cu`:
+
+```cpp
+void solver_settings_t<i_t, f_t>::set_parameter_from_string(
+    const std::string& name, const std::string& value)
+{
+    // Routes to appropriate setter
+    pdlp_settings_.set_optimality_tolerance(std::stof(value));
+}
+```
+
+## Key Cython Patterns
+
+### Declaring C++ classes in .pxd
+
+```cython
+cdef extern from "cuopt/linear_programming/solver_settings.hpp" namespace "cuopt::linear_programming":
+    ctypedef enum pdlp_solver_mode_t "cuopt::linear_programming::pdlp_solver_mode_t":
+        Stable1 "cuopt::linear_programming::pdlp_solver_mode_t::Stable1"
+        Stable2 "cuopt::linear_programming::pdlp_solver_mode_t::Stable2"
+
+    cdef cppclass solver_settings_t[i_t, f_t]:
+        solver_settings_t() except +
+        vector[string] get_parameter_names()
+        void set_parameter_from_string(const string& name, const string& value) except +
+```
+
+### C++ object lifecycle with unique_ptr
+
+```cython
+from libcpp.memory cimport unique_ptr, move
+
+cdef unique_ptr[solver_settings_t[int, double]] settings
+settings.reset(new solver_settings_t[int, double]())
+# Auto-destroyed when scope exits
+```
+
+### Releasing the GIL for GPU work
+
+```cython
+with nogil:
+    result = move(call_solve(problem_ptr, settings_ptr))
+```
+
+Always release the GIL around C++ calls that do GPU work. This allows other Python threads to run during solve.
+
+### Bridging C++ enums to Python IntEnum
+
+```python
+class PDLPSolverMode(IntEnum):
+    Stable1 = pdlp_solver_mode_t.Stable1
+    Stable2 = pdlp_solver_mode_t.Stable2
+```
+
+### Type conversions
+
+| Direction | Pattern |
+|-----------|---------|
+| Python `str` → C++ `string` | `name.encode('utf-8')` |
+| C++ `string` → Python `str` | `cstring.decode('utf-8')` |
+| C++ `vector<double>` → numpy | `np.asarray(<double[:size]> vec.data()).copy()` |
+| numpy → C++ pointer | Pass `.data` pointer via Cython typed memoryview |
+
+### Device memory handling
+
+```cython
+from rmm.pylibrmm.device_buffer import DeviceBuffer
+
+if result_ptr.is_gpu():
+    solution_buf = DeviceBuffer.c_from_unique_ptr(
+        move(get_gpu_solution(result_ptr[0]))
+    )
+    solution = series_from_buf(solution_buf, pa.float64()).to_numpy()
+```
+
+## Build System
+
+Cython modules are built via CMake + rapids-cython-core.
+
+### CMakeLists.txt pattern
+
+`python/cuopt/cuopt/linear_programming/solver/CMakeLists.txt`:
+
+```cmake
+set(cython_sources solver_wrapper.pyx solver_parameters.pyx)
+set(linked_libraries cuopt::cuopt)
+rapids_cython_create_modules(...)
+```
+
+### Build command
+
+```bash
+./build.sh cuopt    # Builds Cython extensions + Python package
+```
+
+After modifying `.pyx` or `.pxd` files, you must rebuild: Cython changes are **not** reflected until recompiled.
+
+## Adding a New Parameter: Checklist
+
+1. **C++ header** — Add parameter to settings struct in `cpp/include/cuopt/`
+2. **C++ implementation** — Add setter/getter and wire into `set_parameter_from_string()` in `cpp/src/`
+3. **Cython declaration (.pxd)** — If the parameter requires a new C++ method signature, declare it
+4. **Cython wrapper (.pyx)** — If using the string-based parameter interface (`set_parameter_from_string`), no `.pyx` change is needed — the parameter is auto-discovered via reflection
+5. **Python API (.py)** — Add a convenience method in `SolverSettings` if warranted
+6. **Server schema** — Update `docs/cuopt/source/cuopt_spec.yaml` if the parameter should be server-accessible
+7. **Tests** — Add tests at both C++ (`cpp/tests/`) and Python (`python/cuopt/cuopt/tests/`) levels
+8. **Rebuild** — `./build.sh libcuopt && ./build.sh cuopt`
+
+## Lazy Loading Pattern
+
+`python/cuopt/cuopt/__init__.py` uses lazy imports for CPU-only environments:
+
+```python
+_submodules = ["linear_programming", "routing", "distance_engine"]
+
+def __getattr__(name):
+    if name in _submodules:
+        import importlib
+        return importlib.import_module(f"cuopt.{name}")
+    raise AttributeError(...)
+```
+
+This allows importing `cuopt` on hosts without a GPU (e.g., for remote solve via server).

package/resources/skills/skills/nvidia/cuopt-developer/resources/troubleshooting.md

@@ -0,0 +1,26 @@
+# Troubleshooting & CI Gotchas
+
+Read this when a build, test, or CI step fails — symptoms, causes, fixes.
+
+## Common Pitfalls
+
+| Problem | Solution |
+|---------|----------|
+| Cython changes not reflected | Rerun: `./build.sh cuopt` |
+| Missing `nvcc` | Set `$CUDACXX` or add CUDA to `$PATH` |
+| OOM during build | Lower `PARALLEL_LEVEL` (e.g., `export PARALLEL_LEVEL=8`) |
+| CUDA out of memory | Reduce problem size |
+| Build fails with CUDA errors on older driver | Conda installs `cuda-nvcc` for the latest supported CUDA (e.g., 13.1), but the user's GPU driver may not support it. Have the user check with `nvidia-smi` — the top-right shows max CUDA version. Provide this command for the user to run (do not run it yourself): `conda install cuda-nvcc=12.9` (or whichever version their driver supports). See [CUDA compatibility matrix](https://docs.nvidia.com/deploy/cuda-compatibility/) |
+| Slow debug library loading | Device symbols cause delay |
+
+## CI Gotchas
+
+| Failure | Cause | Fix |
+|---------|-------|-----|
+| Style check | Formatting drift | Run `pre-commit run --all-files` and commit fixes |
+| DCO sign-off | Missing `-s` flag | `git commit --amend -s` (or rebase to fix older commits) |
+| Dependency mismatch | Edited `pyproject.toml` or `conda/environments/` directly | Edit `dependencies.yaml` instead, let pre-commit regenerate |
+| Cross-suffix dep collision (e.g. `cuopt-sh-client` → `cuopt`) | A pure-Python (CUDA-agnostic) wheel transitively depends on a CUDA-suffixed sibling. PyPI only publishes the `*-cu12` / `*-cu13` variants, which install to the same Python package directory and cannot coexist. An unsuffixed pin fails to resolve; a hardcoded suffix collides with the other suffix when a co-installed package (e.g. `cuopt-server-cu12`) pulls in the opposite one. | Avoid the hard dep. Make the import lazy (`try: from cuopt... except ImportError: ...`) and expose the dep as an opt-in `[<extra>]` extra in `pyproject.toml`. Document that users on the non-default CUDA major must pip-install the matching suffixed wheel themselves rather than relying on the extra. The conda recipe can still depend on the unsuffixed sibling, since conda doesn't have the suffix conflict. |
+| Skill validation | Missing frontmatter or version mismatch | Run `./ci/utils/validate_skills.sh` locally to diagnose |
+
+For CI scripts and pipeline details, see [ci/README.md](../../../ci/README.md).

package/resources/skills/skills/nvidia/cuopt-install/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: cuopt-install
+version: "26.08.00"
+description: Install cuOpt for Python, C, or as a server (pip, conda, Docker) — system requirements, install commands, and verification. Use when the user wants to install or verify cuOpt for any user-facing interface. For building cuOpt from source or contributing to cuOpt, see cuopt-developer.
+---
+
+# cuOpt Install (user)
+
+Install cuOpt to *use* it from Python, C, or as a REST server. For building cuOpt from source to contribute or modify it, see `cuopt-developer`.
+
+## System requirements
+
+- **GPU**: NVIDIA Compute Capability ≥ 7.0 (Volta or newer). Examples: V100, A100, H100, RTX 20xx/30xx/40xx. Not supported: GTX 10xx (Pascal).
+- **CUDA**: 12.x or 13.x. The package CUDA suffix must match the runtime CUDA (e.g. `cuopt-cu12` / `libcuopt-cu12` with CUDA 12).
+- **Driver**: NVIDIA driver compatible with the CUDA version.
+- `cuopt-cuXX` (Python) depends on `libcuopt-cuXX` (C), so installing the Python package also installs the C library and headers. Installing `libcuopt-cuXX` on its own does **not** install the Python API.
+
+## Required questions
+
+Ask these if not already clear:
+
+1. **Interface** — Python, C, or REST server? Server can be called from any language via HTTP.
+2. **CUDA version** — What is installed? Check with `nvcc --version` or `nvidia-smi`.
+3. **Package manager** — pip, conda, or Docker preferred?
+4. **Environment** — Local machine with GPU, cloud instance, Docker/Kubernetes, or remote/server (no local GPU)?
+
+## Python API
+
+**Choose one** — do not run both. The second install would override the first and can cause CUDA / package mismatch.
+
+### pip
+
+- **CUDA 13.x:**
+  ```bash
+  pip install --extra-index-url=https://pypi.nvidia.com cuopt-cu13
+  ```
+- **CUDA 12.x:**
+  ```bash
+  pip install --extra-index-url=https://pypi.nvidia.com 'cuopt-cu12==26.2.*'
+  ```
+
+### conda
+
+```bash
+conda install -c rapidsai -c conda-forge -c nvidia cuopt
+```
+
+### Verify
+
+```python
+import cuopt
+print(cuopt.__version__)
+from cuopt import routing
+dm = routing.DataModel(n_locations=3, n_fleet=1, n_orders=2)
+```
+
+## C API
+
+The C API ships in `libcuopt-cuXX`, which is also pulled in as a dependency of `cuopt-cuXX` — so if you already installed the Python package, the C library and headers are already present. Install `libcuopt` standalone only when you want the C API without Python. **Choose one** of pip or conda — do not run both.
+
+### pip
+
+- **CUDA 13.x:**
+  ```bash
+  pip install --extra-index-url=https://pypi.nvidia.com libcuopt-cu13
+  ```
+- **CUDA 12.x:**
+  ```bash
+  pip install --extra-index-url=https://pypi.nvidia.com 'libcuopt-cu12==26.2.*'
+  ```
+
+### conda
+
+```bash
+conda install -c rapidsai -c conda-forge -c nvidia libcuopt
+```
+
+### Verify
+
+```bash
+# conda:
+find $CONDA_PREFIX -name "cuopt_c.h"
+find $CONDA_PREFIX -name "libcuopt.so"
+
+# pip (venv):
+find "$(python -c 'import sys; print(sys.prefix)')" -name "cuopt_c.h"
+find "$(python -c 'import sys; print(sys.prefix)')" -name "libcuopt.so"
+```
+
+## Server (REST)
+
+### pip
+
+```bash
+pip install --extra-index-url=https://pypi.nvidia.com cuopt-server-cu12 cuopt-sh-client
+```
+
+### conda
+
+```bash
+conda install -c rapidsai -c conda-forge -c nvidia cuopt-server cuopt-sh-client
+```
+
+### Docker
+
+```bash
+docker pull nvidia/cuopt:latest-cuda12.9-py3.13
+docker run --gpus all -it --rm -p 8000:8000 nvidia/cuopt:latest-cuda12.9-py3.13
+```
+
+### Verify
+
+```bash
+python -m cuopt_server.cuopt_service --ip 0.0.0.0 --port 8000 &
+sleep 5
+curl -s http://localhost:8000/cuopt/health | jq .
+```
+
+## Common Issues
+
+- `No module named 'cuopt'` → check `pip list | grep cuopt`, `which python`, reinstall with the correct extra-index-url.
+- CUDA not available → run `nvidia-smi` and `nvcc --version`; ensure the package CUDA suffix (`cu12` vs `cu13`) matches the installed CUDA.
+- Python vs C → `cuopt-cuXX` pulls in `libcuopt-cuXX` as a transitive dependency, so the C library (`libcuopt.so`) and headers (`cuopt_c.h`) are already available after installing the Python package. The reverse is **not** true: `libcuopt-cuXX` alone does not install the Python bindings.
+
+## See also
+
+- [verification_examples.md](resources/verification_examples.md) — full verification recipes for Python, C, server, and Docker.
+- `cuopt-developer` — build cuOpt from source and contribute to the codebase.