Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 0 additions & 8 deletions .agents/rules/cuopt-skill-evolution.mdc

This file was deleted.

44 changes: 1 addition & 43 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,63 +4,21 @@
"name": "NVIDIA"
},
"metadata": {
"description": "Agent skills for NVIDIA cuOpt: routing (VRP, TSP, PDP), LP/MILP/QP, installation (user/developer), and REST server.",
"description": "Agent skills for NVIDIA cuOpt: contributing to the cuOpt codebase, and multi-objective exploration over repeated solves.",
"version": "26.12.00"
},
"plugins": [
{
"name": "cuopt-user-rules",
"source": "./skills/cuopt-user-rules",
"skills": "./",
"description": "Base rules for end users calling NVIDIA cuOpt (routing/LP/MILP/QP/install/server). Not for cuOpt internals — use cuopt-developer for those."
},
{
"name": "cuopt-developer",
"source": "./skills/cuopt-developer",
"skills": "./",
"description": "Modify, build, test, debug, and contribute to NVIDIA cuOpt (C++/CUDA, Python, server, CI). Use for solver internals, PRs, DCO, and code conventions."
},
{
"name": "cuopt-install",
"source": "./skills/cuopt-install",
"skills": "./",
"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."
},
{
"name": "cuopt-numerical-optimization-formulation",
"source": "./skills/cuopt-numerical-optimization-formulation",
"skills": "./",
"description": "Numerical optimization (LP, MILP, QP) — concepts, problem-text parsing, and formulation patterns. What LP, MILP, and QP are, required formulation questions, modeling elements, common patterns, and how to parse problem statements (parameters, constraints, decisions, objective). Domain concepts; no API or interface."
},
{
"name": "cuopt-numerical-optimization-api",
"source": "./skills/cuopt-numerical-optimization-api",
"skills": "./",
"description": "LP, MILP, and QP (beta) with cuOpt — Python, C, and CLI. Use when the user is solving LP, MILP, or QP with any cuOpt interface."
},
{
"name": "cuopt-multi-objective-exploration",
"source": "./skills/cuopt-multi-objective-exploration",
"skills": "./",
"description": "Trace and interpret the Pareto frontier across competing objectives using repeated single-objective cuOpt solves (weighted-sum and ε-constraint)."
},
{
"name": "cuopt-routing-api-python",
"source": "./skills/cuopt-routing-api-python",
"skills": "./",
"description": "Vehicle routing (VRP, TSP, PDP) with cuOpt — Python API only. Use when the user is building or solving routing in Python."
},
{
"name": "cuopt-server-api-python",
"source": "./skills/cuopt-server-api-python",
"skills": "./",
"description": "cuOpt REST server — start server, endpoints, Python/curl client examples. Use when the user is deploying or calling the REST API."
},
{
"name": "cuopt-skill-evolution",
"source": "./skills/cuopt-skill-evolution",
"skills": "./",
"description": "After solving a non-trivial problem, detect generalizable learnings and propose skill updates. Always active."
}
]
}
48 changes: 22 additions & 26 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,41 +1,37 @@
# AGENTS.md — cuOpt AI Agent Entry Point

AI agent skills for NVIDIA cuOpt optimization engine. Skills live in **`skills/`** (repo root) and use a **flat layout**: per domain, a concept skill (formulation / problem types) plus implementation skills — typically one per interface (Python, C, CLI, server), or consolidated when the content is shared across interfaces (e.g. installation). Skills evolve through agent interactions — see `skills/cuopt-skill-evolution/` for the evolution workflow.
NVIDIA cuOpt solves LP, MILP, QP (beta) and vehicle routing on the GPU.

**Start with the documentation.** It is the current, authoritative reference for installation,
system requirements, solver settings, and every interface:
<https://docs.nvidia.com/cuopt/user-guide/latest/>

Skills live in **`skills/`** (repo root), flat layout. There are deliberately few of them: a
skill should exist only when it carries something the documentation does not, because every
skill costs agent context on tasks that may not need it.

> **🔒 MANDATORY — Ambiguity:** When the problem could be read more than one way, you MUST either **ask the user to clarify** or **solve every plausible interpretation and report all outcomes**. Never pick one interpretation silently.

## Skills directory (flat)

### 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`.
- `skills/cuopt-skill-evolution/` — Skill evolution: after solving a non-trivial problem, propose skill updates to capture generalizable learnings.

### Common (concepts only; no API code)
- `skills/cuopt-numerical-optimization-formulation/` — LP / MILP / QP: concepts + problem parsing + common formulation patterns
- `skills/cuopt-multi-objective-exploration/` — Multi-objective: trace + interpret the Pareto frontier across competing objectives (ε-constraint / weighted-sum over repeated cuOpt solves)

### Installation
- `skills/cuopt-install/` — User install for Python, C, and server (pip, conda, Docker, verification). For building cuOpt from source, see `skills/cuopt-developer/`.

### API (implementation)
- `skills/cuopt-numerical-optimization-api/` (LP, MILP, QP — Python, C, CLI; interface-specific details in `references/`)
- `skills/cuopt-routing-api-python/`
- `skills/cuopt-server-api-python/` (deploy + client)

## Skill evolution
- `skills/cuopt-multi-objective-exploration/` — Multi-objective: trace and interpret the Pareto frontier across competing objectives (ε-constraint / weighted-sum over repeated cuOpt solves).

Skills improve through agent interactions. When you solve a problem and discover a generalizable fix, gotcha, or pattern, follow `skills/cuopt-skill-evolution/SKILL.md` to propose a skill update. All proposals go through the same CI validation as manual edits.
## Using cuOpt

### Post-correction hook (mandatory)
For installing cuOpt, writing models against the Python/C/CLI/server interfaces, choosing
solver settings, or understanding termination statuses, read the user guide:

After completing any task where one of these occurred, you MUST read `skills/cuopt-skill-evolution/SKILL.md` and evaluate whether to propose a skill update:
- The user corrected your output or approach
- Your initial solution failed and you had to retry with a different approach
- You discovered undocumented API behavior or a non-obvious gotcha
- You used a workaround not described in any existing skill
- [Install](https://docs.nvidia.com/cuopt/user-guide/latest/install.html)
- [System requirements](https://docs.nvidia.com/cuopt/user-guide/latest/system-requirements.html)
- [Python API](https://docs.nvidia.com/cuopt/user-guide/latest/cuopt-python/)
- [REST server](https://docs.nvidia.com/cuopt/user-guide/latest/cuopt-server/)
- [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)
- [FAQ](https://docs.nvidia.com/cuopt/user-guide/latest/faq.html)

Finish solving the problem first, then evaluate. Not every correction warrants a proposal — only generalizable learnings that would help future interactions.
If the documentation is missing something or is wrong, the fix belongs in the docs — please
open an issue rather than adding it here.

## Resources

Expand Down
4 changes: 2 additions & 2 deletions skills/cuopt-developer/benchmark/evals.json
Original file line number Diff line number Diff line change
Expand Up @@ -663,10 +663,10 @@
"question": "I just want to use cuOpt to solve an LP. Should I follow this developer-installation skill?",
"expected_skill": "cuopt-developer",
"expected_script": null,
"ground_truth": "No \u2014 this skill is for building cuOpt from source to contribute or modify it. To just use cuOpt, the agent points to the user installation skill (cuopt-install) which uses pre-built pip / conda / Docker packages rather than a from-source build. The user path is much simpler and does not require setting up a development environment.",
"ground_truth": "No \u2014 this skill is for building cuOpt from source to contribute or modify it. To just use cuOpt, the agent points to the installation documentation, which uses pre-built pip / conda / Docker packages rather than a from-source build. The user path is much simpler and does not require setting up a development environment.",
"expected_behavior": [
"Identifies that the developer install is for building/contributing, not using",
"Points to cuopt-install as the user path",
"Points to the installation docs as the user path",
"Mentions pre-built pip / conda / Docker packages for the user path",
"Does not start walking the user through ./build.sh"
]
Expand Down
102 changes: 0 additions & 102 deletions skills/cuopt-install/BENCHMARK.md

This file was deleted.

141 changes: 0 additions & 141 deletions skills/cuopt-install/SKILL.md

This file was deleted.

Loading
Loading