From 528424a3cd86bb68a72fcb54af4f8431cb34619d Mon Sep 17 00:00:00 2001 From: Ramakrishna Prabhu Date: Fri, 20 Nov 2026 10:32:58 -0600 Subject: [PATCH 1/5] Add a cuOpt skill bridging agents to API details and gotchas A thin entry point for agents working with cuOpt. It routes to the right part of the user guide for whatever is being done, and names the few API behaviours that are not written down anywhere else. Behaviours that merely surprise -- a status or a result that reads as a solver problem rather than a usage error -- are collected under Common Pitfalls in the FAQ, so the skill points at that section rather than restating it. The pointer names the file in this repo as well as the published page, since the published docs lag the release. What stays inline is what no document covers: addConstraint requiring a comparison, LinearExpression taking constant as a required positional, and the solver writing its own log to stdout. The description is narrow -- writing or debugging code that calls cuOpt -- so the skill is not pulled into context for questions the documentation answers. Co-Authored-By: Claude Opus 5 (1M context) Signed-off-by: Ramakrishna Prabhu --- .claude-plugin/marketplace.json | 6 ++++ AGENTS.md | 2 ++ skills/cuopt/SKILL.md | 50 +++++++++++++++++++++++++++++++++ 3 files changed, 58 insertions(+) create mode 100644 skills/cuopt/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 5f16fb810f..eb170d4eb1 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -8,6 +8,12 @@ "version": "26.12.00" }, "plugins": [ + { + "name": "cuopt", + "source": "./skills/cuopt", + "skills": "./", + "description": "Entry point for working with cuOpt: links into the user guide for install, settings and the API reference, plus API gotchas. Use when writing or debugging code that calls cuOpt." + }, { "name": "cuopt-user-rules", "source": "./skills/cuopt-user-rules", diff --git a/AGENTS.md b/AGENTS.md index 2c7f6e0c96..2cfe71632f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,8 @@ AI agent skills for NVIDIA cuOpt optimization engine. Skills live in **`skills/` ## Skills directory (flat) +- `skills/cuopt/` — Entry point for working with cuOpt: links into the user guide for install, settings and the API reference, plus API gotchas. Read when writing or debugging code that calls cuOpt. + ### Rules - `skills/cuopt-user-rules/` — Base rules for end users calling cuOpt (routing, LP, MILP, QP, install, server). Not for cuOpt internals — see `skills/cuopt-developer/`. Read first for user-facing tasks; choose skills from the index below by task and interface. - `skills/cuopt-developer/` — Modify, build, test, debug, and contribute to cuOpt internals (C++/CUDA, Python, server, CI). Use for solver internals, PRs, DCO, and code conventions. For **VRP dimension** work (combine invariants, fwd/bwd propagation, new constraints/objectives in the routing engine), read **`skills/cuopt-developer/references/vrp_skills.md`** in addition to `SKILL.md`. diff --git a/skills/cuopt/SKILL.md b/skills/cuopt/SKILL.md new file mode 100644 index 0000000000..91569889f6 --- /dev/null +++ b/skills/cuopt/SKILL.md @@ -0,0 +1,50 @@ +--- +name: cuopt +version: "26.12.00" +description: Entry point for working with cuOpt: links into the user guide for install, settings and the API reference, plus API gotchas. Use when writing or debugging code that calls cuOpt. +license: Apache-2.0 +metadata: + author: NVIDIA cuOpt Team + tags: + - cuopt +--- + +# cuOpt + +## Where things are + +| | | +|---|---| +| Source | https://github.com/NVIDIA/cuopt | +| Docs (always use `latest`) | https://docs.nvidia.com/cuopt/user-guide/latest/ | +| Install, channels, Docker | https://docs.nvidia.com/cuopt/user-guide/latest/install.html | +| GPU / CUDA / driver support | https://docs.nvidia.com/cuopt/user-guide/latest/system-requirements.html | +| LP / QP settings | https://docs.nvidia.com/cuopt/user-guide/latest/convex-settings.html | +| MILP settings | https://docs.nvidia.com/cuopt/user-guide/latest/mip-settings.html | +| Python API reference | https://docs.nvidia.com/cuopt/user-guide/latest/cuopt-python/ | +| LP / QP examples | https://docs.nvidia.com/cuopt/user-guide/latest/cuopt-python/convex/convex-examples.html | +| MILP examples | https://docs.nvidia.com/cuopt/user-guide/latest/cuopt-python/mip/mip-examples.html | +| Routing (Python only) | https://docs.nvidia.com/cuopt/user-guide/latest/cuopt-python/routing/ | +| REST server | https://docs.nvidia.com/cuopt/user-guide/latest/cuopt-server/ | +| FAQ | https://docs.nvidia.com/cuopt/user-guide/latest/faq.html | + +Settings names, defaults and ranges change between releases — read them from the docs or from +`SolverSettings`, never from memory. + +## Gotchas + +Solver statuses and results that surprise you are answered under **Common Pitfalls** in the +FAQ: `docs/cuopt/source/faq.rst` in this repo, published at +https://docs.nvidia.com/cuopt/user-guide/latest/faq.html + +Additional gotchas are listed below. + +**`addConstraint` requires a comparison** (`<=`, `>=`, `==`). Accumulate an expression in a +loop, then compare it in the call; passing a bare expression raises `ValueError: +addConstraint requires a Constraint object`. Constraints cannot be built as strings. + +**`LinearExpression` takes `constant` as a required positional**, not an optional keyword: +`LinearExpression([x, y], [1.0, 2.0], 0.0)`. Prefer ordinary arithmetic or `sum(...)` and +reach for it only when recursion depth is a concern. + +**The solver prints its own log to stdout.** That is expected, not an error. From bc4e160377e9c678ae73ec9baf962cbf349d1f31 Mon Sep 17 00:00:00 2001 From: Ramakrishna Prabhu Date: Fri, 20 Nov 2026 14:53:22 -0600 Subject: [PATCH 2/5] Add evals for the cuopt skill Six cases covering the three inline gotchas and the documentation routing the skill exists to provide. Co-Authored-By: Claude Opus 5 (1M context) Signed-off-by: Ramakrishna Prabhu --- skills/cuopt/evals/evals.json | 80 +++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 skills/cuopt/evals/evals.json diff --git a/skills/cuopt/evals/evals.json b/skills/cuopt/evals/evals.json new file mode 100644 index 0000000000..ca1cfcd87e --- /dev/null +++ b/skills/cuopt/evals/evals.json @@ -0,0 +1,80 @@ +[ + { + "id": "cuopt-eval-001-addconstraint-requires-comparison", + "question": "I'm building a cuOpt model in Python. I have a list of variables `x` and weights `w`, and I want the weighted sum to be at most 100. I tried `model.addConstraint(sum(w[i] * x[i] for i in range(n)))` and also `model.addConstraint(\"w @ x <= 100\")`, and neither works. What should I write?", + "expected_skill": "cuopt", + "expected_script": null, + "ground_truth": "The agent explains that addConstraint takes a Constraint object, which is produced by comparing an expression with <=, >= or ==, so a bare expression raises ValueError: addConstraint requires a Constraint object. It also states that constraints cannot be written as strings. The corrected call accumulates the expression and compares it in place, e.g. model.addConstraint(sum(w[i] * x[i] for i in range(n)) <= 100).", + "expected_behavior": [ + "Identifies the missing comparison operator as the cause, not the sum or the generator", + "States that a bare expression raises ValueError: addConstraint requires a Constraint object", + "States that a constraint cannot be built from a string", + "Gives a corrected call containing a <=, >= or == comparison" + ] + }, + { + "id": "cuopt-eval-002-linearexpression-constant-positional", + "question": "In cuOpt Python, I called `LinearExpression([x, y], [1.0, 2.0])` and got a TypeError about a missing argument. How do I construct it, and should I be using it here at all for a simple two-term sum?", + "expected_skill": "cuopt", + "expected_script": null, + "ground_truth": "The agent explains that LinearExpression takes constant as a required positional argument rather than an optional keyword, so the call needs a third argument: LinearExpression([x, y], [1.0, 2.0], 0.0). It also advises that for an ordinary short sum, plain arithmetic or sum(...) is the better choice, and LinearExpression is worth reaching for mainly when recursion depth over a long accumulation is a concern.", + "expected_behavior": [ + "Names constant as a required positional third argument", + "Shows a corrected call that passes the constant explicitly, e.g. 0.0", + "Recommends ordinary arithmetic or sum(...) for a simple expression", + "Mentions recursion depth over long accumulations as the reason LinearExpression exists" + ] + }, + { + "id": "cuopt-eval-003-solver-log-on-stdout", + "question": "I'm calling cuOpt from a Python script and it's dumping a wall of solver output to my terminal before my own print statements. Is something misconfigured, and is this going to break my script if I run it in a pipeline?", + "expected_skill": "cuopt", + "expected_script": null, + "ground_truth": "The agent explains that the solver writes its own log to stdout and that this is expected behaviour, not an error or a misconfiguration. It reassures that the solve itself is unaffected, and does not invent a settings flag to suppress it; if asked how to control verbosity it directs the reader to the solver settings pages rather than quoting a parameter name from memory.", + "expected_behavior": [ + "States that the solver printing to stdout is expected, not an error", + "Does NOT diagnose it as a misconfiguration or a logging bug", + "Does NOT invent a verbosity or log-suppression parameter name", + "If verbosity control is discussed, points to the settings documentation rather than recalling a flag" + ] + }, + { + "id": "cuopt-eval-004-settings-looked-up-not-recalled", + "question": "What is the default value and the valid range for the MILP relative gap tolerance in cuOpt, and what is the exact setting name?", + "expected_skill": "cuopt", + "expected_script": null, + "ground_truth": "The agent does not state a setting name, default or range from memory. It explains that settings names, defaults and ranges change between releases, and sources the answer from the MILP settings page in the user guide (https://docs.nvidia.com/cuopt/user-guide/latest/mip-settings.html) or by inspecting SolverSettings in the installed version. Any value it reports is attributed to one of those two sources.", + "expected_behavior": [ + "Does NOT assert a setting name, default or range purely from memory", + "States that settings change between releases", + "Routes to the MILP settings page in the user guide, not the LP/QP page", + "Offers inspecting SolverSettings in the installed build as the other source of truth" + ] + }, + { + "id": "cuopt-eval-005-install-and-gpu-support-routing", + "question": "I want to try cuOpt. How do I install it, and will it run on my GPU?", + "expected_skill": "cuopt", + "expected_script": null, + "ground_truth": "The agent routes to the install page (https://docs.nvidia.com/cuopt/user-guide/latest/install.html) for packages, channels and Docker, and to the system requirements page (https://docs.nvidia.com/cuopt/user-guide/latest/system-requirements.html) for GPU, CUDA and driver support. It does not recite a compute capability floor, driver version or CUDA version from memory, since those are release-specific and documented.", + "expected_behavior": [ + "Points to the install page for packages, channels and Docker", + "Points to the system requirements page for GPU, CUDA and driver support", + "Does NOT quote a compute capability, driver or CUDA version from memory", + "Uses the 'latest' documentation URLs rather than a pinned release version" + ] + }, + { + "id": "cuopt-eval-006-surprising-result-to-faq", + "question": "My cuOpt solve came back with a status I didn't expect and an objective value that looks wrong, and I can't tell whether it's a bug in the solver or a mistake in how I set the model up. Where do I start?", + "expected_skill": "cuopt", + "expected_script": null, + "ground_truth": "The agent directs the reader to the Common Pitfalls section of the cuOpt FAQ, which covers solver statuses and results that surprise, naming either the published page (https://docs.nvidia.com/cuopt/user-guide/latest/faq.html) or docs/cuopt/source/faq.rst in the repository. It frames these as usage-side causes worth ruling out before concluding the solver is at fault, and does not fabricate a specific status enum or its meaning.", + "expected_behavior": [ + "Routes to the Common Pitfalls section of the FAQ", + "Names the published FAQ URL or docs/cuopt/source/faq.rst in the repo", + "Suggests ruling out model-setup causes before concluding it is a solver bug", + "Does NOT invent a status value or its meaning" + ] + } +] From 0be09f2541320e8256f6eacf6d2709600ebe09c3 Mon Sep 17 00:00:00 2001 From: Ramakrishna Prabhu Date: Fri, 20 Nov 2026 15:45:10 -0600 Subject: [PATCH 3/5] Give the skill an offline path and normalize doc URLs to latest The published pages are unreachable from a sandbox, and the repo does not carry the generated Python API reference, so state a fallback order with the installed package first. Move the LinearExpression accumulation cost to the examples page. Co-Authored-By: Claude Opus 5 (1M context) Signed-off-by: Ramakrishna Prabhu --- skills/cuopt/SKILL.md | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/skills/cuopt/SKILL.md b/skills/cuopt/SKILL.md index 91569889f6..48a072ed7a 100644 --- a/skills/cuopt/SKILL.md +++ b/skills/cuopt/SKILL.md @@ -16,7 +16,7 @@ metadata: | | | |---|---| | Source | https://github.com/NVIDIA/cuopt | -| Docs (always use `latest`) | https://docs.nvidia.com/cuopt/user-guide/latest/ | +| Docs | https://docs.nvidia.com/cuopt/user-guide/latest/ | | Install, channels, Docker | https://docs.nvidia.com/cuopt/user-guide/latest/install.html | | GPU / CUDA / driver support | https://docs.nvidia.com/cuopt/user-guide/latest/system-requirements.html | | LP / QP settings | https://docs.nvidia.com/cuopt/user-guide/latest/convex-settings.html | @@ -28,8 +28,21 @@ metadata: | REST server | https://docs.nvidia.com/cuopt/user-guide/latest/cuopt-server/ | | FAQ | https://docs.nvidia.com/cuopt/user-guide/latest/faq.html | -Settings names, defaults and ranges change between releases — read them from the docs or from -`SolverSettings`, never from memory. +If a documentation URL carries a version number, replace it with `latest`. + +## When the docs are not reachable + +Sandboxes and CI containers often have no network. Work down this list: + +1. **The installed package.** Always present, and correct for the version in use. + `from cuopt.linear_programming.solver.solver_parameters import *` gives every parameter + name; `help()` and `dir()` give signatures. +2. **`docs/cuopt/source/*.rst`**, when working inside the repo. Prose only — the Python API + reference is generated at build time and is not checked in. +3. The published pages above. + +Settings names, defaults and ranges change between releases — read them from one of these, +never from memory. ## Gotchas @@ -44,7 +57,8 @@ loop, then compare it in the call; passing a bare expression raises `ValueError: addConstraint requires a Constraint object`. Constraints cannot be built as strings. **`LinearExpression` takes `constant` as a required positional**, not an optional keyword: -`LinearExpression([x, y], [1.0, 2.0], 0.0)`. Prefer ordinary arithmetic or `sum(...)` and -reach for it only when recursion depth is a concern. +`LinearExpression([x, y], [1.0, 2.0], 0.0)`. For expressions with thousands of terms, build +the lists once and pass them in a single call rather than accumulating with `sum(...)`; see +the LP / QP examples page. **The solver prints its own log to stdout.** That is expected, not an error. From f5894655872ebe5e6ff3e1a73d6b57b8632f7f23 Mon Sep 17 00:00:00 2001 From: Ramakrishna Prabhu Date: Fri, 20 Nov 2026 15:51:02 -0600 Subject: [PATCH 4/5] Shorten the offline note Co-Authored-By: Claude Opus 5 (1M context) Signed-off-by: Ramakrishna Prabhu --- skills/cuopt/SKILL.md | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/skills/cuopt/SKILL.md b/skills/cuopt/SKILL.md index 48a072ed7a..7fd78d5dbd 100644 --- a/skills/cuopt/SKILL.md +++ b/skills/cuopt/SKILL.md @@ -30,19 +30,12 @@ metadata: If a documentation URL carries a version number, replace it with `latest`. -## When the docs are not reachable +With no network access, read from the installed package — `solver_parameters` has every +parameter name and `help()` gives signatures — or, inside the repo, from +`docs/cuopt/source/*.rst`, which carries the prose pages but not the Python API reference. -Sandboxes and CI containers often have no network. Work down this list: - -1. **The installed package.** Always present, and correct for the version in use. - `from cuopt.linear_programming.solver.solver_parameters import *` gives every parameter - name; `help()` and `dir()` give signatures. -2. **`docs/cuopt/source/*.rst`**, when working inside the repo. Prose only — the Python API - reference is generated at build time and is not checked in. -3. The published pages above. - -Settings names, defaults and ranges change between releases — read them from one of these, -never from memory. +Settings names, defaults and ranges change between releases — look them up, never recall +them from memory. ## Gotchas From 698b005f14da6f7beb9cf19cba46c07392dc08b6 Mon Sep 17 00:00:00 2001 From: Ramakrishna Prabhu Date: Fri, 20 Nov 2026 15:57:17 -0600 Subject: [PATCH 5/5] Check the installed version against the docs, not the other way round Rewriting a URL to latest points at a release the reader may not be running, and no versioned path resolves anyway. Co-Authored-By: Claude Opus 5 (1M context) Signed-off-by: Ramakrishna Prabhu --- skills/cuopt/SKILL.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/skills/cuopt/SKILL.md b/skills/cuopt/SKILL.md index 7fd78d5dbd..8fd078b498 100644 --- a/skills/cuopt/SKILL.md +++ b/skills/cuopt/SKILL.md @@ -28,7 +28,8 @@ metadata: | REST server | https://docs.nvidia.com/cuopt/user-guide/latest/cuopt-server/ | | FAQ | https://docs.nvidia.com/cuopt/user-guide/latest/faq.html | -If a documentation URL carries a version number, replace it with `latest`. +These pages track the newest release — check `cuopt.__version__` when a setting's default or +range matters. With no network access, read from the installed package — `solver_parameters` has every parameter name and `help()` gives signatures — or, inside the repo, from