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?"

1. 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

1. 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]" ``

1. 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): <value> 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.)"

1. Different packages by language/interface:

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.

1. 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

1. 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)

1. 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:

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
• API Reference

Examples

• cuopt-examples repo
• Google Colab notebooks

Support

• File a Bug
• Ask a Question
• All Issues