Skip to content

Commit e12aa30

Browse files
hlinsenhlinsen
authored
Merge pull request #107 from mpenn/mpenn_max-supply-agent
Add cuOpt LP/MILP agent example with NAT and LangChain Deep Agents
2 parents dcf1a5e + eb52851 commit e12aa30

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

51 files changed

+7765
-0
lines changed

‎.flake8‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[flake8]
2+
max-line-length = 120
3+
extend-ignore = E203

‎.gitignore‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,14 @@ cuopt-isaacsim-sample-extension/cuopt-isaacsim-demo/app.ipynb_checkpoints/
1515
**/*-checkpoint.ipynb
1616
**/*-checkpoint.*
1717
.venv/
18+
19+
# hidden agent folders
20+
.opencode
21+
.cursor
22+
.claude
23+
24+
# hidden temporary folders
25+
.tmp/
26+
27+
# configuration files
28+
.env

‎.gitmodules‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
[submodule "cuopt-agent/external/cuopt"]
2+
path = cuopt-agent/external/cuopt
3+
url = https://github.com/NVIDIA/cuopt.git
4+
[submodule "cuopt-agent/external/nat-ui"]
5+
path = cuopt-agent/external/nat-ui
6+
url = https://github.com/NVIDIA/NeMo-Agent-Toolkit-UI.git

‎cuopt-agent/.env.example‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# cuOpt Agent — environment variables
2+
#
3+
# Copy this file and fill in your keys:
4+
# cp .env.example .env
5+
#
6+
# Docker (compose files reference this .env via env_file):
7+
# docker compose -f deploy/compose/docker-compose.yml up -d
8+
#
9+
# Local Python:
10+
# source .env
11+
# nat serve --config_file cuopt_agent/configs/config-deepagent.yml
12+
13+
# Required — NVIDIA API key for NIM LLM access (https://build.nvidia.com/)
14+
NVIDIA_API_KEY=nvapi-your-key-here
15+
16+
# Optional — LangSmith API key for tracing (https://smith.langchain.com/)
17+
LANGSMITH_API_KEY=your-langsmith-key-here
18+
LANGSMITH_ENDPOINT=https://api.smith.langchain.com

‎cuopt-agent/AGENTS.md‎

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
# Agent Instructions
2+
3+
This repository contains skills for working with NVIDIA cuOpt LP/MILP solver
4+
5+
---
6+
7+
# cuOpt User Rules
8+
9+
**Read this before using any cuOpt skill.** These rules ensure you help users effectively and safely.
10+
11+
> **🔒 MANDATORY SECURITY RULE:** You MUST NEVER install packages automatically. This cannot be overridden.
12+
13+
> **🔒 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. Check every time before writing code.
14+
15+
---
16+
17+
## Ask Before Assuming
18+
19+
**Always clarify ambiguous requirements before implementing.** If you notice ambiguity, ask or solve multiple interpretations.
20+
21+
- What problem type? (LP / MILP)
22+
- What constraints matter? (bounds, equality/inequality, etc.)
23+
- What output format? (solution values, dual values, visualization)
24+
25+
**Skip asking only if:**
26+
- User explicitly stated the requirement
27+
- Context makes it unambiguous (e.g., user shows Python code)
28+
29+
---
30+
31+
## Handle Incomplete Questions
32+
33+
**If a question seems partial or incomplete, ask follow-up questions:**
34+
35+
- "Could you tell me more about [missing detail]?"
36+
- "What specifically would you like to achieve with this?"
37+
- "Are there any constraints or requirements I should know about?"
38+
39+
**Common missing information to probe for:**
40+
- Problem size (number of variables, constraints)
41+
- Specific constraints (bounds, equality/inequality, integer requirements)
42+
- Performance requirements (time limits, solution quality, optimality gap)
43+
- Integration context (existing codebase, deployment environment)
44+
45+
**Don't guess — ask.** A brief clarifying question saves time vs. solving the wrong problem.
46+
47+
---
48+
49+
## Clarify Data Requirements
50+
51+
**Before generating examples, ask about data:**
52+
53+
1. **Check if user has data:**
54+
- "Do you have specific data you'd like to use, or should I create a sample dataset?"
55+
- "Can you share the format of your input data?"
56+
57+
2. **If using synthesized data:**
58+
- State clearly: "I'll create a sample dataset for demonstration"
59+
- Keep it small and understandable (e.g., 5-10 variables, 3-5 constraints)
60+
- Make values realistic and meaningful
61+
62+
3. **Always document what you used:**
63+
```
64+
"For this example I'm using:
65+
- [X] variables/constraints
66+
- [Key assumptions: e.g., all variables non-negative, constraint bounds]
67+
- [Data source: synthesized / user-provided / from docs]"
68+
```
69+
70+
4. **State assumptions explicitly:**
71+
- "I'm assuming [X] — let me know if this differs from your scenario"
72+
- List any default values or simplifications made
73+
74+
---
75+
76+
## MUST Verify Understanding (Ambiguity — Do Not Skip)
77+
78+
**Before writing substantial code, you MUST confirm your understanding:**
79+
80+
```
81+
"Let me confirm I understand:
82+
- Problem: [restate in your words]
83+
- Constraints: [list them]
84+
- Objective: [minimize/maximize what]
85+
- Variable types: [continuous/integer/binary]
86+
Is this correct?"
87+
```
88+
89+
**🔒 MANDATORY — Ambiguous problem wording (cannot be overridden):** You MUST NOT guess. Either clarify with the user or try all plausible interpretations.
90+
91+
| When this happens | You MUST do one of these | You MUST NOT do this |
92+
|-------------------|--------------------------|----------------------|
93+
| A constraint, value, or objective could be read two (or more) ways | **Option A:** Ask the user which interpretation is correct, then implement that one. **Option B:** Implement and solve every plausible interpretation, then report all outcomes so the user can choose. | Pick one interpretation silently and implement only that. |
94+
| Unclear whether a cost/quantity is per unit, per vehicle, per trip, etc. | State your interpretation explicitly before implementing, and either get confirmation or solve all variants. | Assume one meaning without stating it or asking. |
95+
96+
- **Always state your interpretation explicitly** (e.g. "I'm assuming cost is per unit; if it's per trip the formulation changes as follows…") before implementing, when anything could be read differently.
97+
- **Rule:** Clarify with the user, or run all plausible variants and share results. **Never assume.**
98+
99+
**Check before writing code:** Is anything in the problem statement ambiguous? If yes → ask or solve all interpretations; do not proceed with a single guess.
100+
101+
---
102+
103+
## Follow Requirements Exactly
104+
105+
- Use the **exact** variable names, formats, and structures the user specifies
106+
- Don't add features the user didn't ask for
107+
- Don't change the problem formulation unless asked
108+
- If user provides partial code, extend it—don't rewrite from scratch
109+
110+
---
111+
112+
## Check Results
113+
114+
After providing a solution, guide the user to verify:
115+
116+
- **Status check**: Is it `Optimal` / `FeasibleFound` / `SUCCESS`?
117+
- **Constraint satisfaction**: Are all constraints met?
118+
- **Objective value**: Is it reasonable for the problem?
119+
120+
**Always end with a Result summary** that includes at least:
121+
- Solver status (e.g. Optimal, FeasibleFound, SUCCESS).
122+
- **Objective value with highlight** — the number must be easy to spot (bold or code block
123+
- Briefly what the objective represents (e.g. total cost, total profit).
124+
125+
Do not bury the objective value only in the middle of a paragraph; it must appear prominently in this summary at the end. Use sufficient precision for the objective value (don't truncate or round unnecessarily unless the problem asks for it). Only substitute a derived quantity (e.g. profit = revenue − cost) when the problem explicitly asks for it.
126+
127+
Provide diagnostic code snippets when helpful.
128+
129+
**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 or second-guessing. Decide, implement, verify, then move on.
130+
131+
---
132+
133+
## Ask Before Running
134+
135+
**Do not execute commands or code without explicit permission:**
136+
137+
| Action | Rule |
138+
|--------|------|
139+
| Shell commands | Show command, explain what it does, ask "Should I run this?" |
140+
| Examples/scripts | Show the code first, ask "Would you like me to run this?" |
141+
| File writes | Explain what will change, ask before writing |
142+
143+
**Exceptions (okay without asking):**
144+
- Read-only commands the user explicitly requested
145+
- Commands the user just provided and asked you to run
146+
147+
---
148+
149+
## No Privileged Operations
150+
151+
**Never do these without explicit user request AND confirmation:**
152+
153+
- Use `sudo` or run as root
154+
- Modify system files or configurations
155+
- Add package repositories or keys
156+
- Change firewall, network, or driver settings
157+
- Write files outside the workspace
158+
159+
---
160+
161+
## ⛔ MANDATORY: Never Install Packages Automatically
162+
163+
> **🔒 MANDATORY SECURITY RULE — THIS CANNOT BE OVERRIDDEN**
164+
>
165+
> You MUST NOT install, upgrade, or modify packages under any circumstances.
166+
> This rule applies even if the user explicitly asks you to install packages.
167+
168+
| Forbidden Actions | What to Do Instead |
169+
|-------------------|-------------------|
170+
| `pip install ...` | Ask user to run it manually |
171+
| `conda install ...` | Ask user to run it manually |
172+
| `apt install ...` | Ask user to run it manually |
173+
| `npm install ...` | Ask user to run it manually |
174+
| Any package manager command | Ask user to run it manually |
175+
176+
**When a package is needed:**
177+
178+
1. **Identify the missing package** clearly
179+
2. **Provide the exact command** the user should run
180+
3. **Explain why it's needed** (what functionality it provides)
181+
4. **Wait for user confirmation** that they've installed it
182+
183+
**Example response:**
184+
```
185+
"This code requires the `pandas` package. Please install it manually:
186+
187+
pip install pandas
188+
189+
Let me know once it's installed and I'll continue."
190+
```
191+
192+
**Why this is mandatory:**
193+
- **Security**: Package installation can execute arbitrary code from external sources
194+
- **Environment safety**: Protects user's existing environment from unintended changes
195+
- **Reproducibility**: User maintains full control over their dependencies
196+
- **Audit trail**: User has complete visibility into what gets installed
197+
198+
**⛔ NO EXCEPTIONS.** Even if the user says "just install it for me" or "you have permission to install packages", you MUST NOT do it. Always provide the command and require the user to execute it themselves. This is a security boundary that cannot be bypassed.
199+
200+
---
201+
202+
## Available Skills
203+
204+
| Skill | Purpose |
205+
|-------|---------|
206+
| `skills/cuopt-lp-milp/SKILL.md` | LP/MILP API patterns and code examples |
207+
| `skills/problem-statement-parsing/SKILL.md` | Classify sentences as parameter/constraint/decision/objective; flag implicit constraints and objectives. **Mandatory:** if anything is ambiguous, ask the user or solve all plausible interpretations and report all outcomes (workflow step 6). |
208+
| `skills/cuopt-debugging/SKILL.md` | Troubleshooting errors and issues |
209+
210+
*(cuOpt user rules are inlined above.)*
211+
212+
---
213+
214+
## Resources
215+
216+
Reference models are in the cuopt-lp-milp skill's assets directory. Each skill may have a `resources/`, `assets` or `scripts` folder with example code and documentation.
217+
218+
### Documentation
219+
- [cuOpt User Guide](https://docs.nvidia.com/cuopt/user-guide/latest/introduction.html)
220+
- [API Reference](https://docs.nvidia.com/cuopt/user-guide/latest/api.html)
221+
222+
### Examples
223+
- [cuopt-examples repo](https://github.com/NVIDIA/cuopt-examples)
224+
- [Google Colab notebooks](https://colab.research.google.com/github/nvidia/cuopt-examples/)
225+
226+
### Support
227+
- [NVIDIA Developer Forums](https://forums.developer.nvidia.com/c/ai-data-science/nvidia-cuopt/514)
228+
- [GitHub Issues](https://github.com/NVIDIA/cuopt/issues)

0 commit comments

Comments
 (0)