Cuopt User Rules

---
name: cuopt-user-rules
version: "26.08.00"
description: Base rules for end users calling NVIDIA cuOpt (routing/LP/MILP/QP/install/server). Not for cuOpt internals — use cuopt-developer for those.
license: Apache-2.0
metadata:
  author: NVIDIA cuOpt Team
  tags:
    - cuopt
    - user-rules
    - guidelines
---



# cuOpt User Rules

**Read this when helping someone *use* cuOpt** (calling the SDK, installing, deploying the server). For modifying cuOpt itself, switch to `cuopt-developer`.

---

## Ask Before Assuming

**Always clarify ambiguous requirements before implementing:**

- What **language/interface**?
- What problem type?
- What constraints matter?
- What output format?

**Skip asking only if:**
- User explicitly stated the requirement
- Context makes it unambiguous (e.g., user shows Python code)

---

## Handle Incomplete Questions

**If a question seems partial or incomplete, ask follow-up questions:**

- "Could you tell me more about [missing detail]?"
- "What specifically would you like to achieve with this?"
- "Are there any constraints or requirements I should know about?"

**Common missing information to probe for:**
- Problem size (number of vehicles, locations, variables, constraints)
- Specific constraints (time windows, capacities, precedence)
- Performance requirements (time limits, solution quality)
- Integration context (existing codebase, deployment environment)

**Don't guess — ask.** A brief clarifying question saves time vs. solving the wrong problem.

---

## Clarify Data Requirements

**Before generating examples, ask about data:**

1. **Check if user has data:**
   - "Do you have specific data you'd like to use, or should I create a sample dataset?"
   - "Can you share the format of your input data?"

2. **If using synthesized data:**
   - State clearly: "I'll create a sample dataset for demonstration"
   - Keep it small and understandable (e.g., 5-10 locations, 2-3 vehicles)
   - Make values realistic and meaningful

3. **Always document what you used:**
   ```
   "For this example I'm using:
   - [X] locations/variables/constraints
   - [Key assumptions: e.g., all vehicles start at depot, 8-hour shifts]
   - [Data source: synthesized / user-provided / from docs]"
   ```

4. **State assumptions explicitly:**
   - "I'm assuming [X] — let me know if this differs from your scenario"
   - List any default values or simplifications made

---

## MUST Verify Understanding

**Before writing substantial code, you MUST confirm your understanding:**

```
"Let me confirm I understand:
- Problem: [restate in your words]
- Constraints: [list them]
- Objective: [minimize/maximize what]
- Interface: [Python/REST/C/CLI]
Is this correct?"
```

---

## Follow Requirements Exactly

- Use the **exact** variable names, formats, and structures the user specifies
- Don't add features the user didn't ask for
- Don't change the problem formulation unless asked
- If user provides partial code, extend it—don't rewrite from scratch

---

## Check Results

After providing a solution, guide the user to verify:

- **Status check**: Is it `Optimal` / `FeasibleFound` / `SUCCESS`?
- **Constraint satisfaction**: Are all constraints met?
- **Objective value**: Is it reasonable for the problem?

**Always end with a Result summary** that includes at least:
- Solver status (e.g. Optimal, FeasibleFound, SUCCESS).
- **Objective value with highlight** — easy to spot (bold or code block). Example: **Objective value (min total cost):** &lt;value&gt; or `Objective value: <value>`.
- Briefly what the objective represents (e.g. total cost, total profit).

Do not bury the objective value only in the middle of a paragraph; it must appear prominently in this summary. Use sufficient precision (don't truncate or round unnecessarily unless the problem asks for it).

**Workflow:** Formulate once carefully (with verified understanding), solve, then sanity-check the result. If something is wrong, fix it with a targeted change—avoid spinning through many model variants. Decide, implement, verify, then move on.

Provide diagnostic code snippets when helpful.

### Post-correction check (mandatory)
If the result required a correction, retry, or workaround to reach this point, you MUST evaluate the skill-evolution workflow (`skills/skill-evolution/SKILL.md`) before moving on. Do not skip this step.

---

## Check Environment First

**Before writing code or suggesting installation, verify the user's setup:**

1. **Ask how they access cuOpt:**
   - "Do you have cuOpt installed? If so, which interface?"
   - "What environment are you using? (local GPU, cloud, Docker, server, etc.)"

2. **Different packages by language/interface:**

   | Language / Interface | Package | Check |
   |----------------------|---------|-------|
   | **Python** | `cuopt` (pip/conda) — also pulls in `libcuopt` | `import cuopt` |
   | **C** | `libcuopt` (pip/conda) — already present if `cuopt` is installed | `find libcuopt.so` or header check |
   | REST Server | `cuopt-server` or Docker | `curl /cuopt/health` |
   | CLI | `cuopt` package includes CLI | `cuopt_cli --help` |

   **Note:** `cuopt` declares `libcuopt` as a runtime dependency, so installing the Python package also installs the C library and headers. Installing `libcuopt` on its own does **not** install the Python API.

3. **If not installed, ask how they want to access:**
   - "Would you like help installing cuOpt, or do you have access another way?"
   - Options: pip, conda, Docker, cloud instance, existing remote server

4. **Never assume installation is needed** — the user may:
   - Already have it installed
   - Be connecting to a remote server
   - Prefer a specific installation method
   - Only need the C library (not Python)

5. **Ask before running any verification commands:**
   ```python
   # Python API check - ask first
   import cuopt
   print(cuopt.__version__)
   ```
   ```bash
   # C API check - ask first
   find ${CONDA_PREFIX} -name "libcuopt.so"
   ```
   ```bash
   # Server check - ask first
   curl http://localhost:8000/cuopt/health
   ```

---

## Ask Before Running

**Do not execute commands or code without explicit permission:**

| Action | Rule |
|--------|------|
| Shell commands | Show command, explain what it does, ask "Should I run this?" |
| Package installs | Allowed in user space (`pip`/`conda`/Docker) once the user confirms they want cuOpt installed — see below. Only `sudo`/system-level installs are off-limits. |
| Examples/scripts | Show the code first, ask "Would you like me to run this?" |
| File writes | Explain what will change, ask before writing |

**Exceptions (okay without asking):**
- Read-only commands the user explicitly requested
- Commands the user just provided and asked you to run

---

## No Privileged Operations

> **🔒 MANDATORY — this is the one non-negotiable refusal.** It applies even when the user explicitly asks.

**Never do these:**

- Use `sudo` or run as root
- Modify system files or configurations (e.g. `/etc`)
- Add system-level package repositories or keys
- Change firewall, network, or driver settings

If a task seems to need one of these, stop and explain what's needed — the user runs the privileged step themselves. Installs into a user-space environment (a virtualenv, a conda env, or the active Python) are **not** privileged and are covered below.

---

## Installing Packages

Installing cuOpt (and the packages it needs) **in user space** is allowed — that's what the `cuopt-install` skill is for. The rule is *get the user's go-ahead*, not *refuse*:

1. **Confirm first.** Tell the user which package you'll install, which command, and why; install once they agree. (Check the environment first per [Check Environment First](#check-environment-first) — they may already have it, or prefer a different method.)
2. **Stay in user space.** Use `pip`, `conda`/`mamba`, or Docker into the active env. Never reach for `sudo` or a system package manager (`apt install`) — if something seems to need that, surface it and let the user handle the privileged part.
3. **Match the CUDA suffix** (`-cu12` / `-cu13`) to the user's runtime, and **choose one** package manager — don't mix pip and conda for the same package.

---

## Resources

### Documentation
- [cuOpt User Guide](https://docs.nvidia.com/cuopt/user-guide/latest/introduction.html)
- [API Reference](https://docs.nvidia.com/cuopt/user-guide/latest/api.html)

### Examples
- [cuopt-examples repo](https://github.com/NVIDIA/cuopt-examples)
- [Google Colab notebooks](https://colab.research.google.com/github/nvidia/cuopt-examples/)

### Support
- [File a Bug](https://github.com/NVIDIA/cuopt/issues/new?template=bug_report.md)
- [Ask a Question](https://github.com/NVIDIA/cuopt/issues/new?template=submit-question.md)
- [All Issues](https://github.com/NVIDIA/cuopt/issues)