Repository navigation
Add a cuOpt skill bridging agents to API details and gotchas #2364
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
528424a
bc4e160
0be09f2
f589465
698b005
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| --- | ||
| 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 | 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 | | ||
|
|
||
| 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 | ||
| `docs/cuopt/source/*.rst`, which carries the prose pages but not the Python API reference. | ||
|
|
||
| Settings names, defaults and ranges change between releases — look them up, never recall | ||
| them 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)`. 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. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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.", | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Require an explicit constant, not a positional-only argument. The supplied constructor signature allows Update the reference answer and Line 22 to accept both forms. Keep the check that omitting
|
||
| "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" | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Replace the recursion-depth requirement with the actual accumulation cost.
Update this requirement and Line 20 to describe repeated list copying. Keep the recommendation to use ordinary arithmetic for two terms and construct the lists once for large expressions.
|
||
| ] | ||
| }, | ||
| { | ||
| "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" | ||
| ] | ||
| } | ||
| ] | ||
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Point the troubleshooting pointer to a section that exists.
The FAQ at this revision has no "Common Pitfalls" section, so the pointer in
skills/cuopt/SKILL.md:36-38leads to nothing. Either add that section todocs/cuopt/source/faq.rstin the same change set, or point to an existing FAQ section that answers surprising solver results. The stated dependency on#2363does not add this section.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Correct. That section comes from #2365, not #2363 — the stated dependency was wrong and the PR body is now fixed. Once #2365 merges the pointer resolves.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@ramakrishnap-nv Thanks for correcting the dependency. I’m not marking the finding as addressed yet.
Once
#2365merges, please verify that the FAQ contains Common Pitfalls before merging this PR.Learnings used
You are interacting with an AI system.